ApplicationDescriptor
Date: 2016-06-25

org.osgi.service.application

## Class ApplicationDescriptor

- java.lang.Object
- - 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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ApplicationDescriptor(java.lang.String applicationId)` Constructs the `ApplicationDescriptor`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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:

      - 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:
        `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 registers the application handle to represent the newly created and started instance and registers 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 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:
        `java.lang.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.
        `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