net.rim.device.api.system
Class ApplicationManager

java.lang.Object
  extended by net.rim.device.api.system.ApplicationManager

public abstract class ApplicationManager
extends Object

Manages all Java applications on the device.

The net.rim.device.api.system.ApplicationManager class enables applications to interact with the application manager to perform the following tasks:

. interact with processes, such as retrieving the IDs for foreground applications
. post global events to the system
. lock or unlock the handheld, or determine whether the handheld is locked
. run an application immediately or at a specific time

To use any of the ApplicationManager methods, you must first retrieve a reference to the current application manager using the getApplicationManager() method:

 ApplicationManager manager = ApplicationManager.getApplicationManager();
 

Retrieve information about applications

You can retrieve information about running processes by invoking getVisibleApplications() on the ApplicationManager. The getVisibleApplications() method retrieves an array of ApplicationDescriptor objects for visible applications that are running. An ApplicationDescriptor contains descriptive information for the application, such as its name, icon, position on the Home screen, resource bundle, and so on. Use ApplicationDescriptor methods to retrieve this information.

 ApplicationManager manager = ApplicationManager.getApplicationManager();
 ApplicationDescriptor descriptors[] = manager.getVisibleApplications();
 String appname1 = descriptors[0].getName();
 
Run an application with different arguments

You can use the ApplicationManager and ApplicationDescriptor classes to run an application with different arguments, for example, based on a system event.

1. Create an ApplicationDescriptor using the existing ApplicationDesriptor as a template. Specify the arguments to use in the main() method.

 
 ApplicationDescriptor template = ApplicationDescriptor.currentApplicationDescriptor();
 String[] args = { "admin", "secure" };
 ApplicationDescriptor newdescriptor = new ApplicationDescriptor(template, args);
 
2. Run the application using the new ApplicationDescriptor.
 ApplicationManager appmanager = ApplicationManager.getApplicationManager();
 try 
 {
     appmanager.runApplication(newdescriptor);
 } 
 catch(ApplicationManagerException) 
 {
     // Handle situation when application cannot run
 }
 

The runApplication() method creates a new process and invokes the exported main() method in the specified descriptor, using its arguments. The new process moves to the foreground if possible.

Post global events

You can use the ApplicationManager.postGlobalEvent method as a basic mechanism to communicate with other processes. You can also send and receive messages between processes using the runtime store.
To post a global event to a specific application, use the following method:

 abstract boolean postGlobalEvent(int processId, long guid, int data0, int data1, Object object0, Object object1)
 

The processID parameter specifies the ID of the process to which to post the event. You can retrieve a process ID by invoking the getProcessId(ApplicationDescriptor) method. The guid parameter specifies a global unique identifier (GUID) for the event. The data and object parameters specify additional information for the event.

To post a global event to all applications, use one of the following forms of the postGlobalEvent() method:
Form 1

 boolean postGlobalEvent(long guid);
 
Form 2
 boolean postGlobalEvent(long guid, int data0, int data1);
 
Form 3
 abstract boolean postGlobalEvent(long guid, int data0, int data1, Object object0, Object object1);
 

The first form of the method posts a global event with a unique identifier. The second form of the method posts a global event with additional data. The third form of the method posts a global event with additional integer and object data. To receive a global event, an application must implement the net.rim.device.api.system.GlobalEventListener interface and implement the GlobalEventListener.eventOccurred method, which is invoked when a global event occurs. In its implementation of eventOccurred(), the application specifies which actions to perform when a global event is received.

Register the GlobalEventListener by invoking the Application.addGlobalEventListener(GlobalEventListener) method.

Lock the handheld

To determine whether the user's handheld is locked, invoke ApplicationManager.isSystemLocked(). This method returns true if the handheld is locked.

You can use the ApplicationManager.lockSystem method to lock the user's handheld. For example, you might want to lock the handheld if the user types a password for your application incorrectly a certain number of times.
The following sample code demonstrates how to do this:

 ApplicationManager manager = ApplicationManager.getApplicationManager();
 manager.lockSystem(true);
 
Schedule an application to run later

You can schedule the application to run at a specified time by invoking scheduleApplication() instead of runApplication(), as demonstrated in the following code sample:

 try 
 {
     appmanager.scheduleApplication(newdescriptor, 1728000, false);
 } 
 catch(ApplicationManagerException) 
 {
     //handle situation when application cannot run
 }
 

Note: The application does not run if the handheld is reset or turned off before the specified time.

See Also:
Application, ApplicationDescriptor
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

Method Summary
Category: Signed static ApplicationManager getApplicationManager()
          Retrieves the system's application manager.
Category: Signed abstract  int getForegroundProcessId()
          Retrieves the process ID of the foreground process.
Category: Signed abstract  long getNextAlarm()
          Get the next alarm based on the current power on behavior
Category: Signed abstract  long getNextAlarm(int powerOnBehavior)
          Get the next alarm based on the power on behavior
Category: Signed abstract  int getProcessId(ApplicationDescriptor descriptor)
          Retrieves the process ID for specified descriptor's application.
Category: Signed abstract  ApplicationDescriptor[] getVisibleApplications()
          Retrieves descriptors for the visible, running applications.
Category: Signed abstract  boolean inStartup()
          Determines if the device is in the process of starting up.
Category: Signed abstract  boolean isConsoleDescriptor(ApplicationDescriptor descriptor)
          Determines if an application descriptor is the descriptor of the console process.
Category: Signed abstract  boolean isSystemLocked()
          Determines if the system is currently locked.
Category: Signed abstract  void launch(String url)
          Launches an application with provided URL parameter, without returning the process ID of the launched process.
Category: Signed abstract  int launchApplication(String url)
          Launches an application with provided URL parameter.
Category: Signed abstract  void lockSystem(boolean force)
          Locks the system.
Category: Signed abstract  boolean postGlobalEvent(int processId, long guid, int data0, int data1, Object object0, Object object1)
          Posts a global event with additional data and attachments to the specified process.
Category: Signed  boolean postGlobalEvent(long guid)
          Posts a global event to all applications in the system.
Category: Signed  boolean postGlobalEvent(long guid, int data0, int data1)
          Posts a global event with additional data to all applications in the system.
Category: Signed abstract  boolean postGlobalEvent(long guid, int data0, int data1, Object object0, Object object1)
          Posts a global event with additional data and attachments to all applications in the system.
Category: Signed abstract  void requestForeground(int processId)
          Sends a foreground request to application with specified process ID.
Category: Signed abstract  void requestForegroundForConsole()
          Requests that the console process (usually the home screen) be notified that it should bring itself to the foreground.
Category: Signed  int runApplication(ApplicationDescriptor descriptor)
          Creates a new process to run an application and ask it to foreground itself.
Category: Signed abstract  int runApplication(ApplicationDescriptor descriptor, boolean grabForeground)
          Creates a new process to run an application.
Category: Signed abstract  boolean scheduleApplication(ApplicationDescriptor descriptor, long time, boolean absolute)
          Schedules an application to run at a specific time.
Category: Signed abstract  void setCurrentPowerOnBehavior(int powerOnBehavior)
          Set the Power On Behavior for scheduled applications
Category: Signed abstract  boolean setInHolsterInputProcess()
          Deprecated.  
Category: Signed abstract  void unlockSystem()
          Unlocks the system.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

setInHolsterInputProcess

public abstract boolean setInHolsterInputProcess()
Deprecated. 

Sets the invoking process to receive input events when the device is in the holster.

Returns:
True if the invocation was successful; false if there is already another in-holster process set.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

launch

public abstract void launch(String url)
                     throws ApplicationManagerException
Launches an application with provided URL parameter, without returning the process ID of the launched process. If the process ID is desired then use ApplicationManager.launchApplication(String) instead.

This method launches an application with an URL of the following form:
module.name?param&param...
or
module?param&param...
if there is only a single entry point in the module.

Parameters:
url - URL which can be in any form and is passed in the arguments to main.
Throws:
ApplicationManagerException - If the application could not be run.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

launchApplication

public abstract int launchApplication(String url)
                               throws ApplicationManagerException
Launches an application with provided URL parameter.

This method launches an application with an URL of the following form:
module.name?param&param...
or
module?param&param...
if there is only a single entry point in the module.

Parameters:
url - URL which can be in any form and is passed in the arguments to main.
Returns:
ID for process that was created.
Throws:
ApplicationManagerException - If the application could not be run.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

lockSystem

public abstract void lockSystem(boolean force)
Locks the system.

Parameters:
force - Deprecated.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

isSystemLocked

public abstract boolean isSystemLocked()
Determines if the system is currently locked.

Returns:
True if the system is currently locked.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

unlockSystem

public abstract void unlockSystem()
Unlocks the system.

Calling this method blocks until the system actually unlocks.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

runApplication

public final int runApplication(ApplicationDescriptor descriptor)
                         throws ApplicationManagerException
Creates a new process to run an application and ask it to foreground itself.

Invoke this method to create a new process and invoke the exported main() method in the specified descriptor. This method then asks the process to foreground itself (which it may or may not do). If a process has already been created for your descriptor, then this method sends that process a foreground request.

Parameters:
descriptor - Descriptor of application to start.
Returns:
Process ID for the application's new process; if the application already has a running process, this will be the ID for that process.
Throws:
ApplicationManagerException - Thrown if the application could not be run.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

runApplication

public abstract int runApplication(ApplicationDescriptor descriptor,
                                   boolean grabForeground)
                            throws ApplicationManagerException
Creates a new process to run an application.

Invoke this method to create a new process and invoke the exported main() method in the specified descriptor. If you pass true for the grabForeground parameter, then this method also asks the process to foreground itself (which it may or may not do). If a process has already been created for your descriptor, and you pass true for the grabForeground parameter, then this method sends that process a foreground request.

Parameters:
descriptor - Descriptor of application to start.
grabForeground - If true, this method prompts the application to foreground itself.
Returns:
Process ID for the application's new process; if the application already has a running process, this will be the ID for that process.
Throws:
ApplicationManagerException - Thrown if the application could not be run.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

scheduleApplication

public abstract boolean scheduleApplication(ApplicationDescriptor descriptor,
                                            long time,
                                            boolean absolute)
Schedules an application to run at a specific time.

If the application is already scheduled to run at a particular time, then this method updates the schedule with your specified time. Note that the application scheduler has a resolution of one minute. Times are rounded down to the nearest minute.

If the specified time is absolute and has already occurred, the application will not be scheduled.

If the application's module changes after this method is invoked then the scheduled launch will be cancelled. For example, if an application invokes this method to schedule itself to launch in 10 minutes and a newer version is installed before the 10 minutes then the scheduled launch will be cancelled. This is because when a module is upgraded or downgraded the "old" module is deleted and a the "new" module is added, which means that the "new" module will have a different handle. Since the module's handle is stored in the ApplicationDescriptor there is no way for this method to completely reliably discover the upgraded module and launch it instead. As a workaround, if an application needs to maintain its scheduled launch after an upgrade it should run on startup and invoke this method to register a scheduled launch of the upgraded version.

Parameters:
descriptor - Descriptor of application to start.
time - Time at which to run the application; if a negative value, remove this application from the schedule.
absolute - If true, then the time parameter represents the number of milliseconds since device's origin time (midnight, January 1, 1970 UTC); otherwise, it represents the number of milliseconds since midnight local time.
Returns:
True if the application was scheduled successfully; otherwise, false.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

requestForeground

public abstract void requestForeground(int processId)
Sends a foreground request to application with specified process ID.

Parameters:
processId - Process ID for the application to receive a foreground request.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

requestForegroundForConsole

public abstract void requestForegroundForConsole()
Requests that the console process (usually the home screen) be notified that it should bring itself to the foreground.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

isConsoleDescriptor

public abstract boolean isConsoleDescriptor(ApplicationDescriptor descriptor)
Determines if an application descriptor is the descriptor of the console process.

Parameters:
descriptor - The descriptor to check.
Returns:
true if the specified descriptor matches the console process' descriptor; returns false otherwise or if descriptor==null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

getProcessId

public abstract int getProcessId(ApplicationDescriptor descriptor)
Retrieves the process ID for specified descriptor's application.

Parameters:
descriptor - Descriptor for the application in question.
Returns:
ID for process hosting descriptor's application; -1 if application has no process (i.e. is not running).
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getForegroundProcessId

public abstract int getForegroundProcessId()
Retrieves the process ID of the foreground process.

Parameters:
processId - Process ID of the application which is currently in the foreground; -1 if there is no foreground application.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

getVisibleApplications

public abstract ApplicationDescriptor[] getVisibleApplications()
Retrieves descriptors for the visible, running applications.

Returns:
Array of descriptors for the visible (foregroundable), running applications.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

postGlobalEvent

public final boolean postGlobalEvent(long guid)
Posts a global event to all applications in the system.

To receive and handle such events, an application must register a GlobalEventListener.

Parameters:
guid - The GUID of the event.
Returns:
True if the event was successfully posted; otherwise, false.
See Also:
Knowledge base article DB-00469 with additional information on valid system global events.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

postGlobalEvent

public final boolean postGlobalEvent(long guid,
                                     int data0,
                                     int data1)
Posts a global event with additional data to all applications in the system.

To receive and handle such events, an application must register a GlobalEventListener.

Parameters:
guid - The GUID of the event.
data0 - Additional information associated with the event.
data1 - Additional information associated with the event.
Returns:
True if the event was successfully posted; otherwise, false.
See Also:
Knowledge base article DB-00469 with additional information on valid system global events.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

postGlobalEvent

public abstract boolean postGlobalEvent(long guid,
                                        int data0,
                                        int data1,
                                        Object object0,
                                        Object object1)
Posts a global event with additional data and attachments to all applications in the system.

To receive and handle such events, an application must register a GlobalEventListener.

Parameters:
guid - The GUID of the event.
data0 - Additional information associated with the event.
data1 - Additional information associated with the event.
object0 - Additional information associated with the event.
object1 - Additional information associated with the event.
Returns:
True if the event was successfully posted; otherwise, false.
See Also:
Knowledge base article DB-00469 with additional information on valid system global events.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

postGlobalEvent

public abstract boolean postGlobalEvent(int processId,
                                        long guid,
                                        int data0,
                                        int data1,
                                        Object object0,
                                        Object object1)
Posts a global event with additional data and attachments to the specified process.

To receive and handle such events, the application must register a GlobalEventListener.

Parameters:
processId - Process ID of the application to receive the event.
guid - The GUID of the event.
data0 - Additional information associated with the event.
data1 - Additional information associated with the event.
object0 - Additional information associated with the event.
object1 - Additional information associated with the event.
Returns:
True if the event was successfully posted; otherwise, false.
See Also:
Knowledge base article DB-00469 with additional information on valid system global events.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0

inStartup

public abstract boolean inStartup()
Determines if the device is in the process of starting up. During startup, all threads must quiesce in order for the startup process to move on to the next startup tier.

Returns:
True if the device is in the process of starting up.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

setCurrentPowerOnBehavior

public abstract void setCurrentPowerOnBehavior(int powerOnBehavior)
Set the Power On Behavior for scheduled applications

Parameters:
powerOnBehavior - the ApplicationDescriptor power On Behaviour to use.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getNextAlarm

public abstract long getNextAlarm()
Get the next alarm based on the current power on behavior

Returns:
Time for next alarm.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

getNextAlarm

public abstract long getNextAlarm(int powerOnBehavior)
Get the next alarm based on the power on behavior

Parameters:
powerOnBehavior - the ApplicationDescriptor power On Behaviour filter alarms by.
Returns:
Time for next alarm.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getApplicationManager

public static final ApplicationManager getApplicationManager()
Retrieves the system's application manager.

Returns:
Reference to the system's application manager.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 3.6.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.