Package org.osgi.service.provisioning

Interface ProvisioningService

  • public interface ProvisioningService
    Service for managing the initial provisioning information.

    Initial provisioning of an OSGi device is a multi step process that culminates with the installation and execution of the initial management agent. At each step of the process, information is collected for the next step. Multiple bundles may be involved and this service provides a means for these bundles to exchange information. It also provides a means for the initial Management Bundle to get its initial configuration information.

    The provisioning information is collected in a Dictionary object, called the Provisioning Dictionary. Any bundle that can access the service can get a reference to this object and read and update provisioning information. The key of the dictionary is a String object and the value is a String or byte[] object. The single exception is the PROVISIONING_UPDATE_COUNT value which is an Integer. The provisioning prefix is reserved for keys defined by OSGi, other key names may be used for implementation dependent provisioning systems.

    Any changes to the provisioning information will be reflected immediately in all the dictionary objects obtained from the Provisioning Service.

    Because of the specific application of the Provisioning Service, there should be only one Provisioning Service registered. This restriction will not be enforced by the Framework. Gateway operators or manufactures should ensure that a Provisioning Service bundle is not installed on a device that already has a bundle providing the Provisioning Service.

    The provisioning information has the potential to contain sensitive information. Also, the ability to modify provisioning information can have drastic consequences. Thus, only trusted bundles should be allowed to register and get the Provisioning Service. The ServicePermission is used to limit the bundles that can gain access to the Provisioning Service. There is no check of Permission objects to read or modify the provisioning information, so care must be taken not to leak the Provisioning Dictionary received from getInformation method.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String INITIALPROVISIONING_ENTRIES
      Name of the header that specifies the type information for the ZIP file entries.
      static java.lang.String MIME_BUNDLE
      MIME type to be stored in the extra field of a ZipEntry object for an installable bundle file.
      static java.lang.String MIME_BUNDLE_ALT
      Alternative MIME type to be stored in the extra field of a ZipEntry object for an installable bundle file.
      static java.lang.String MIME_BUNDLE_URL
      MIME type to be stored in the extra field of a ZipEntry for a String that represents a URL for a bundle.
      static java.lang.String MIME_BYTE_ARRAY
      MIME type to be stored in the extra field of a ZipEntry object for byte[] data.
      static java.lang.String MIME_STRING
      MIME type to be stored in the extra field of a ZipEntry object for String data.
      static java.lang.String PROVISIONING_AGENT_CONFIG
      The key to the provisioning information that contains the initial configuration information of the initial Management Agent.
      static java.lang.String PROVISIONING_REFERENCE
      The key to the provisioning information that contains the location of the provision data provider.
      static java.lang.String PROVISIONING_ROOTX509
      The key to the provisioning information that contains the root X509 certificate used to establish trust with operator when using HTTPS.
      static java.lang.String PROVISIONING_RSH_SECRET
      The key to the provisioning information that contains the shared secret used in conjunction with the RSH protocol.
      static java.lang.String PROVISIONING_SPID
      The key to the provisioning information that uniquely identifies the Service Platform.
      static java.lang.String PROVISIONING_START_BUNDLE
      The key to the provisioning information that contains the location of the bundle to start with AllPermission.
      static java.lang.String PROVISIONING_UPDATE_COUNT
      The key to the provisioning information that contains the update count of the info data.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addInformation​(java.util.Dictionary<java.lang.String,​?> info)
      Adds the key/value pairs contained in info to the Provisioning Information dictionary.
      void addInformation​(java.util.zip.ZipInputStream zis)
      Processes the ZipInputStream and extracts information to add to the Provisioning Information dictionary, as well as, install/update and start bundles.
      java.util.Dictionary<java.lang.String,​java.lang.Object> getInformation()
      Returns a reference to the Provisioning Dictionary.
      void setInformation​(java.util.Dictionary<java.lang.String,​?> info)
      Replaces the Provisioning Information dictionary with the key/value pairs contained in info.

    • Field Detail

      • PROVISIONING_SPID

        static final java.lang.String PROVISIONING_SPID
        The key to the provisioning information that uniquely identifies the Service Platform. The value must be of type String.
        See Also:
        Constant Field Values

      • PROVISIONING_REFERENCE

        static final java.lang.String PROVISIONING_REFERENCE
        The key to the provisioning information that contains the location of the provision data provider. The value must be of type String.
        See Also:
        Constant Field Values

      • PROVISIONING_AGENT_CONFIG

        static final java.lang.String PROVISIONING_AGENT_CONFIG
        The key to the provisioning information that contains the initial configuration information of the initial Management Agent. The value will be of type byte[].
        See Also:
        Constant Field Values

      • PROVISIONING_UPDATE_COUNT

        static final java.lang.String PROVISIONING_UPDATE_COUNT
        The key to the provisioning information that contains the update count of the info data. Each set of changes to the provisioning information must end with this value being incremented. The value must be of type Integer. This key/value pair is also reflected in the properties of the ProvisioningService in the service registry.
        See Also:
        Constant Field Values

      • PROVISIONING_START_BUNDLE

        static final java.lang.String PROVISIONING_START_BUNDLE
        The key to the provisioning information that contains the location of the bundle to start with AllPermission. The bundle must have be previously installed for this entry to have any effect.
        See Also:
        Constant Field Values

      • PROVISIONING_ROOTX509

        static final java.lang.String PROVISIONING_ROOTX509
        The key to the provisioning information that contains the root X509 certificate used to establish trust with operator when using HTTPS.
        See Also:
        Constant Field Values

      • PROVISIONING_RSH_SECRET

        static final java.lang.String PROVISIONING_RSH_SECRET
        The key to the provisioning information that contains the shared secret used in conjunction with the RSH protocol.
        See Also:
        Constant Field Values

      • MIME_STRING

        static final java.lang.String MIME_STRING
        MIME type to be stored in the extra field of a ZipEntry object for String data.
        See Also:
        Constant Field Values

      • MIME_BYTE_ARRAY

        static final java.lang.String MIME_BYTE_ARRAY
        MIME type to be stored in the extra field of a ZipEntry object for byte[] data.
        See Also:
        Constant Field Values

      • MIME_BUNDLE

        static final java.lang.String MIME_BUNDLE
        MIME type to be stored in the extra field of a ZipEntry object for an installable bundle file. Zip entries of this type will be installed in the framework, but not started. The entry will also not be put into the information dictionary.
        See Also:
        Constant Field Values

      • MIME_BUNDLE_ALT

        static final java.lang.String MIME_BUNDLE_ALT
        Alternative MIME type to be stored in the extra field of a ZipEntry object for an installable bundle file. Zip entries of this type will be installed in the framework, but not started. The entry will also not be put into the information dictionary. This alternative entry is only for backward compatibility, new applications are recommended to use MIME_BUNDLE, which is an official IANA MIME type.
        Since:
        1.2
        See Also:
        Constant Field Values

      • MIME_BUNDLE_URL

        static final java.lang.String MIME_BUNDLE_URL
        MIME type to be stored in the extra field of a ZipEntry for a String that represents a URL for a bundle. Zip entries of this type will be used to install (but not start) a bundle from the URL. The entry will not be put into the information dictionary.
        See Also:
        Constant Field Values

      • INITIALPROVISIONING_ENTRIES

        static final java.lang.String INITIALPROVISIONING_ENTRIES
        Name of the header that specifies the type information for the ZIP file entries.
        Since:
        1.2
        See Also:
        Constant Field Values

    • Method Detail

      • getInformation

        java.util.Dictionary<java.lang.String,​java.lang.Object> getInformation()
        Returns a reference to the Provisioning Dictionary. Any change operations (put and remove) to the dictionary will cause an UnsupportedOperationException to be thrown. Changes must be done using the setInformation and addInformation methods of this service.
        Returns:
        A reference to the Provisioning Dictionary.

      • setInformation

        void setInformation​(java.util.Dictionary<java.lang.String,​?> info)
        Replaces the Provisioning Information dictionary with the key/value pairs contained in info. Any key/value pairs not in info will be removed from the Provisioning Information dictionary. This method causes the PROVISIONING_UPDATE_COUNT to be incremented.
        Parameters:
        info - the new set of Provisioning Information key/value pairs. Any keys are values that are of an invalid type will be silently ignored.

      • addInformation

        void addInformation​(java.util.Dictionary<java.lang.String,​?> info)
        Adds the key/value pairs contained in info to the Provisioning Information dictionary. This method causes the PROVISIONING_UPDATE_COUNT to be incremented.
        Parameters:
        info - the set of Provisioning Information key/value pairs to add to the Provisioning Information dictionary. Any keys are values that are of an invalid type will be silently ignored.

      • addInformation

        void addInformation​(java.util.zip.ZipInputStream zis)
             throws java.io.IOException
        Processes the ZipInputStream and extracts information to add to the Provisioning Information dictionary, as well as, install/update and start bundles. This method causes the PROVISIONING_UPDATE_COUNT to be incremented.
        Parameters:
        zis - the ZipInputStream that will be used to add key/value pairs to the Provisioning Information dictionary and install and start bundles. If a ZipEntry does not have an Extra field that corresponds to one of the four defined MIME types (MIME_STRING, MIME_BYTE_ARRAY, MIME_BUNDLE, and MIME_BUNDLE_URL) in will be silently ignored.
        Throws:
        java.io.IOException - if an error occurs while processing the ZipInputStream. No additions will be made to the Provisioning Information dictionary and no bundles must be started or installed.