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 Application.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() Deprecated. KEY_UP events are now always sent.
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) Deprecated.
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	addKeyListener(KeyListener listener, boolean excludeFromUnhandledGlobalKeyEvents) Adds a key event listener to this application.
boolean	addMediaActionHandler(MediaActionHandler handler) Adds a MediaActionHandler to this applicaton's list of media actions handlers.
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) Deprecated. Use Screen.navigationClick(int, int) or Screen.navigationMovement(int, int, int, int) instead.
void	cancelInvokeLater(int id) Cancels a runnable timed to invoke later.
void	deactivate() Handles backgrounding event.
void	enableKeyUpEvents(boolean enable) Deprecated. KEY_UP events are now always sent.
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.
ServiceMode	getServiceMode() Get the current service mode 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.
boolean	isInTouchCompatibilityMode() Returns whether app is running in touch compatibility mode (always show keyboard, disable rotation, 320x240 screen).
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) Deprecated.
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	removeMediaActionHandler(MediaActionHandler handler) Removes a MediaActionHandler from this applicaton's list of media actions handlers.
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) Deprecated. Use Screen.navigationClick(int, int) or Screen.navigationMovement(int, int, int, int) instead.
void	requestBackground() Requests to have this application sent to the background.
boolean	requestClose() Individual apps can handle this new API call by cleaning up and then closing themselves, if they so desire.
void	requestForeground() Requests to have this application brought to the foreground.
void	setAcceptEvents(boolean on) Determines if this application accepts system events.
void	setServiceMode(ServiceMode serviceMode) Set the current service mode for this application.
protected void	setServiceModeImpl(ServiceMode serviceMode) The implementation method backing the Application.setServiceMode(ServiceMode) method used to set the current service mode for this application.
boolean	shouldAppearInApplicationSwitcher() Determines if this application should appear in the Application Switcher.
boolean	suggestServiceMode(ServiceMode serviceMode) Suggest a new service mode for this application.

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

getServiceMode

public ServiceMode getServiceMode()

Get the current service mode for this application. The return value should be a service mode that is representative of the data currently being managed by the application. If an application can manage data from multiple services and is currently in a state for which an appropriate service cannot be determined then the service mode should reflect this.

It is expected that this method be overridden to provide the desired implementation. By default this method will return null.

Note that this method should only be used by components internal to the application. For components external to the application MultiServicePlatformManager.getApplicationServiceMode() should be used instead.

Returns:

the current service mode for this application; may be null

Since:

BlackBerry API 7.0.0

setServiceMode

public final void setServiceMode(ServiceMode serviceMode)

Set the current service mode for this application.

This method is used to change the current service mode for an application. When this method is called the application must change its current service mode to the new specified service mode.

Note that the application's service mode can only be modified by a core platform module or a module that the application explicitly depends on.

Parameters:

serviceMode - the new service mode for this application; may be null

Throws:

ControlledAccessException - if the caller is not allowed to modify this application's service mode

See Also:

Application.setServiceModeImpl(ServiceMode)

Since:

BlackBerry API 7.0.0

setServiceModeImpl

protected void setServiceModeImpl(ServiceMode serviceMode)

The implementation method backing the Application.setServiceMode(ServiceMode) method used to set the current service mode for this application.

It is expected that this method be overridden to provide the desired implementation of the setServiceMode(ServiceMode) method.

Parameters:

serviceMode - the new service mode for this application; may be null

See Also:

Application.setServiceMode(ServiceMode)

Since:

BlackBerry API 7.0.0

suggestServiceMode

public boolean suggestServiceMode(ServiceMode serviceMode)

Suggest a new service mode for this application.

This method is used to suggest to an application a more appropriate service mode to operate in. This can happen as a result of data being passed to the application from an external source that is associated with another service. As part of passing this data a suggestion to operate in the mode associated the data may be made.

Note that the application does not need to always accept the suggested service mode. It is acceptable for the application to reject suggestions.

It is expected that this method be overridden to provide the desired implementation. The default behavior is to reject all suggestions.

Parameters:

serviceMode - the new service mode being suggested for this application; may be null

Returns:

true if the new mode was accepted; false, otherwise

Since:

BlackBerry API 7.0.0

isInTouchCompatibilityMode

public boolean isInTouchCompatibilityMode()

Returns whether app is running in touch compatibility mode (always show keyboard, disable rotation, 320x240 screen).

Returns:

True if app is in touch compatibility mode, otherwise false

Since:

BlackBerry API 4.7.0

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

shouldAppearInApplicationSwitcher

public boolean shouldAppearInApplicationSwitcher()

Determines if this application should appear in the Application Switcher.

Note that this method returns the value of acceptsForeground() by default. This is the method the Application Switcher used to populate itself before this method was added. However, there are applications that have other criteria for deciding when they wish to appear in the Application Switcher that aren't necessarily based on the ability of the application to take the foreground. This method decouples these two concepts. Classes that extend Application can override this method to base this decision on other criteria.

Returns:

True if this application should appear in the Application Switcher, false otherwise.

Since:

BlackBerry API 6.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.

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.

isForeground

public final boolean isForeground()

Determines if this application is in the foreground.

Returns:

True if this application is in the foreground; otherwise, false.

requestBackground

public final void requestBackground()

Requests to have this application sent to the background.

The Application.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 Application.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.

enableKeyUpEvents

public final void enableKeyUpEvents(boolean enable)

Deprecated. KEY_UP events are now always sent.

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.

acceptsKeyUpEvents

public final boolean acceptsKeyUpEvents()

Deprecated. KEY_UP events are now always sent.

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:

BlackBerry API 4.0.0

addKeyListener

public void addKeyListener(KeyListener listener)

Adds a key event listener to this application. When a key listener is attached to an Application object, the listener receives all key events (both handled keys and unhandled global keys) while the application is in the foreground. In addition, the key listener receives all unhandled global key events while the application is in the background. If the latter key events are not desired, then key listeners should be attached to the individual screens in an application rather than to the Application object itself.

Parameters:

listener - Key event listener to register for this application.

Throws:

NullPointerException - if listener is null.

addKeyListener

public void addKeyListener(KeyListener listener,
                           boolean excludeFromUnhandledGlobalKeyEvents)

Adds a key event listener to this application.

Parameters:

listener - Key event listener to register for this application.

excludeFromUnhandledGlobalKeyEvents - If a foreground application does not consume a global key event, it is reposted as an unhandled global key event. Pass in true if the listener should be excluded from receiving unhandled global key events, false otherwise. This is desirable if an application is registered with KeyHandlerRegistry and does not want to receive duplicate notifications of global key events.

Throws:

NullPointerException - if listener is null.

Since:

BlackBerry API 6.0.0

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.

addMediaActionHandler

public boolean addMediaActionHandler(MediaActionHandler handler)

Adds a MediaActionHandler to this applicaton's list of media actions handlers. Examples of media actions include key presses of media keys while in the background, button presses on connected wired headsets, and button presses on paired Bluetooth headsets. See the documentation of MediaActionHandler for details.

When the mediaAction() method of the specified MediaActionHandler is invoked for media key presses from this registration it will be specified source==SOURCE_BACKGROUND_KEY, even if this application is currently in the foreground. If it is desired that mediaAction() be invoked with SOURCE_FOREGROUND_KEY when this application is in the foreground then register a MediaKeyListener using addKeyListener() to receive key presses while in the foreground and a MediaActionHandler to receive key presses while in the background. Since MediaKeyListener actually implements MediaActionHandler, the MediaKeyListener instance can be registered with both addKeyListener() and addMediaActionHandler().

The callbacks into the specified MediaActionHandler will occur on the event thread of this application.

Parameters:

handler - the MediaActionHandler to add to this application's list.

Returns:

true if the MediaActionHandler was successfully registered; false if the registration failed, possibly because net_rim_media_actions or net_rim_media_actions_daemon is missing or failed to run.

Throws:

NullPointerException - if handler is null.

ControlledAccessException - if registering the specified handler is forbidden for this application.

See Also:

Application.removeMediaActionHandler(MediaActionHandler), MediaActionHandler.SOURCE_BACKGROUND_KEY, Application.addKeyListener(KeyListener), MediaKeyListener

Since:

BlackBerry API 5.0.0

removeMediaActionHandler

public void removeMediaActionHandler(MediaActionHandler handler)

Removes a MediaActionHandler from this applicaton's list of media actions handlers.

Parameters:

handler - the MediaActionHandler to remove from this application's list; if null this method does nothing.

See Also:

Application.addMediaActionHandler(MediaActionHandler)

Since:

BlackBerry API 5.0.0

addTrackwheelListener

public void addTrackwheelListener(TrackwheelListener listener)

Deprecated. Use Screen.navigationClick(int, int) or Screen.navigationMovement(int, int, int, int) instead.

Adds a trackwheel event listener to this application.

Parameters:

listener - Trackwheel event listener to register for this application.

Throws:

NullPointerException - if listener is null.

removeTrackwheelListener

public void removeTrackwheelListener(TrackwheelListener listener)

Deprecated. Use Screen.navigationClick(int, int) or Screen.navigationMovement(int, int, int, int) instead.

Removes a trackwheel event listener from this application.

Parameters:

listener - Trackwheel event listener to de-register for this application.

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.

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.

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.

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.

addHolsterListener

public void addHolsterListener(HolsterListener listener)

Deprecated.

Adds a holster event listener to this application. The HolsterListener is deprecated. Please use SensorListener.

Parameters:

listener - Holster event listener to register for this application.

Throws:

NullPointerException - if listener is null.

removeHolsterListener

public void removeHolsterListener(HolsterListener listener)

Deprecated.

Removes a holster event listener from this application. The HolsterListener is deprecated. Please use SensorListener.

Parameters:

listener - Holster event listener to de-register for this application.

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:

BlackBerry API 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.

See Also:

RadioInfo

Since:

BlackBerry API 4.2.1

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:

BlackBerry API 3.6.0

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.

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.

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:

BlackBerry API 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:

BlackBerry API 4.2.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:

BlackBerry API 4.2.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:

BlackBerry API 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.

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.

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:

BlackBerry API 3.6.0

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:

BlackBerry API 3.6.0

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:

BlackBerry API 3.6.0

removeAlertListener

public void removeAlertListener(AlertListener listener)

Removes an alert listener from this application.

Parameters:

listener - Alert listener to de-register for this application.

Since:

BlackBerry API 3.6.0

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 Application.isHandlingEvents() returns true.

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 Application.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.

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:

BlackBerry API 4.0.0

isEventDispatchThread

public static final boolean isEventDispatchThread()

Determines if this is the event dispatching thread.

Note: this method simply invokes Application.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.

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 Application.enterEventDispatcher()); 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.

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.

getAppEventLock

public final Object getAppEventLock()

Retrieves the application event lock for this application.

Returns:

Application event lock.

See Also:

Application.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.

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. Application.hasEventThread() returns false), then a runnable object posted using this method will not be processed. Note: If an application does not have an event thread, you may invoke Application.setAcceptEvents(boolean) to inform the runtime system that the application no longer accepts events. Events will not be queued for that application.

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. Application.hasEventThread() returns false), then a runnable object posted using this method will not be processed. Note: If an application does not have an event thread, you may invoke Application.setAcceptEvents(boolean) to inform the runtime system that the application no longer accepts events. Events will not be queued for that application.

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.

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 Application.invokeLater(Runnable,long,boolean). If the supplied Event ID is invalid, this method does nothing.

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. Application.hasEventThread() returns false), then a runnable object posted using this method will not be processed. Note: If an application does not have an event thread, you may invoke Application.setAcceptEvents(boolean) to inform the runtime system that the application no longer accepts events. Events will not be queued for that application.

Parameters:

runnable - Runnable object to be placed on the dispatch thread's queue of events for synchronous execution.

Throws:

NullPointerException - if runnable is null.

getProcessId

public final int getProcessId()

Retrieves the process ID for this application.

Returns:

Process identifier for this application.

requestClose

public boolean requestClose()

Individual apps can handle this new API call by cleaning up and then closing themselves, if they so desire. The individual app should return true if it's successful in terminating itself otherwise should return false.

Returns:

whether the application closed (true) or was sent to the background (false)

Since:

BlackBerry API 5.0.0