Interface ProvisioningService
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
FieldsModifier and TypeFieldDescriptionstatic final String
Name of the header that specifies the type information for the ZIP file entries.static final String
MIME type to be stored in the extra field of aZipEntry
object for an installable bundle file.static final String
Alternative MIME type to be stored in the extra field of aZipEntry
object for an installable bundle file.static final String
MIME type to be stored in the extra field of a ZipEntry for a String that represents a URL for a bundle.static final String
MIME type to be stored in the extra field of aZipEntry
object forbyte[]
data.static final String
MIME type to be stored in the extra field of aZipEntry
object for String data.static final String
The key to the provisioning information that contains the initial configuration information of the initial Management Agent.static final String
The key to the provisioning information that contains the location of the provision data provider.static final String
The key to the provisioning information that contains the root X509 certificate used to establish trust with operator when using HTTPS.static final String
The key to the provisioning information that contains the shared secret used in conjunction with the RSH protocol.static final String
The key to the provisioning information that uniquely identifies the Service Platform.static final String
The key to the provisioning information that contains the location of the bundle to start withAllPermission
.static final String
The key to the provisioning information that contains the update count of the info data. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addInformation
(Dictionary<String, ?> info) Adds the key/value pairs contained ininfo
to the Provisioning Information dictionary.void
Processes theZipInputStream
and extracts information to add to the Provisioning Information dictionary, as well as, install/update and start bundles.Returns a reference to the Provisioning Dictionary.void
setInformation
(Dictionary<String, ?> info) Replaces the Provisioning Information dictionary with the key/value pairs contained ininfo
.
-
Field Details
-
PROVISIONING_SPID
The key to the provisioning information that uniquely identifies the Service Platform. The value must be of typeString
.- See Also:
-
PROVISIONING_REFERENCE
The key to the provisioning information that contains the location of the provision data provider. The value must be of typeString
.- See Also:
-
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 typebyte[]
.- See Also:
-
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 typeInteger
. This key/value pair is also reflected in the properties of the ProvisioningService in the service registry.- See Also:
-
PROVISIONING_START_BUNDLE
The key to the provisioning information that contains the location of the bundle to start withAllPermission
. The bundle must have be previously installed for this entry to have any effect.- See Also:
-
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:
-
PROVISIONING_RSH_SECRET
The key to the provisioning information that contains the shared secret used in conjunction with the RSH protocol.- See Also:
-
MIME_STRING
MIME type to be stored in the extra field of aZipEntry
object for String data.- See Also:
-
MIME_BYTE_ARRAY
MIME type to be stored in the extra field of aZipEntry
object forbyte[]
data.- See Also:
-
MIME_BUNDLE
MIME type to be stored in the extra field of aZipEntry
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:
-
MIME_BUNDLE_ALT
Alternative MIME type to be stored in the extra field of aZipEntry
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 useMIME_BUNDLE
, which is an official IANA MIME type.- Since:
- 1.2
- See Also:
-
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:
-
INITIALPROVISIONING_ENTRIES
Name of the header that specifies the type information for the ZIP file entries.- Since:
- 1.2
- See Also:
-
-
Method Details
-
getInformation
Dictionary<String,Object> getInformation()Returns a reference to the Provisioning Dictionary. Any change operations (put and remove) to the dictionary will cause anUnsupportedOperationException
to be thrown. Changes must be done using thesetInformation
andaddInformation
methods of this service.- Returns:
- A reference to the Provisioning Dictionary.
-
setInformation
Replaces the Provisioning Information dictionary with the key/value pairs contained ininfo
. Any key/value pairs not ininfo
will be removed from the Provisioning Information dictionary. This method causes thePROVISIONING_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
Adds the key/value pairs contained ininfo
to the Provisioning Information dictionary. This method causes thePROVISIONING_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
Processes theZipInputStream
and extracts information to add to the Provisioning Information dictionary, as well as, install/update and start bundles. This method causes thePROVISIONING_UPDATE_COUNT
to be incremented.- Parameters:
zis
- theZipInputStream
that will be used to add key/value pairs to the Provisioning Information dictionary and install and start bundles. If aZipEntry
does not have anExtra
field that corresponds to one of the four defined MIME types (MIME_STRING
,MIME_BYTE_ARRAY
,MIME_BUNDLE
, andMIME_BUNDLE_URL
) in will be silently ignored.- Throws:
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.
-