org.osgi.service.provisioning.ProvisioningService Maven / Gradle / Ivy
Show all versions of org.osgi.compendium Show documentation
/*
* Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.service.provisioning;
import java.io.IOException;
import java.util.Dictionary;
import java.util.zip.ZipInputStream;
/**
* 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.
*
* @version $Revision: 7347 $
*/
public interface ProvisioningService {
/**
* The key to the provisioning information that uniquely identifies the
* Service Platform. The value must be of type String.
*/
public final static String PROVISIONING_SPID = "provisioning.spid";
/**
* The key to the provisioning information that contains the location of the
* provision data provider. The value must be of type String.
*/
public final static String PROVISIONING_REFERENCE = "provisioning.reference";
/**
* The key to the provisioning information that contains the initial
* configuration information of the initial Management Agent. The value will
* be of type byte[].
*/
public final static String PROVISIONING_AGENT_CONFIG = "provisioning.agent.config";
/**
* 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.
*/
public final static String PROVISIONING_UPDATE_COUNT = "provisioning.update.count";
/**
* 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.
*/
public final static String PROVISIONING_START_BUNDLE = "provisioning.start.bundle";
/**
* The key to the provisioning information that contains the root X509
* certificate used to establish trust with operator when using HTTPS.
*/
public final static String PROVISIONING_ROOTX509 = "provisioning.rootx509";
/**
* The key to the provisioning information that contains the shared secret
* used in conjunction with the RSH protocol.
*/
public final static String PROVISIONING_RSH_SECRET = "provisioning.rsh.secret";
/**
* MIME type to be stored in the extra field of a ZipEntry
* object for String data.
*/
public final static String MIME_STRING = "text/plain;charset=utf-8";
/**
* MIME type to be stored stored in the extra field of a
* ZipEntry object for byte[] data.
*/
public final static String MIME_BYTE_ARRAY = "application/octet-stream";
/**
* 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.
*/
public final static String MIME_BUNDLE = "application/vnd.osgi.bundle";
/**
* 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
*/
public final static String MIME_BUNDLE_ALT = "application/x-osgi-bundle";
/**
* 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.
*/
public final static String MIME_BUNDLE_URL = "text/x-osgi-bundle-url";
/**
* Name of the header that specifies the type information for the ZIP file
* entries.
*
* @since 1.2
*/
public final static String INITIALPROVISIONING_ENTRIES = "InitialProvisioning-Entries";
/**
* 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.
*
* @return A reference to the Provisioning Dictionary.
*/
public Dictionary getInformation();
/**
* 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.
*
* @param info the new set of Provisioning Information key/value pairs. Any
* keys are values that are of an invalid type will be silently
* ignored.
*/
public void setInformation(Dictionary info);
/**
* Adds the key/value pairs contained in info to the
* Provisioning Information dictionary. This method causes the
* PROVISIONING_UPDATE_COUNT to be incremented.
*
* @param 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.
*/
public void addInformation(Dictionary info);
/**
* 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.
*
* @param 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 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.
*/
public void addInformation(ZipInputStream zis) throws IOException;
}