com.sun.dtv.application
Class AppManager

java.lang.Object
  com.sun.dtv.application.AppManager

public abstract class AppManager
extends Object

AppManager provides control and access to Applications. The AppManager can list the applications known to the DTV runtime both active and inactive. Monitoring of changes in the available applications and their attributes is via AppManagerListener, see the addListener method.

For each application various attributes can be queried using the Application class, including the application id, type, the locator used to retrieve the application, the application name in one or more locales, the priority and visibility, version information, and icons; see the getApplications method.

Applications can be controlled using the ApplicationProxy class, providing methods to start, stop, pause, and resume the application, via the getActiveApplications method. Monitoring of active applications is via AppProxyListener via the ApplicationProxy.addListener method.

This API is multi-thread safe, meaning that the API can be called from multiple threads concurrently and no corruption of the application database will occur.

Code Sample

Example using the AppManager to find information about the current application. The XletContext contains the organization id and application id that are used to retrieve the Application instance.

 import com.sun.dtv.application.AppManager;
 import com.sun.dtv.application.Application;
 import javax.microedition.xlet.XletContext;
 
     XletContext xc = ...;
     AppManager mgr = AppManager.getInstance();
     Integer aid = (Integer)xc.getXletProperty("com.sun.dtv.appid");
     Integer oid = (Integer)xc.getXletProperty("com.sun.dtv.orgid");
     String id = mgr.makeApplicationId(oid.intValue(), aid.intValue());
     Application app = mgr.getApplication(id);
 

Method Summary

abstract void	addListener(AppManagerListener listener) Adds a listener for changes in the available applications.
abstract Application	fetch(String locator) Fetch an application from a locator.
abstract Enumeration	getActiveApplications() Returns an enumeration of the AppProxys for active applications in the current Service.
abstract Enumeration	getActiveApplications(AppFilter appFilter) Returns an enumeration of the AppProxys for active applications filtered by the AppFilter.
abstract Application	getApplication(String appId) Gets the Application for the requested appId.
abstract ApplicationProxy	getApplicationProxy(String appId) Gets the application proxy for the requested Application.
abstract Enumeration	getApplications() Returns an enumeration of the available Applications in the current Service.
abstract Enumeration	getApplications(AppFilter appFilter) Returns an enumeration of the applications filtered by the AppFilter.
static AppManager	getInstance() Gets the singleton AppManager.
abstract String	makeApplicationId(int organization, int applicationid) Makes an appId for the application with the indicated organization id and application id.
abstract void	removeListener(AppManagerListener listener) Remove a listener registered for changes in available applications.
abstract void	unload(String appId) Unload the application, freeing any resources that can be acquired if needed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static AppManager getInstance()

Gets the singleton AppManager.

Returns:

the Singleton AppManager instance.

Throws:

SecurityException - if the Application does not have AppManagerPermission("*", "read").

getApplications

public abstract Enumeration getApplications()

Returns an enumeration of the available Applications in the current Service. The results are the same as:

getApplications(new AppFilter)

Returns:

an Enumeration of Applications.

getActiveApplications

public abstract Enumeration getActiveApplications()

Returns an enumeration of the AppProxys for active applications in the current Service. The results are the same as:

getApplications(new AppFilter)

Returns:

an Enumeration of ApplicationProxys.

Throws:

SecurityException - if the Application does not have AppManagerPermission("*", "manage").

getApplications

public abstract Enumeration getApplications(AppFilter appFilter)

Returns an enumeration of the applications filtered by the AppFilter. All known Applications are passed to the filter and the filter accepts them or not.

Parameters:

appFilter - an AppFilter used to select Applications.

Returns:

an Enumeration of Applications.

getActiveApplications

public abstract Enumeration getActiveApplications(AppFilter appFilter)

Returns an enumeration of the AppProxys for active applications filtered by the AppFilter. All known Applications are passed to the filter and the filter accepts them or not.

Parameters:

appFilter - an AppFilter used to select Applications.

Returns:

an Enumeration of Applications.

Throws:

SecurityException - if the Application does not have AppManagerPermission("*", "manage").

makeApplicationId

public abstract String makeApplicationId(int organization,
                                         int applicationid)

Makes an appId for the application with the indicated organization id and application id. The organization id and application id are concatenated to form a 48 bit unsigned value. All 32 bits are used from the organization id and become the most significant bits of the result. Only the least significant 16 bits from the application id are used and they become the least significant bits of the result. That value is converted to a hexadecimal string using only digits and lowercase characters ('0'..'9','a'..'f'). The string MUST NOT have any leading '0' characters.

Parameters:

organization - an organization id as an int

applicationid - an application id as an int

Returns:

a String formatted properly with the organization id and application id.

getApplication

public abstract Application getApplication(String appId)

Gets the Application for the requested appId.

Parameters:

appId - the String appId

Returns:

the Application with the matching appId; otherwise null.

See Also:

makeApplicationId(int, int)

getApplicationProxy

public abstract ApplicationProxy getApplicationProxy(String appId)

Gets the application proxy for the requested Application.

Parameters:

appId - the String appId

Returns:

the ApplicationProxy of an application with the matching appId; otherwise null.

Throws:

SecurityException - if the Application does not have AppManagerPermission("*", "manage").

See Also:

makeApplicationId(int, int)

fetch

public abstract Application fetch(String locator)
                           throws IOException

Fetch an application from a locator. The method blocks the calling thread until sufficient information is available for the application. The application is entered into the database. Calls to fetch are internally synchronized so that the application is fetched only once and the same Application object is returned.

Parameters:

locator - referencing an application.

Returns:

the Application reference.

Throws:

SecurityException - if the Application does not have AppManagerPermission("*", "fetch").

SecurityException - if this Application does not have permission to use the locator to fetch the application.

IOException - if attempts to fetch the application results in an exception.

unload

public abstract void unload(String appId)

Unload the application, freeing any resources that can be acquired if needed. If the application is active, the unload is deferred until the application is no longer active. The unload request is canceled if the application is restarted.

Parameters:

appId - the appId of the application to unload

Throws:

SecurityException - if the Application does not have AppManagerPermission("*", "manage").

addListener

public abstract void addListener(AppManagerListener listener)

Adds a listener for changes in the available applications.

Parameters:

listener - the listener to add.

See Also:

removeListener(com.sun.dtv.application.AppManagerListener)

removeListener

public abstract void removeListener(AppManagerListener listener)

Remove a listener registered for changes in available applications. If the listener was not added, no action is taken.

Parameters:

listener - the listener to remove.

See Also:

addListener(com.sun.dtv.application.AppManagerListener)