org.osgi.service.application

Class ApplicationDescriptor

java.lang.Object

org.osgi.service.application.ApplicationDescriptor

public abstract class ApplicationDescriptor
extends Object

An OSGi service that represents an installed application and stores information about it. The application descriptor can be used for instance creation.

Version:

$Revision: 7938 $

Field Summary

Fields

Modifier and Type	Field and Description
static String	APPLICATION_CONTAINER The property key for the application container of the application.
static String	APPLICATION_COPYRIGHT The property key for the localized copyright notice of the application.
static String	APPLICATION_DESCRIPTION The property key for the localized description of the application.
static String	APPLICATION_DOCUMENTATION The property key for the localized documentation of the application.
static String	APPLICATION_ICON The property key for the localized icon of the application.
static String	APPLICATION_LAUNCHABLE The property key for the launchable property of the application.
static String	APPLICATION_LICENSE The property key for the localized license of the application.
static String	APPLICATION_LOCATION The property key for the location of the application.
static String	APPLICATION_LOCKED The property key for the locked property of the application.
static String	APPLICATION_NAME The property key for the localized name of the application.
static String	APPLICATION_PID The property key for the unique identifier (PID) of the application.
static String	APPLICATION_VENDOR The property key for the name of the application vendor.
static String	APPLICATION_VERSION The property key for the version of the application.
static String	APPLICATION_VISIBLE The property key for the visibility property of the application.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ApplicationDescriptor(String applicationId) Constructs the ApplicationDescriptor.

Method Summary

Modifier and Type	Method and Description
String	getApplicationId() Returns the identifier of the represented application.
Map	getProperties(String locale) Returns the properties of the application descriptor as key-value pairs.
protected abstract Map	getPropertiesSpecific(String locale) Container implementations can provide application model specific and/or container implementation specific properties via this method.
protected abstract boolean	isLaunchableSpecific() This method is called by launch() to verify that according to the container, the application is launchable.
ApplicationHandle	launch(Map arguments) Launches a new instance of an application.
protected abstract ApplicationHandle	launchSpecific(Map arguments) Called by launch() to create and start a new instance in an application model specific way.
void	lock() Sets the lock state of the application.
protected abstract void	lockSpecific() This method is used to notify the container implementation that the corresponding application has been locked and it should update the application.locked service property accordingly.
abstract boolean	matchDNChain(String pattern) This method verifies whether the specified pattern matches the Distinguished Names of any of the certificate chains used to authenticate this application.
ScheduledApplication	schedule(String scheduleId, Map arguments, String topic, String eventFilter, boolean recurring) Schedules the application at a specified event.
void	unlock() Unsets the lock state of the application.
protected abstract void	unlockSpecific() This method is used to notify the container implementation that the corresponding application has been unlocked and it should update the application.locked service property accordingly.

Methods inherited from class java.lang.Object

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

Field Detail

APPLICATION_NAME

public static final String APPLICATION_NAME

The property key for the localized name of the application.

See Also:

Constant Field Values

APPLICATION_ICON

public static final String APPLICATION_ICON

The property key for the localized icon of the application.

See Also:

Constant Field Values

APPLICATION_PID

public static final String APPLICATION_PID

The property key for the unique identifier (PID) of the application.

See Also:

Constant Field Values

APPLICATION_VERSION

public static final String APPLICATION_VERSION

The property key for the version of the application.

See Also:

Constant Field Values

APPLICATION_VENDOR

public static final String APPLICATION_VENDOR

The property key for the name of the application vendor.

See Also:

Constant Field Values

APPLICATION_VISIBLE

public static final String APPLICATION_VISIBLE

The property key for the visibility property of the application.

See Also:

Constant Field Values

APPLICATION_LAUNCHABLE

public static final String APPLICATION_LAUNCHABLE

The property key for the launchable property of the application.

See Also:

Constant Field Values

APPLICATION_LOCKED

public static final String APPLICATION_LOCKED

The property key for the locked property of the application.

See Also:

Constant Field Values

APPLICATION_DESCRIPTION

public static final String APPLICATION_DESCRIPTION

The property key for the localized description of the application.

See Also:

Constant Field Values

APPLICATION_DOCUMENTATION

public static final String APPLICATION_DOCUMENTATION

The property key for the localized documentation of the application.

See Also:

Constant Field Values

APPLICATION_COPYRIGHT

public static final String APPLICATION_COPYRIGHT

The property key for the localized copyright notice of the application.

See Also:

Constant Field Values

APPLICATION_LICENSE

public static final String APPLICATION_LICENSE

The property key for the localized license of the application.

See Also:

Constant Field Values

APPLICATION_CONTAINER

public static final String APPLICATION_CONTAINER

The property key for the application container of the application.

See Also:

Constant Field Values

APPLICATION_LOCATION

public static final String APPLICATION_LOCATION

The property key for the location of the application.

See Also:

Constant Field Values

Constructor Detail

ApplicationDescriptor

protected ApplicationDescriptor(String applicationId)

Constructs the ApplicationDescriptor.

Parameters:

applicationId - The identifier of the application. Its value is also available as the service.pid service property of this ApplicationDescriptor service. This parameter must not be null.

Throws:

NullPointerException - if the specified applicationId is null.

Method Detail

getApplicationId

public final String getApplicationId()

Returns the identifier of the represented application.

Returns:

the identifier of the represented application

matchDNChain

public abstract boolean matchDNChain(String pattern)

This method verifies whether the specified pattern matches the Distinguished Names of any of the certificate chains used to authenticate this application.

The pattern must adhere to the syntax defined in ApplicationAdminPermission for signer attributes.

This method is used by ApplicationAdminPermission.implies(java.security.Permission) method to match target ApplicationDescriptor and filter.

Parameters:

pattern - a pattern for a chain of Distinguished Names. It must not be null.

Returns:

true if the specified pattern matches at least one of the certificate chains used to authenticate this application

Throws:

NullPointerException - if the specified pattern is null.

IllegalStateException - if the application descriptor was unregistered

getProperties

public final Map getProperties(String locale)

Returns the properties of the application descriptor as key-value pairs. The return value contains the locale aware and unaware properties as well. The returned Map will include the service properties of this ApplicationDescriptor as well.

This method will call the getPropertiesSpecific method to enable the container implementation to insert application model and/or container implementation specific properties.

The returned Map will contain the standard OSGi service properties as well (e.g. service.id, service.vendor etc.) and specialized application descriptors may offer further service properties. The returned Map contains a snapshot of the properties. It will not reflect further changes in the property values nor will the update of the Map change the corresponding service property.

Parameters:

locale - the locale string, it may be null, the value null means the default locale. If the provided locale is the empty String ("")then raw (non-localized) values are returned.

Returns:

copy of the service properties of this application descriptor service, according to the specified locale. If locale is null then the default locale's properties will be returned. (Since service properties are always exist it cannot return null.)

Throws:

IllegalStateException - if the application descriptor is unregistered

getPropertiesSpecific

protected abstract Map getPropertiesSpecific(String locale)

Container implementations can provide application model specific and/or container implementation specific properties via this method. Localizable properties must be returned localized if the provided locale argument is not the empty String. The value null indicates to use the default locale, for other values the specified locale should be used. The returned Map must contain the standard OSGi service properties as well (e.g. service.id, service.vendor etc.) and specialized application descriptors may offer further service properties. The returned Map contains a snapshot of the properties. It will not reflect further changes in the property values nor will the update of the Map change the corresponding service property.

Parameters:

locale - the locale to be used for localizing the properties. If null the default locale should be used. If it is the empty String ("") then raw (non-localized) values should be returned.

Returns:

the application model specific and/or container implementation specific properties of this application descriptor.

Throws:

IllegalStateException - if the application descriptor is unregistered

launch

public final ApplicationHandle launch(Map arguments)
                               throws ApplicationException

Launches a new instance of an application. The args parameter specifies the startup parameters for the instance to be launched, it may be null.

The following steps are made:

• Check for the appropriate permission.
• Check the locking state of the application. If locked then throw an ApplicationException with the reason code ApplicationException.APPLICATION_LOCKED.
• Calls the launchSpecific() method to create and start an application instance.
• Returns the ApplicationHandle returned by the launchSpecific()

The caller has to have ApplicationAdminPermission(applicationPID, "launch") in order to be able to perform this operation.

The Map argument of the launch method contains startup arguments for the application. The keys used in the Map must be non-null, non-empty String objects. They can be standard or application specific. OSGi defines the org.osgi.triggeringevent key to be used to pass the triggering event to a scheduled application, however in the future it is possible that other well-known keys will be defined. To avoid unwanted clashes of keys, the following rules should be applied:

• The keys starting with the dash (-) character are application specific, no well-known meaning should be associated with them.
• Well-known keys should follow the reverse domain name based naming. In particular, the keys standardized in OSGi should start with org.osgi..

The method is synchronous, it return only when the application instance was successfully started or the attempt to start it failed.

This method never returns null. If launching an application fails, the appropriate exception is thrown.

Parameters:

arguments - Arguments for the newly launched application, may be null

Returns:

the registered ApplicationHandle, which represents the newly launched application instance. Never returns null.

Throws:

SecurityException - if the caller doesn't have "lifecycle" ApplicationAdminPermission for the application.

ApplicationException - if starting the application failed

IllegalStateException - if the application descriptor is unregistered

IllegalArgumentException - if the specified Map contains invalid keys (null objects, empty String or a key that is not String)

launchSpecific

protected abstract ApplicationHandle launchSpecific(Map arguments)
                                             throws Exception

Called by launch() to create and start a new instance in an application model specific way. It also creates and registeres the application handle to represent the newly created and started instance and registeres it. The method is synchronous, it return only when the application instance was successfully started or the attempt to start it failed.

This method must not return null. If launching the application failed, and exception must be thrown.

Parameters:

arguments - the startup parameters of the new application instance, may be null

Returns:

the registered application model specific application handle for the newly created and started instance.

Throws:

IllegalStateException - if the application descriptor is unregistered

Exception - if any problem occurs.

isLaunchableSpecific

protected abstract boolean isLaunchableSpecific()

This method is called by launch() to verify that according to the container, the application is launchable.

Returns:

true, if the application is launchable according to the container, false otherwise.

Throws:

IllegalStateException - if the application descriptor is unregistered

schedule

public final ScheduledApplication schedule(String scheduleId,
                                           Map arguments,
                                           String topic,
                                           String eventFilter,
                                           boolean recurring)
                                    throws org.osgi.framework.InvalidSyntaxException,
                                           ApplicationException

Schedules the application at a specified event. Schedule information should not get lost even if the framework or the device restarts so it should be stored in a persistent storage. The method registers a ScheduledApplication service in Service Registry, representing the created schedule.

The Map argument of the method contains startup arguments for the application. The keys used in the Map must be non-null, non-empty String objects. The argument values must be of primitive types, wrapper classes of primitive types, String or arrays or collections of these.

The created schedules have a unique identifier within the scope of this ApplicationDescriptor. This identifier can be specified in the scheduleId argument. If this argument is null, the identifier is automatically generated.

Parameters:

scheduleId - the identifier of the created schedule. It can be null, in this case the identifier is automatically generated.

arguments - the startup arguments for the scheduled application, may be null

topic - specifies the topic of the triggering event, it may contain a trailing asterisk as wildcard, the empty string is treated as "*", must not be null

eventFilter - specifies and LDAP filter to filter on the properties of the triggering event, may be null

recurring - if the recurring parameter is false then the application will be launched only once, when the event firstly occurs. If the parameter is true then scheduling will take place for every event occurrence; i.e. it is a recurring schedule

Returns:

the registered scheduled application service

Throws:

NullPointerException - if the topic is null

org.osgi.framework.InvalidSyntaxException - if the specified eventFilter is not syntactically correct

ApplicationException - if the schedule couldn't be created. The possible error codes are

• ApplicationException.APPLICATION_DUPLICATE_SCHEDULE_ID if the specified scheduleId is already used for this ApplicationDescriptor
• ApplicationException.APPLICATION_SCHEDULING_FAILED if the scheduling failed due to some internal reason (e.g. persistent storage error).
• ApplicationException.APPLICATION_INVALID_STARTUP_ARGUMENT if the specified startup argument doesn't satisfy the type or value constraints of startup arguments.

SecurityException - if the caller doesn't have "schedule" ApplicationAdminPermission for the application.

IllegalStateException - if the application descriptor is unregistered

IllegalArgumentException - if the specified Map contains invalid keys (null objects, empty String or a key that is not String)

lock

public final void lock()

Sets the lock state of the application. If an application is locked then launching a new instance is not possible. It does not affect the already launched instances.

Throws:

SecurityException - if the caller doesn't have "lock" ApplicationAdminPermission for the application.

IllegalStateException - if the application descriptor is unregistered

lockSpecific

protected abstract void lockSpecific()

This method is used to notify the container implementation that the corresponding application has been locked and it should update the application.locked service property accordingly.

Throws:

IllegalStateException - if the application descriptor is unregistered

unlock

public final void unlock()

Unsets the lock state of the application.

Throws:

SecurityException - if the caller doesn't have "lock" ApplicationAdminPermission for the application.

IllegalStateException - if the application descriptor is unregistered

unlockSpecific

protected abstract void unlockSpecific()

This method is used to notify the container implementation that the corresponding application has been unlocked and it should update the application.locked service property accordingly.

Throws:

IllegalStateException - if the application descriptor is unregistered