Package org.osgi.service.application

Class 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 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 Description
      protected ApplicationDescriptor​(java.lang.String applicationId)
      Constructs the ApplicationDescriptor.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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
        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