ProvisioningService


1   /*
2    * $Header: /cvshome/build/org.osgi.service.provisioning/src/org/osgi/service/provisioning/ProvisioningService.java,v 1.11 2006/07/12 21:21:31 hargrave Exp $
3    *
4    * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.osgi.service.provisioning;
19  
20  import java.io.IOException  ;
21  import java.util.Dictionary  ;
22  import java.util.zip.ZipInputStream  ;
23  
24  /**
25   * Service for managing the initial provisioning information.
26   * <p>
27   * Initial provisioning of an OSGi device is a multi step process that
28   * culminates with the installation and execution of the initial management
29   * agent. At each step of the process, information is collected for the next
30   * step. Multiple bundles may be involved and this service provides a means for
31   * these bundles to exchange information. It also provides a means for the
32   * initial Management Bundle to get its initial configuration information.
33   * <p>
34   * The provisioning information is collected in a <code>Dictionary</code> object,
35   * called the Provisioning Dictionary. Any bundle that can access the service
36   * can get a reference to this object and read and update provisioning
37   * information. The key of the dictionary is a <code>String</code> object and the
38   * value is a <code>String</code> or <code>byte[]</code> object. The single
39   * exception is the PROVISIONING_UPDATE_COUNT value which is an Integer. The
40   * <code>provisioning</code> prefix is reserved for keys defined by OSGi, other
41   * key names may be used for implementation dependent provisioning systems.
42   * <p>
43   * Any changes to the provisioning information will be reflected immediately in
44   * all the dictionary objects obtained from the Provisioning Service.
45   * <p>
46   * Because of the specific application of the Provisioning Service, there should
47   * be only one Provisioning Service registered. This restriction will not be
48   * enforced by the Framework. Gateway operators or manufactures should ensure
49   * that a Provisioning Service bundle is not installed on a device that already
50   * has a bundle providing the Provisioning Service.
51   * <p>
52   * The provisioning information has the potential to contain sensitive
53   * information. Also, the ability to modify provisioning information can have
54   * drastic consequences. Thus, only trusted bundles should be allowed to
55   * register and get the Provisioning Service. The <code>ServicePermission</code>
56   * is used to limit the bundles that can gain access to the Provisioning
57   * Service. There is no check of <code>Permission</code> objects to read or modify
58   * the provisioning information, so care must be taken not to leak the
59   * Provisioning Dictionary received from <code>getInformation</code> method.
60   * 
61   * @version $Revision: 1.11 $
62   */
63  public interface ProvisioningService {
64      /**
65       * The key to the provisioning information that uniquely identifies the
66       * Service Platform. The value must be of type <code>String</code>.
67       */
68      public final static String    PROVISIONING_SPID           = "provisioning.spid";
69      /**
70       * The key to the provisioning information that contains the location of the
71       * provision data provider. The value must be of type <code>String</code>.
72       */
73      public final static String    PROVISIONING_REFERENCE      = "provisioning.reference";
74      /**
75       * The key to the provisioning information that contains the initial
76       * configuration information of the initial Management Agent. The value will
77       * be of type <code>byte[]</code>.
78       */
79      public final static String    PROVISIONING_AGENT_CONFIG   = "provisioning.agent.config";
80      /**
81       * The key to the provisioning information that contains the update count of
82       * the info data. Each set of changes to the provisioning information must
83       * end with this value being incremented. The value must be of type
84       * <code>Integer</code>. This key/value pair is also reflected in the
85       * properties of the ProvisioningService in the service registry.
86       */
87      public final static String    PROVISIONING_UPDATE_COUNT   = "provisioning.update.count";
88      /**
89       * The key to the provisioning information that contains the location of the
90       * bundle to start with <code>AllPermission</code>. The bundle must have be
91       * previously installed for this entry to have any effect.
92       */
93      public final static String    PROVISIONING_START_BUNDLE   = "provisioning.start.bundle";
94      /**
95       * The key to the provisioning information that contains the root X509
96       * certificate used to esatblish trust with operator when using HTTPS.
97       */
98      public final static String    PROVISIONING_ROOTX509       = "provisioning.rootx509";
99      /**
100      * The key to the provisioning information that contains the shared secret
101      * used in conjunction with the RSH protocol.
102      */
103     public final static String    PROVISIONING_RSH_SECRET     = "provisioning.rsh.secret";
104     /**
105      * MIME type to be stored in the extra field of a <code>ZipEntry</code> object
106      * for String data.
107      */
108     public final static String    MIME_STRING                 = "text/plain;charset=utf-8";
109     /**
110      * MIME type to be stored in the extra field of a <code>ZipEntry</code> object
111      * for <code>byte[]</code> data.
112      */
113     public final static String    MIME_BYTE_ARRAY             = "application/octet-stream";
114     /**
115      * MIME type to be stored in the extra field of a <code>ZipEntry</code> object
116      * for an installable bundle file. Zip entries of this type will be
117      * installed in the framework, but not started. The entry will also not be
118      * put into the information dictionary.
119      */
120     public final static String    MIME_BUNDLE                 = "application/x-osgi-bundle";
121     /**
122      * MIME type to be stored in the extra field of a ZipEntry for a String that
123      * represents a URL for a bundle. Zip entries of this type will be used to
124      * install (but not start) a bundle from the URL. The entry will not be put
125      * into the information dictionary.
126      */
127     public final static String    MIME_BUNDLE_URL             = "text/x-osgi-bundle-url";
128 
129     /**
130      * Returns a reference to the Provisioning Dictionary. Any change operations
131      * (put and remove) to the dictionary will cause an
132      * <code>UnsupportedOperationException</code> to be thrown. Changes must be
133      * done using the <code>setInformation</code> and <code>addInformation</code>
134      * methods of this service.
135      * @return A reference to the Provisioning Dictionary.
136      */
137     public Dictionary   getInformation();
138 
139     /**
140      * Replaces the Provisioning Information dictionary with the key/value pairs
141      * contained in <code>info</code>. Any key/value pairs not in <code>info</code>
142      * will be removed from the Provisioning Information dictionary. This method
143      * causes the <code>PROVISIONING_UPDATE_COUNT</code> to be incremented.
144      * 
145      * @param info the new set of Provisioning Information key/value pairs. Any
146      *        keys are values that are of an invalid type will be silently
147      *        ignored.
148      */
149     public void setInformation(Dictionary   info);
150 
151     /**
152      * Adds the key/value pairs contained in <code>info</code> to the Provisioning
153      * Information dictionary. This method causes the
154      * <code>PROVISIONING_UPDATE_COUNT</code> to be incremented.
155      * 
156      * @param info the set of Provisioning Information key/value pairs to add to
157      *        the Provisioning Information dictionary. Any keys are values that
158      *        are of an invalid type will be silently ignored.
159      */
160     public void addInformation(Dictionary   info);
161 
162     /**
163      * Processes the <code>ZipInputStream</code> and extracts information to add
164      * to the Provisioning Information dictionary, as well as, install/update
165      * and start bundles. This method causes the
166      * <code>PROVISIONING_UPDATE_COUNT</code> to be incremented.
167      * 
168      * @param zis the <code>ZipInputStream</code> that will be used to add
169      *        key/value pairs to the Provisioning Information dictionary and
170      *        install and start bundles. If a <code>ZipEntry</code> does not have
171      *        an <code>Extra</code> field that corresponds to one of the four
172      *        defined MIME types (<code>MIME_STRING</code>,
173      *        <code>MIME_BYTE_ARRAY</code>,<code>MIME_BUNDLE</code>, and
174      *        <code>MIME_BUNDLE_URL</code>) in will be silently ignored.
175      * @throws IOException if an error occurs while processing the
176      *            ZipInputStream. No additions will be made to the Provisioning
177      *            Information dictionary and no bundles must be started or
178      *            installed.
179      */
180     public void addInformation(ZipInputStream   zis) throws IOException  ;
181 }
182
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags