net.rim.device.api.system
Class Application

java.lang.Object
  |
  +--net.rim.device.api.system.Application
Direct Known Subclasses:
UiApplication

public abstract class Application
extends Object

The base class for all device applications. There should only be one Application instance per process.

Applications which do not require any user interaction may be derived directly from this class. Applications which require user interaction should be derived from UiApplication.

An application can synchronize with the event lock (returned by getEventLock()) to serialize operations with the event dispatcher.

See Also:
ApplicationDescriptor, ApplicationManager

Constructor Summary
protected Application()
          Constructs a new Application instance.
 
Method Summary
protected  boolean acceptsForeground()
          Determines if this application can function in the foreground.
 boolean acceptsKeyUpEvents()
          Determines if this application receives KeyListener.keyUp(int, int) events.
 void activate()
          Handles foregrounding event.
 void addAlertListener(AlertListener listener)
          Adds an alert listener to this application.
 void addFileSystemJournalListener(FileSystemJournalListener listener)
          Adds an file system event journal listener to this application.
 void addFileSystemListener(FileSystemListener listener)
          Adds an file system event listener to this application.
 void addGlobalEventListener(GlobalEventListener listener)
          Adds a global event listener to this application.
 void addHolsterListener(HolsterListener listener)
          Adds a holster event listener to this application.
 void addIOPortListener(IOPortListener listener)
          Adds an I/O port event listener to this application.
 void addKeyListener(KeyListener listener)
          Adds a key event listener to this application.
 void addPeripheralListener(PeripheralListener listener)
          Deprecated.  
 void addRadioListener(int WAFFilter, RadioListener listener)
          Adds a radio event listener to this application.
 void addRadioListener(RadioListener listener)
          Adds a radio event listener to this application.
 void addRealtimeClockListener(RealtimeClockListener listener)
          Adds a real-time clock event listener to this application.
 void addSystemListener(SystemListener listener)
          Adds a system event listener to this application.
 void addTrackwheelListener(TrackwheelListener listener)
          Adds a trackwheel event listener to this application.
 void cancelInvokeLater(int id)
          Cancels a runnable timed to invoke later.
 void deactivate()
          Handles backgrounding event.
 void enableKeyUpEvents(boolean enable)
          Allows this application to receive KeyListener.keyUp(int, int) events.
 void enterEventDispatcher()
          Enters the event dispatcher.
 Object getAppEventLock()
          Retrieves the application event lock for this application.
static Application getApplication()
          Retrieves the current application instance.
static Object getEventLock()
          Retrieves the application user interface event lock.
 int getProcessId()
          Retrieves the process ID for this application.
 boolean hasEventThread()
          Determines if this application has entered the event dispatcher.
 void invokeAndWait(Runnable runnable)
          Puts runnable object into this application's event queue, and waits until it is processed.
 void invokeLater(Runnable runnable)
          Puts runnable object into this application's event queue.
 int invokeLater(Runnable runnable, long time, boolean repeat)
          Puts runnable object into this application's event queue for repeated execution.
 boolean isAlive()
          Determines if this application's process is still alive.
static boolean isEventDispatchThread()
          Determines if this is the event dispatching thread.
 boolean isEventThread()
          Determines if this is the event dispatching thread.
 boolean isForeground()
          Determines if this application is in the foreground.
 boolean isHandlingEvents()
          Determines if this application has entered the event dispatch loop.
 void removeAlertListener(AlertListener listener)
          Removes an alert listener from this application.
 void removeFileSystemJournalListener(FileSystemJournalListener listener)
          Removes a file system journal listener from this application.
 void removeFileSystemListener(FileSystemListener listener)
          Removes a file system listener from this application.
 void removeGlobalEventListener(GlobalEventListener listener)
          Removes a global event listener from this application.
 void removeHolsterListener(HolsterListener listener)
          Removes a holster event listener from this application.
 void removeIOPortListener(IOPortListener listener)
          Removes an I/O port event listener from this application.
 void removeKeyListener(KeyListener listener)
          Removes a key event listener from this application.
 void removePeripheralListener(PeripheralListener listener)
          Deprecated.  
 void removeRadioListener(RadioListener listener)
          Removes a radio event listener from this application.
 void removeRealtimeClockListener(RealtimeClockListener listener)
          Removes a real-time clock event listener from this application.
 void removeSystemListener(SystemListener listener)
          Removes a system event listener from this application.
 void removeTrackwheelListener(TrackwheelListener listener)
          Removes a trackwheel event listener from this application.
 void requestBackground()
          Requests to have this application sent to the background.
 void requestForeground()
          Requests to have this application brought to the foreground.
 void setAcceptEvents(boolean on)
          Determines if this application accepts system events.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Application

protected Application()
Constructs a new Application instance.
Throws:
RuntimeException - if an instance of Application already exists in the current application.
Method Detail

acceptsForeground

protected boolean acceptsForeground()
Determines if this application can function in the foreground.

Note that this method returns false by default; classes that extend Application should override this method to return true. They furnish applications that can handle foregrounding (that is, applications presenting an interface to the user).

Returns:
True if this application can be pushed into the foreground; otherwise, false.
See Also:
UiApplication

acceptsKeyUpEvents

public final boolean acceptsKeyUpEvents()
Determines if this application receives KeyListener.keyUp(int, int) events.

By default, applications do not receive these events for performance reasons.

Returns:
True if this application receives keyUp events; otherwise, false.
Since:
JDE 4.0.0

activate

public void activate()
Handles foregrounding event.

The system invokes this method when it brings this application to the foreground. By default, this method does nothing. Override this method to perform additional processing when being brought to the foreground.


addAlertListener

public void addAlertListener(AlertListener listener)
Adds an alert listener to this application.
Parameters:
listener - Alert listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
JDE 3.6.0

addFileSystemJournalListener

public void addFileSystemJournalListener(FileSystemJournalListener listener)
Adds an file system event journal listener to this application.
Parameters:
listener - File system journal event listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
JDE 4.2.0

addFileSystemListener

public void addFileSystemListener(FileSystemListener listener)
Adds an file system event listener to this application.
Parameters:
listener - File system event listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
JDE 4.2.0

addGlobalEventListener

public void addGlobalEventListener(GlobalEventListener listener)
Adds a global event listener to this application.
Parameters:
listener - Global event listener to register for this application.
Throws:
NullPointerException - if listener is null.

addHolsterListener

public void addHolsterListener(HolsterListener listener)
Adds a holster event listener to this application.
Parameters:
listener - Holster event listener to register for this application.
Throws:
NullPointerException - if listener is null.

addIOPortListener

public void addIOPortListener(IOPortListener listener)
Adds an I/O port event listener to this application.
Parameters:
listener - I/O port event listener to register for this application.
Throws:
NullPointerException - if listener is null.

addKeyListener

public void addKeyListener(KeyListener listener)
Adds a key event listener to this application.
Parameters:
listener - Key event listener to register for this application.
Throws:
NullPointerException - if listener is null.

addPeripheralListener

public void addPeripheralListener(PeripheralListener listener)
Deprecated.  

Adds a peripheral listener to this application.
Parameters:
listener - Peripheral event listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
JDE 3.6.0

addRadioListener

public void addRadioListener(int WAFFilter,
                             RadioListener listener)
Adds a radio event listener to this application. The listener will only receive events generated by radios belonging to the provided Wireless Access Families.
Parameters:
WAFFilter - A bitmask of RadioInfo.WAF_* flags indicating the Wireless Access Families for this listener.
listener - Radio event listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
JDE 4.2.1
See Also:
RadioInfo

addRadioListener

public void addRadioListener(RadioListener listener)
Adds a radio event listener to this application.
Parameters:
listener - Radio event listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
JDE 3.6.0

addRealtimeClockListener

public void addRealtimeClockListener(RealtimeClockListener listener)
Adds a real-time clock event listener to this application.
Parameters:
listener - Real-time clock event listener to register for this application.
Throws:
NullPointerException - if listener is null.

addSystemListener

public void addSystemListener(SystemListener listener)
Adds a system event listener to this application.
Parameters:
listener - System event listener to register for this application.
Throws:
NullPointerException - if listener is null.

addTrackwheelListener

public void addTrackwheelListener(TrackwheelListener listener)
Adds a trackwheel event listener to this application.
Parameters:
listener - Trackwheel event listener to register for this application.
Throws:
NullPointerException - if listener is null.

cancelInvokeLater

public final void cancelInvokeLater(int id)
Cancels a runnable timed to invoke later.

Use this method to remove a runnable object inserted into the event queue (if currently in the queue), and cancel the operation to insert it into the queue in the future.

Parameters:
id - Event ID of the runnable returned by invokeLater(Runnable,long,boolean).

deactivate

public void deactivate()
Handles backgrounding event.

The system invokes this method when sending this application to the background. By default, this method does nothing. Override this method to perform additional processing when being sent to the background.


enableKeyUpEvents

public final void enableKeyUpEvents(boolean enable)
Allows this application to receive KeyListener.keyUp(int, int) events.

By default, applications do not receive these events for performance reasons.

Parameters:
enable - If true, this application will receive keyup events from the system; otherwise, the system will continue to withold them from this application.

enterEventDispatcher

public void enterEventDispatcher()
Enters the event dispatcher.

The thread that calls this method (typically the main thread in the application) becomes the event-dispatching thread, which will execute all drawing and event-handling code.

Note that under normal circumstances this method does not return.

Throws:
IllegalStateException - if this method is invoked after the event thread has already been entered; that is, if isHandlingEvents() returns true.

getAppEventLock

public final Object getAppEventLock()
Retrieves the application event lock for this application.
Returns:
Application event lock.
See Also:
getEventLock()

getApplication

public static final Application getApplication()
Retrieves the current application instance.
Returns:
Current application instance.
Throws:
IllegalStateException - If this function is called when there is no Application object in the process.

getEventLock

public static final Object getEventLock()
Retrieves the application user interface event lock.

Worker threads should synchronize on this thread if they wish to execute code serialized with the event thread. Your worker thread should hold the lock only for a short period of time, as this action pauses the thread dispatcher.

Any operation involving the device's user interface must be done with the lock held. The UI system also guarantees that any methods it invokes will execute on a thread that already has the lock.

An application should never call notify or wait on this object.

Returns:
Application event lock; returns exactly Application.getApplication().getAppEventLock().
Throws:
IllegalStateException - If this method is called when there is no Application object in the process.

getProcessId

public final int getProcessId()
Retrieves the process ID for this application.
Returns:
Process identifier for this application.

hasEventThread

public boolean hasEventThread()
Determines if this application has entered the event dispatcher.
Returns:
True if this application has entered the event dispatcher (i.e. has invoked enterEventDispatcher()); otherwise, false.

invokeAndWait

public final void invokeAndWait(Runnable runnable)
Puts runnable object into this application's event queue, and waits until it is processed.

Invoke this method, passing a runnable object, to have that object's run() method invoked on the dispatch thread, after all pending events are processed.

This method blocks until the insert event is processed (that is, until the runnable object's run() method returns).

It is safe to call this method on the event dispatch thread. In this case the runnable will be executed immediately.

If there is no event dispatch thread (ie. hasEventThread() returns false), then the last item to be queued is dropped when the queue surpasses its size limit. Note: If an application does not have an event thread, you may invoke setAcceptEvents(boolean) to inform the runtime system that the application no longer accepts events. All events queued to that application are then discarded.

Parameters:
runnable - Runnable object to be placed on the dispatch thread's queue of events for synchronous execution.
Throws:
NullPointerException - if runnable is null.

invokeLater

public final void invokeLater(Runnable runnable)
Puts runnable object into this application's event queue.

Invoke this method, passing a runnable object, to have that object's run() method invoked on the dispatch thread, after all pending events are processed.

If there is no event dispatch thread (ie. hasEventThread() returns false), then the last item to be queued is dropped when the queue surpasses its size limit. Note: If an application does not have an event thread, you may invoke setAcceptEvents(boolean) to inform the runtime system that the application no longer accepts events. All events queued to that application are then discarded.

Parameters:
runnable - Runnable object to be placed on the dispatch thread's queue of events to execute.
Throws:
NullPointerException - if runnable is null.

invokeLater

public final int invokeLater(Runnable runnable,
                             long time,
                             boolean repeat)
Puts runnable object into this application's event queue for repeated execution.

Invoke this method, passing a runnable object and schedule parameters, to have the object's run() method repeatedly invoked on the dispatch thread, after all pending events are processed.

Note that you should make sparing use of this this method, as each application has a limited number of timers. If this application currently has no timers available, this method returns -1.

If there is no event dispatch thread (ie. hasEventThread() returns false), then the last item to be queued is dropped when the queue surpasses its size limit. Note: If an application does not have an event thread, you may invoke setAcceptEvents(boolean) to inform the runtime system that the application no longer accepts events. All events queued to that application are then discarded.

Parameters:
runnable - Runnable object to be placed on the dispatch thread's queue of events to execute.
time - Number of milliseconds to wait before adding the runnable object to the event queue. If the repeat parameter is true, then this method continually re-adds your runnable object to the queue, pausing this number of milliseconds between each insertion.
repeat - If true, the runnable object will be added to the event queue after each period of milliseconds specified by the time parameter. If false, the runnable will be added only once.
Returns:
ID of the event, or -1 if there are no timers available.
Throws:
NullPointerException - if runnable is null.
IllegalArgumentException - if time is less than or equal to zero.

isAlive

public boolean isAlive()
Determines if this application's process is still alive.
Returns:
True if this application's process is still alive; otherwise, false.
Since:
JDE 4.0.0

isEventDispatchThread

public static final boolean isEventDispatchThread()
Determines if this is the event dispatching thread.

Note: this method simply invokes isEventThread() on the current process's Application object.

Returns:
True if the invoking thread is the event dispatch thread; otherwise false.
Throws:
IllegalStateException - If this method is called when there is no Application object in the process.

isEventThread

public boolean isEventThread()
Determines if this is the event dispatching thread.
Returns:
True if the invoking thread is the event dispatch thread; otherwise false.

isForeground

public final boolean isForeground()
Determines if this application is in the foreground.
Returns:
True if this application is in the foreground; otherwise, false.

isHandlingEvents

public final boolean isHandlingEvents()
Determines if this application has entered the event dispatch loop.
Returns:
True if the application has entered the event dispatch loop; otherwise, false.

removeAlertListener

public void removeAlertListener(AlertListener listener)
Removes an alert listener from this application.
Parameters:
listener - Alert listener to de-register for this application.
Since:
JDE 3.6.0

removeFileSystemJournalListener

public void removeFileSystemJournalListener(FileSystemJournalListener listener)
Removes a file system journal listener from this application.
Parameters:
listener - File system journal event listener to de-register for this application.
Since:
JDE 4.2.0

removeFileSystemListener

public void removeFileSystemListener(FileSystemListener listener)
Removes a file system listener from this application.
Parameters:
listener - File system event listener to de-register for this application.
Since:
JDE 4.2.0

removeGlobalEventListener

public void removeGlobalEventListener(GlobalEventListener listener)
Removes a global event listener from this application.
Parameters:
listener - Global event listener to de-register for this application.

removeHolsterListener

public void removeHolsterListener(HolsterListener listener)
Removes a holster event listener from this application.
Parameters:
listener - Holster event listener to de-register for this application.

removeIOPortListener

public void removeIOPortListener(IOPortListener listener)
Removes an I/O port event listener from this application.
Parameters:
listener - I/O port event listener to de-register for this application.

removeKeyListener

public void removeKeyListener(KeyListener listener)
Removes a key event listener from this application.
Parameters:
listener - Key event listener to de-register for this application.

removePeripheralListener

public void removePeripheralListener(PeripheralListener listener)
Deprecated.  

Removes a peripheral listener from this application.
Parameters:
listener - Peripheral event listener to de-register for this application.
Since:
JDE 3.6.0

removeRadioListener

public void removeRadioListener(RadioListener listener)
Removes a radio event listener from this application.
Parameters:
listener - Radio event listener to de-register for this application.
Since:
JDE 3.6.0

removeRealtimeClockListener

public void removeRealtimeClockListener(RealtimeClockListener listener)
Removes a real-time clock event listener from this application.
Parameters:
listener - Real-time clock event listener to de-register from this application.

removeSystemListener

public void removeSystemListener(SystemListener listener)
Removes a system event listener from this application.
Parameters:
listener - System event listener to de-register for this application.

removeTrackwheelListener

public void removeTrackwheelListener(TrackwheelListener listener)
Removes a trackwheel event listener from this application.
Parameters:
listener - Trackwheel event listener to de-register for this application.

requestBackground

public final void requestBackground()
Requests to have this application sent to the background.

The deactivate() method will be invoked when the switch to the background actually occurs. If the application is not in the foreground when you invoke this method, this method does nothing.


requestForeground

public final void requestForeground()
Requests to have this application brought to the foreground.

The activate() method will be invoked when the switch to the foreground actually occurs. If this application is already in the foreground when the request is granted, this method does nothing.


setAcceptEvents

public final void setAcceptEvents(boolean on)
Determines if this application accepts system events.

An application can use this method to turn off and on accepting of events from the system. A long running application that does not need to handle events (e.g., a non-ui background process) should invoke this method and pass it false, rather than invoking enterEventDispatcher().

Invoking this method to turn off events also flushes the event queue.

Parameters:
on - True to accept system events; false to tell the system not to pass them to this application.



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.