Package 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: 1.13 $

  • Field Summary

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

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    final String
    getApplicationId()
    Returns the identifier of the represented application.
    final 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.
    final 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.
    final 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.
    final ScheduledApplication
    schedule(String scheduleId, Map arguments, String topic, String eventFilter, boolean recurring)
    Schedules the application at a specified event.
    final 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 Details

    • APPLICATION_NAME

      public static final String APPLICATION_NAME
      The property key for the localized name of the application.
      See Also:

    • APPLICATION_ICON

      public static final String APPLICATION_ICON
      The property key for the localized icon of the application.
      See Also:

    • APPLICATION_PID

      public static final String APPLICATION_PID
      The property key for the unique identifier (PID) of the application.
      See Also:

    • APPLICATION_VERSION

      public static final String APPLICATION_VERSION
      The property key for the version of the application.
      See Also:

    • APPLICATION_VENDOR

      public static final String APPLICATION_VENDOR
      The property key for the name of the application vendor.
      See Also:

    • APPLICATION_VISIBLE

      public static final String APPLICATION_VISIBLE
      The property key for the visibility property of the application.
      See Also:

    • APPLICATION_LAUNCHABLE

      public static final String APPLICATION_LAUNCHABLE
      The property key for the launchable property of the application.
      See Also:

    • APPLICATION_LOCKED

      public static final String APPLICATION_LOCKED
      The property key for the locked property of the application.
      See Also:

    • APPLICATION_DESCRIPTION

      public static final String APPLICATION_DESCRIPTION
      The property key for the localized description of the application.
      See Also:

    • APPLICATION_DOCUMENTATION

      public static final String APPLICATION_DOCUMENTATION
      The property key for the localized documentation of the application.
      See Also:

    • APPLICATION_LICENSE

      public static final String APPLICATION_LICENSE
      The property key for the localized license of the application.
      See Also:

    • APPLICATION_CONTAINER

      public static final String APPLICATION_CONTAINER
      The property key for the application container of the application.
      See Also:

    • APPLICATION_LOCATION

      public static final String APPLICATION_LOCATION
      The property key for the location of the application.
      See Also:

  • Constructor Details

    • 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 Details

    • 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 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
      InvalidSyntaxException - if the specified eventFilter is not syntactically correct
      ApplicationException - if the schedule couldn't be created. The possible error codes are
      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