001 /*
002 * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.provisioning;
017
018 import java.io.IOException;
019 import java.util.Dictionary;
020 import java.util.zip.ZipInputStream;
021
022 /**
023 * Service for managing the initial provisioning information.
024 * <p>
025 * Initial provisioning of an OSGi device is a multi step process that
026 * culminates with the installation and execution of the initial management
027 * agent. At each step of the process, information is collected for the next
028 * step. Multiple bundles may be involved and this service provides a means for
029 * these bundles to exchange information. It also provides a means for the
030 * initial Management Bundle to get its initial configuration information.
031 * <p>
032 * The provisioning information is collected in a <code>Dictionary</code>
033 * object, called the Provisioning Dictionary. Any bundle that can access the
034 * service can get a reference to this object and read and update provisioning
035 * information. The key of the dictionary is a <code>String</code> object and
036 * the value is a <code>String</code> or <code>byte[]</code> object. The
037 * single exception is the PROVISIONING_UPDATE_COUNT value which is an Integer.
038 * The <code>provisioning</code> prefix is reserved for keys defined by OSGi,
039 * other key names may be used for implementation dependent provisioning
040 * systems.
041 * <p>
042 * Any changes to the provisioning information will be reflected immediately in
043 * all the dictionary objects obtained from the Provisioning Service.
044 * <p>
045 * Because of the specific application of the Provisioning Service, there should
046 * be only one Provisioning Service registered. This restriction will not be
047 * enforced by the Framework. Gateway operators or manufactures should ensure
048 * that a Provisioning Service bundle is not installed on a device that already
049 * has a bundle providing the Provisioning Service.
050 * <p>
051 * The provisioning information has the potential to contain sensitive
052 * information. Also, the ability to modify provisioning information can have
053 * drastic consequences. Thus, only trusted bundles should be allowed to
054 * register and get the Provisioning Service. The <code>ServicePermission</code>
055 * is used to limit the bundles that can gain access to the Provisioning
056 * Service. There is no check of <code>Permission</code> objects to read or
057 * modify the provisioning information, so care must be taken not to leak the
058 * Provisioning Dictionary received from <code>getInformation</code> method.
059 *
060 * @version $Revision: 5654 $
061 */
062 public interface ProvisioningService {
063 /**
064 * The key to the provisioning information that uniquely identifies the
065 * Service Platform. The value must be of type <code>String</code>.
066 */
067 public final static String PROVISIONING_SPID = "provisioning.spid";
068
069 /**
070 * The key to the provisioning information that contains the location of the
071 * provision data provider. The value must be of type <code>String</code>.
072 */
073 public final static String PROVISIONING_REFERENCE = "provisioning.reference";
074
075 /**
076 * The key to the provisioning information that contains the initial
077 * configuration information of the initial Management Agent. The value will
078 * be of type <code>byte[]</code>.
079 */
080 public final static String PROVISIONING_AGENT_CONFIG = "provisioning.agent.config";
081
082 /**
083 * The key to the provisioning information that contains the update count of
084 * the info data. Each set of changes to the provisioning information must
085 * end with this value being incremented. The value must be of type
086 * <code>Integer</code>. This key/value pair is also reflected in the
087 * properties of the ProvisioningService in the service registry.
088 */
089 public final static String PROVISIONING_UPDATE_COUNT = "provisioning.update.count";
090
091 /**
092 * The key to the provisioning information that contains the location of the
093 * bundle to start with <code>AllPermission</code>. The bundle must have
094 * be previously installed for this entry to have any effect.
095 */
096 public final static String PROVISIONING_START_BUNDLE = "provisioning.start.bundle";
097
098 /**
099 * The key to the provisioning information that contains the root X509
100 * certificate used to establish trust with operator when using HTTPS.
101 */
102 public final static String PROVISIONING_ROOTX509 = "provisioning.rootx509";
103
104 /**
105 * The key to the provisioning information that contains the shared secret
106 * used in conjunction with the RSH protocol.
107 */
108 public final static String PROVISIONING_RSH_SECRET = "provisioning.rsh.secret";
109
110 /**
111 * MIME type to be used in the InitialProvisioning-Entries header or stored
112 * in the extra field of a <code>ZipEntry</code> object for String data.
113 */
114 public final static String MIME_STRING = "text/plain;charset=utf-8";
115
116 /**
117 * MIME type to be used in the InitialProvisioning-Entries header or stored
118 * stored in the extra field of a <code>ZipEntry</code> object for
119 * <code>byte[]</code> data.
120 */
121 public final static String MIME_BYTE_ARRAY = "application/octet-stream";
122
123 /**
124 * MIME type to be used in the InitialProvisioning-Entries header or stored
125 * stored in the extra field of a <code>ZipEntry</code> object for an
126 * installable bundle file. Zip entries of this type will be installed in
127 * the framework, but not started. The entry will also not be put into the
128 * information dictionary.
129 */
130 public final static String MIME_BUNDLE = "application/vnd.osgi.bundle";
131
132 /**
133 * Alternative MIME type to be used in the InitialProvisioning-Entries header or stored
134 * stored in the extra field of a <code>ZipEntry</code> object for an
135 * installable bundle file. Zip entries of this type will be installed in
136 * the framework, but not started. The entry will also not be put into the
137 * information dictionary. This alternative entry is only for backward compatibility,
138 * new applications are recommended to use <code>MIME_BUNDLE</code>, which is an official
139 * IANA MIME type.
140 */
141 public final static String MIME_BUNDLE_ALT = "application/x-osgi-bundle";
142
143 /**
144 * MIME type to be stored in the extra field of a ZipEntry for a String that
145 * represents a URL for a bundle. Zip entries of this type will be used to
146 * install (but not start) a bundle from the URL. The entry will not be put
147 * into the information dictionary.
148 */
149 public final static String MIME_BUNDLE_URL = "text/x-osgi-bundle-url";
150
151 /**
152 * Name of the header that specifies the (MIME) type information for the ZIP file
153 * entries.
154 */
155 public final static String INITIALPROVISIONING_ENTRIES = "InitialProvisioning-Entries";
156
157 /**
158 * Returns a reference to the Provisioning Dictionary. Any change operations
159 * (put and remove) to the dictionary will cause an
160 * <code>UnsupportedOperationException</code> to be thrown. Changes must
161 * be done using the <code>setInformation</code> and
162 * <code>addInformation</code> methods of this service.
163 *
164 * @return A reference to the Provisioning Dictionary.
165 */
166 public Dictionary getInformation();
167
168 /**
169 * Replaces the Provisioning Information dictionary with the key/value pairs
170 * contained in <code>info</code>. Any key/value pairs not in
171 * <code>info</code> will be removed from the Provisioning Information
172 * dictionary. This method causes the <code>PROVISIONING_UPDATE_COUNT</code>
173 * to be incremented.
174 *
175 * @param info the new set of Provisioning Information key/value pairs. Any
176 * keys are values that are of an invalid type will be silently
177 * ignored.
178 */
179 public void setInformation(Dictionary info);
180
181 /**
182 * Adds the key/value pairs contained in <code>info</code> to the
183 * Provisioning Information dictionary. This method causes the
184 * <code>PROVISIONING_UPDATE_COUNT</code> to be incremented.
185 *
186 * @param info the set of Provisioning Information key/value pairs to add to
187 * the Provisioning Information dictionary. Any keys are values that
188 * are of an invalid type will be silently ignored.
189 */
190 public void addInformation(Dictionary info);
191
192 /**
193 * Processes the <code>ZipInputStream</code> and extracts information to
194 * add to the Provisioning Information dictionary, as well as,
195 * install/update and start bundles. This method causes the
196 * <code>PROVISIONING_UPDATE_COUNT</code> to be incremented.
197 *
198 * @param zis the <code>ZipInputStream</code> that will be used to add
199 * key/value pairs to the Provisioning Information dictionary and
200 * install and start bundles. If a <code>ZipEntry</code> does not
201 * have an <code>Extra</code> field that corresponds to one of the
202 * four defined MIME types (<code>MIME_STRING</code>,
203 * <code>MIME_BYTE_ARRAY</code>,<code>MIME_BUNDLE</code>, and
204 * <code>MIME_BUNDLE_URL</code>) in will be silently ignored.
205 * @throws IOException if an error occurs while processing the
206 * ZipInputStream. No additions will be made to the Provisioning
207 * Information dictionary and no bundles must be started or
208 * installed.
209 */
210 public void addInformation(ZipInputStream zis) throws IOException;
211 }