OSGi™ Service Platform
Compendium Specification

Release 4 Version 4.3

org.osgi.service.application
Class ApplicationDescriptor

java.lang.Object
  extended by org.osgi.service.application.ApplicationDescriptor

public abstract class ApplicationDescriptor
extends java.lang.Object

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


Field Summary
static java.lang.String APPLICATION_CONTAINER
          The property key for the application container of the application.
static java.lang.String APPLICATION_COPYRIGHT
          The property key for the localized copyright notice of the application.
static java.lang.String APPLICATION_DESCRIPTION
          The property key for the localized description of the application.
static java.lang.String APPLICATION_DOCUMENTATION
          The property key for the localized documentation of the application.
static java.lang.String APPLICATION_ICON
          The property key for the localized icon of the application.
static java.lang.String APPLICATION_LAUNCHABLE
          The property key for the launchable property of the application.
static java.lang.String APPLICATION_LICENSE
          The property key for the localized license of the application.
static java.lang.String APPLICATION_LOCATION
          The property key for the location of the application.
static java.lang.String APPLICATION_LOCKED
          The property key for the locked property of the application.
static java.lang.String APPLICATION_NAME
          The property key for the localized name of the application.
static java.lang.String APPLICATION_PID
          The property key for the unique identifier (PID) of the application.
static java.lang.String APPLICATION_VENDOR
          The property key for the name of the application vendor.
static java.lang.String APPLICATION_VERSION
          The property key for the version of the application.
static java.lang.String APPLICATION_VISIBLE
          The property key for the visibility property of the application.
 
Constructor Summary
protected ApplicationDescriptor(java.lang.String applicationId)
          Constructs the ApplicationDescriptor.
 
Method Summary
 java.lang.String getApplicationId()
          Returns the identifier of the represented application.
 java.util.Map getProperties(java.lang.String locale)
          Returns the properties of the application descriptor as key-value pairs.
protected abstract  java.util.Map getPropertiesSpecific(java.lang.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(java.util.Map arguments)
          Launches a new instance of an application.
protected abstract  ApplicationHandle launchSpecific(java.util.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(java.lang.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(java.lang.String scheduleId, java.util.Map arguments, java.lang.String topic, java.lang.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 java.lang.String APPLICATION_NAME
The property key for the localized name of the application.

See Also:
Constant Field Values

APPLICATION_ICON

public static final java.lang.String APPLICATION_ICON
The property key for the localized icon of the application.

See Also:
Constant Field Values

APPLICATION_PID

public static final java.lang.String APPLICATION_PID
The property key for the unique identifier (PID) of the application.

See Also:
Constant Field Values

APPLICATION_VERSION

public static final java.lang.String APPLICATION_VERSION
The property key for the version of the application.

See Also:
Constant Field Values

APPLICATION_VENDOR

public static final java.lang.String APPLICATION_VENDOR
The property key for the name of the application vendor.

See Also:
Constant Field Values

APPLICATION_VISIBLE

public static final java.lang.String APPLICATION_VISIBLE
The property key for the visibility property of the application.

See Also:
Constant Field Values

APPLICATION_LAUNCHABLE

public static final java.lang.String APPLICATION_LAUNCHABLE
The property key for the launchable property of the application.

See Also:
Constant Field Values

APPLICATION_LOCKED

public static final java.lang.String APPLICATION_LOCKED
The property key for the locked property of the application.

See Also:
Constant Field Values

APPLICATION_DESCRIPTION

public static final java.lang.String APPLICATION_DESCRIPTION
The property key for the localized description of the application.

See Also:
Constant Field Values

APPLICATION_DOCUMENTATION

public static final java.lang.String APPLICATION_DOCUMENTATION
The property key for the localized documentation of the application.

See Also:
Constant Field Values

APPLICATION_COPYRIGHT

public static final java.lang.String APPLICATION_COPYRIGHT
The property key for the localized copyright notice of the application.

See Also:
Constant Field Values

APPLICATION_LICENSE

public static final java.lang.String APPLICATION_LICENSE
The property key for the localized license of the application.

See Also:
Constant Field Values

APPLICATION_CONTAINER

public static final java.lang.String APPLICATION_CONTAINER
The property key for the application container of the application.

See Also:
Constant Field Values

APPLICATION_LOCATION

public static final java.lang.String APPLICATION_LOCATION
The property key for the location of the application.

See Also:
Constant Field Values
Constructor Detail

ApplicationDescriptor

protected ApplicationDescriptor(java.lang.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:
java.lang.NullPointerException - if the specified applicationId is null.
Method Detail

getApplicationId

public final java.lang.String getApplicationId()
Returns the identifier of the represented application.

Returns:
the identifier of the represented application

matchDNChain

public abstract boolean matchDNChain(java.lang.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:
java.lang.NullPointerException - if the specified pattern is null.
java.lang.IllegalStateException - if the application descriptor was unregistered

getProperties

public final java.util.Map getProperties(java.lang.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:
java.lang.IllegalStateException - if the application descriptor is unregistered

getPropertiesSpecific

protected abstract java.util.Map getPropertiesSpecific(java.lang.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:
java.lang.IllegalStateException - if the application descriptor is unregistered

launch

public final ApplicationHandle launch(java.util.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:

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 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:
java.lang.SecurityException - if the caller doesn't have "lifecycle" ApplicationAdminPermission for the application.
ApplicationException - if starting the application failed
java.lang.IllegalStateException - if the application descriptor is unregistered
java.lang.IllegalArgumentException - if the specified Map contains invalid keys (null objects, empty String or a key that is not String)

launchSpecific

protected abstract ApplicationHandle launchSpecific(java.util.Map arguments)
                                             throws java.lang.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:
java.lang.IllegalStateException - if the application descriptor is unregistered
java.lang.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:
java.lang.IllegalStateException - if the application descriptor is unregistered

schedule

public final ScheduledApplication schedule(java.lang.String scheduleId,
                                           java.util.Map arguments,
                                           java.lang.String topic,
                                           java.lang.String eventFilter,
                                           boolean recurring)
                                    throws 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:
java.lang.NullPointerException - if the topic is null
InvalidSyntaxException - if the specified eventFilter is not syntactically correct
ApplicationException - if the schedule couldn't be created. The possible error codes are
java.lang.SecurityException - if the caller doesn't have "schedule" ApplicationAdminPermission for the application.
java.lang.IllegalStateException - if the application descriptor is unregistered
java.lang.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:
java.lang.SecurityException - if the caller doesn't have "lock" ApplicationAdminPermission for the application.
java.lang.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:
java.lang.IllegalStateException - if the application descriptor is unregistered

unlock

public final void unlock()
Unsets the lock state of the application.

Throws:
java.lang.SecurityException - if the caller doesn't have "lock" ApplicationAdminPermission for the application.
java.lang.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:
java.lang.IllegalStateException - if the application descriptor is unregistered

OSGi™ Service Platform
Compendium Specification

Release 4 Version 4.3

Copyright © OSGi Alliance (2000, 2012). All Rights Reserved. Licensed under the OSGi Specification License, Version 2.0