KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > osgi > framework > adaptor > FrameworkAdaptor


1 /*******************************************************************************
2  * Copyright (c) 2003, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11
12 package org.eclipse.osgi.framework.adaptor;
13
14 import java.io.IOException JavaDoc;
15 import java.net.URLConnection JavaDoc;
16 import java.util.Properties JavaDoc;
17 import org.eclipse.osgi.framework.log.FrameworkLog;
18 import org.eclipse.osgi.service.resolver.PlatformAdmin;
19 import org.eclipse.osgi.service.resolver.State;
20 import org.osgi.framework.BundleContext;
21 import org.osgi.framework.BundleException;
22
23 /**
24  * FrameworkAdaptor interface to the osgi framework. This class is used to provide
25  * platform specific support for the osgi framework.
26  *
27  * <p>The OSGi framework will call this class to perform platform specific functions.
28  *
29  * Classes that implement FrameworkAdaptor MUST provide a constructor that takes as a
30  * parameter an array of Strings. This array will contain arguments to be
31  * handled by the FrameworkAdaptor. The FrameworkAdaptor implementation may define the format
32  * and content of its arguments.
33  *
34  * The constructor should parse the arguments passed to it and remember them.
35  * The initialize method should perform the actual processing of the adaptor
36  * arguments.
37  * <p>
38  * Clients may implement this interface.
39  * </p>
40  * @since 3.1
41  */
42
43 public interface FrameworkAdaptor {
44
45     public static final String JavaDoc FRAMEWORK_SYMBOLICNAME = "org.eclipse.osgi"; //$NON-NLS-1$
46
47     /**
48      * Initialize the FrameworkAdaptor object so that it is ready to be
49      * called by the framework. Handle the arguments that were
50      * passed to the constructor.
51      * This method must be called before any other FrameworkAdaptor methods.
52      * @param eventPublisher The EventPublisher used to publish any events to
53      * the framework.
54      */
55     public void initialize(EventPublisher eventPublisher);
56
57     /**
58      * Initialize the persistent storage for the adaptor.
59      *
60      * @throws IOException If the adaptor is unable to
61      * initialize the bundle storage.
62      */
63     public void initializeStorage() throws IOException JavaDoc;
64
65     /**
66      * Compact/cleanup the persistent storage for the adaptor.
67      * @throws IOException If the adaptor is unable to
68      * compact the bundle storage.
69      *
70      */
71     public void compactStorage() throws IOException JavaDoc;
72
73     /**
74      * Return the properties object for the adaptor.
75      * The properties in the returned object supplement
76      * the System properties.
77      * The framework may modify this object. The Framework
78      * will use the returned properties to set the System
79      * properties.
80      *
81      * @return The properties object for the adaptor.
82      */
83     public Properties JavaDoc getProperties();
84
85     /**
86      * Return a list of the installed bundles. Each element in the
87      * list must be of type <code>BundleData</code>. Each <code>BundleData</code>
88      * corresponds to one bundle that is persistently stored.
89      * This method must construct <code>BundleData</code> objects for all
90      * installed bundles and return an array containing the objects.
91      * The returned array becomes the property of the framework.
92      *
93      * @return Array of installed BundleData objects, or null if none can be found.
94      */
95     public BundleData[] getInstalledBundles();
96
97     /**
98      * Map a location to a URLConnection. This is used by the Framework when installing a bundle
99      * from a spacified location.
100      *
101      * @param location of the bundle.
102      * @return URLConnection that represents the location.
103      * @throws BundleException if the mapping fails.
104      */
105     public URLConnection JavaDoc mapLocationToURLConnection(String JavaDoc location) throws BundleException;
106
107     /**
108      * Prepare to install a bundle from a URLConnection.
109      * <p>To complete the install,
110      * begin and then commit
111      * must be called on the returned <code>BundleOperation</code> object.
112      * If either of these methods throw a BundleException
113      * or some other error occurs,
114      * then undo must be called on the <code>BundleOperation</code> object
115      * to undo the change to persistent storage.
116      *
117      * @param location Bundle location.
118      * @param source URLConnection from which the bundle may be read.
119      * Any InputStreams returned from the source
120      * (URLConnections.getInputStream) must be closed by the
121      * <code>BundleOperation</code> object.
122      * @return BundleOperation object to be used to complete the install.
123      */
124     public BundleOperation installBundle(String JavaDoc location, URLConnection JavaDoc source);
125
126     /**
127      * Prepare to update a bundle from a URLConnection.
128      * <p>To complete the update
129      * begin and then commit
130      * must be called on the returned <code>BundleOperation</code> object.
131      * If either of these methods throw a BundleException
132      * or some other error occurs,
133      * then undo must be called on the <code>BundleOperation</code> object
134      * to undo the change to persistent storage.
135      *
136      * @param bundledata BundleData to update.
137      * @param source URLConnection from which the updated bundle may be read.
138      * Any InputStreams returned from the source
139      * (URLConnections.getInputStream) must be closed by the
140      * <code>BundleOperation</code> object.
141      * @return BundleOperation object to be used to complete the update.
142      */
143     public BundleOperation updateBundle(BundleData bundledata, URLConnection JavaDoc source);
144
145     /**
146      * Prepare to uninstall a bundle.
147      * <p>To complete the uninstall,
148      * begin and then commit
149      * must be called on the returned <code>BundleOperation</code> object.
150      * If either of these methods throw a BundleException
151      * or some other error occurs,
152      * then undo must be called on the <code>BundleOperation</code> object
153      * to undo the change to persistent storage.
154      *
155      * @param bundledata BundleData to uninstall.
156      * @return BundleOperation object to be used to complete the uninstall.
157      */
158     public BundleOperation uninstallBundle(BundleData bundledata);
159
160     /**
161      * Returns the total amount of free space available for bundle storage on the device.
162      *
163      * @return Free space available in bytes or -1 if it does not apply to this adaptor
164      * @exception IOException if an I/O error occurs determining the available space
165      */
166     public long getTotalFreeSpace() throws IOException JavaDoc;
167
168     /**
169      * Returns the PermissionStorage object which will be used to
170      * to manage the permission data.
171      *
172      * @return The PermissionStorage object for the adaptor.
173      * @see "org.osgi.service.permissionadmin.PermissionAdmin"
174      */
175     public PermissionStorage getPermissionStorage() throws IOException JavaDoc;
176
177     /**
178      * Returns the <code>ServiceRegistry</code> object which will be used
179      * to manage ServiceReference bindings.
180      * @return The ServiceRegistry object for the adaptor.
181      */
182     public ServiceRegistry getServiceRegistry();
183
184     /**
185      * The framework will call this method after the
186      * System BundleActivator.start(BundleContext) has been called. The context is
187      * the System Bundle's BundleContext. This method allows FrameworkAdaptors to
188      * have access to the OSGi framework to get services, register services and
189      * perform other OSGi operations.
190      * @param context The System Bundle's BundleContext.
191      * @exception BundleException on any error that may occur.
192      */
193     public void frameworkStart(BundleContext context) throws BundleException;
194
195     /**
196      * The framework will call this method before the
197      * System BundleActivator.stop(BundleContext) has been called. The context is
198      * the System Bundle's BundleContext. This method allows FrameworkAdaptors to
199      * have access to the OSGi framework to get services, register services and
200      * perform other OSGi operations.
201      * @param context The System Bundle's BundleContext.
202      * @exception BundleException on any error that may occur.
203      */
204     public void frameworkStop(BundleContext context) throws BundleException;
205
206     /**
207      * The framework will call this method before the process of framework
208      * shutdown is started. This gives FrameworkAdaptors a chance to
209      * perform actions before the framework start level is decremented and
210      * all the bundles are stopped. This method will get called before the
211      * {@link #frameworkStop(BundleContext)} method.
212      * @param context The System Bundle's BundleContext.
213      */
214     public void frameworkStopping(BundleContext context);
215
216     /**
217      * Returns the initial bundle start level as maintained by this adaptor
218      * @return the initial bundle start level
219      */
220     public int getInitialBundleStartLevel();
221
222     /**
223      * Sets the initial bundle start level
224      * @param value the initial bundle start level
225      */
226     public void setInitialBundleStartLevel(int value);
227
228     /**
229      * Returns the FrameworkLog for the FrameworkAdaptor. The FrameworkLog
230      * is used by the Framework and FrameworkAdaptor to log any error messages
231      * and FramworkEvents of type ERROR.
232      * @return The FrameworkLog to be used by the Framework.
233      */
234     public FrameworkLog getFrameworkLog();
235
236     /**
237      * Creates a BundleData object for the System Bundle. The BundleData
238      * returned will be used to define the System Bundle for the Framework.
239      * @return the BundleData for the System Bundle.
240      * @throws BundleException if any error occurs while creating the
241      * System BundleData.
242      */
243     public BundleData createSystemBundleData() throws BundleException;
244
245     /**
246      * Returns the bundle watcher for this FrameworkAdaptor.
247      * @return the bundle watcher for this FrameworkAdaptor.
248      */
249     public BundleWatcher getBundleWatcher();
250
251     /**
252      * Returns the PlatformAdmin for this FrameworkAdaptor.
253      * <p>
254      * This method will not be called until after
255      * {@link FrameworkAdaptor#frameworkStart(BundleContext)} is called.
256      * @return the PlatformAdmin for this FrameworkAdaptor.
257      */
258     public PlatformAdmin getPlatformAdmin();
259
260     /**
261      * Returns the State for this FrameworkAdaptor.
262      * <p>
263      * This method will not be called until after
264      * {@link FrameworkAdaptor#frameworkStart(BundleContext)} is called.
265      * The State returned is used by the framework to resolve bundle
266      * dependencies.
267      * @return the State for this FrameworkAdaptor.
268      */
269     public State getState();
270
271     /**
272      * Returns the parent ClassLoader all BundleClassLoaders created. All
273      * BundleClassLoaders that are created must use the ClassLoader returned
274      * by this method as a parent ClassLoader. Each call to this method must
275      * return the same ClassLoader object.
276      * @return the parent ClassLoader for all BundleClassLoaders created.
277      */
278     public ClassLoader JavaDoc getBundleClassLoaderParent();
279
280     /**
281      * Handles a RuntimeException or Error that was caught by the Framework and
282      * there is not a suitable caller to propagate the Throwable to. This gives
283      * the FrameworkAdaptor the ablity to handle such cases. For example, a
284      * FrameworkAdaptor may decide that such unexpected errors should cause an error
285      * message to be logged, or that the Framework should be terminated immediately.
286      * @param error The Throwable for the runtime error that is to be handled.
287      */
288     public void handleRuntimeError(Throwable JavaDoc error);
289
290     /**
291      * Matches the distinguished name chain against a
292      * pattern of a distinguished name chain.
293      *
294      * @param pattern the pattern of distinguished name (DN) chains to match
295      * against the dnChain. Wildcards "*" can be used in three cases:
296      * <ol>
297      * <li>As a DN. In this case, the DN will consist of just the "*".
298      * It will match zero or more DNs. For example, "cn=me,c=US;*;cn=you"
299      * will match "cn=me,c=US";cn=you" and
300      * "cn=me,c=US;cn=her,c=CA;cn=you".
301      * <li>As a DN prefix. In this case, the DN must start with "*,".
302      * The wild card will match zero or more RDNs at the start of a DN.
303      * For example, "*,cn=me,c=US;cn=you" will match "cn=me,c=US";cn=you"
304      * and "ou=my org unit,o=my org,cn=me,c=US;cn=you"</li>
305      * <li>As a value. In this case the value of a name value pair in an
306      * RDN will be a "*". The wildcard will match any value for the given
307      * name. For example, "cn=*,c=US;cn=you" will match
308      * "cn=me,c=US";cn=you" and "cn=her,c=US;cn=you", but it will not
309      * match "ou=my org unit,c=US;cn=you". If the wildcard does not occur
310      * by itself in the value, it will not be used as a wildcard. In
311      * other words, "cn=m*,c=US;cn=you" represents the common name of
312      * "m*" not any common name starting with "m".</li>
313      * </ol>
314      * @param dnChain a distinguished name (DN) chain
315      * @return true if a dnChain matches the pattern. A value of false is returned
316      * if bundle signing is not supported.
317      * @throws IllegalArgumentException
318      */
319     public boolean matchDNChain(String JavaDoc pattern, String JavaDoc dnChain[]);
320 }
321
Popular Tags