BundleData


1   /*******************************************************************************
2    * Copyright (c) 2003, 2005 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.File  ;
15  import java.io.IOException  ;
16  import java.net.URL  ;
17  import java.util.Dictionary  ;
18  import java.util.Enumeration  ;
19  import org.osgi.framework.*;
20  import org.osgi.framework.Bundle;
21  import org.osgi.framework.BundleException;
22  
23  /**
24   * The <code>BundleData</code> represents a single bundle that is persistently 
25   * stored by a <code>FrameworkAdaptor</code>.  A <code>BundleData</code> creates
26   * the ClassLoader for a bundle, finds native libraries installed in the
27   * FrameworkAdaptor for the bundle, creates data files for the bundle,
28   * used to access bundle entries, manifest information, and getting and saving
29   * metadata.
30   * <p>
31   * Clients may implement this interface.
32   * </p>
33   * @since 3.1
34   */
35  public interface BundleData {
36  
37      /** The BundleData is for a fragment bundle */
38      public static final int TYPE_FRAGMENT =                 0x00000001;
39      /** The BundleData is for a framework extension bundle */
40      public static final int TYPE_FRAMEWORK_EXTENSION =      0x00000002;
41      /** The BundleData is for a bootclasspath extension bundle */
42      public static final int TYPE_BOOTCLASSPATH_EXTENSION =  0x00000004;
43      /** The BundleData is for a singleton bundle */
44      public static final int TYPE_SINGLETON =                0x00000008;
45      
46  
47      /**
48       * Creates the ClassLoader for the BundleData.  The ClassLoader created
49       * must use the <code>ClassLoaderDelegate</code> to delegate class, resource
50       * and library loading.  The delegate is responsible for finding any resource
51       * or classes imported by the bundle through an imported package or a required
52       * bundle. <p>
53       * The <code>ProtectionDomain</code> domain must be used by the Classloader when 
54       * defining a class.  
55       * @param delegate The <code>ClassLoaderDelegate</code> to delegate to.
56       * @param domain The <code>BundleProtectionDomain</code> to use when defining a class.
57       * @param bundleclasspath An array of bundle classpaths to use to create this
58       * classloader.  This is specified by the Bundle-ClassPath manifest entry.
59       * @return The new ClassLoader for the BundleData.
60       */
61      public BundleClassLoader createClassLoader(ClassLoaderDelegate delegate, BundleProtectionDomain domain, String  [] bundleclasspath);
62  
63      /**
64       * Gets a <code>URL</code> to the bundle entry specified by path.
65       * This method must not use the BundleClassLoader to find the
66       * bundle entry since the ClassLoader will delegate to find the resource.
67       * @see org.osgi.framework.Bundle#getEntry(String)
68       * @param path The bundle entry path.
69       * @return A URL used to access the entry or null if the entry
70       * does not exist.
71       */
72      public URL   getEntry(String   path);
73  
74      /**
75       * Gets all of the bundle entries that exist under the specified path.
76       * For example: <p>
77       * <code>getEntryPaths("/META-INF")</code> <p>
78       * This will return all entries from the /META-INF directory of the bundle.
79       * @see org.osgi.framework.Bundle#getEntryPaths(String path)
80       * @param path The path to a directory in the bundle.
81       * @return An Enumeration of the entry paths or null if the specified path
82       * does not exist.
83       */
84      public Enumeration   getEntryPaths(String   path);
85  
86      /**
87       * Returns the absolute path name of a native library. The BundleData
88       * ClassLoader invokes this method to locate the native libraries that 
89       * belong to classes loaded from this BundleData. Returns 
90       * null if the library does not exist in this BundleData.
91       * @param libname The name of the library to find the absolute path to.
92       * @return The absolute path name of the native library or null if
93       * the library does not exist.
94       */
95      public String   findLibrary(String   libname);
96  
97      /**
98       * Installs the native code paths for this BundleData.  Each
99       * element of nativepaths must be installed for lookup when findLibrary 
100      * is called.
101      * @param nativepaths The array of native code paths to install for
102      * the bundle.
103      * @throws BundleException If any error occurs during install.
104      */
105     public void installNativeCode(String  [] nativepaths) throws BundleException;
106 
107     /**
108      * Return the bundle data directory.
109      * Attempt to create the directory if it does not exist.
110      *
111      * @see org.osgi.framework.BundleContext#getDataFile(String)
112      * @return Bundle data directory or null if not supported.
113      */
114 
115     public File   getDataFile(String   path);
116 
117     /**
118      * Return the Dictionary of manifest headers for the BundleData.
119      * @return Dictionary that contains the Manifest headers for the BundleData.
120      * @throws BundleException if an error occurred while reading the
121      * bundle manifest data.
122      */
123     public Dictionary   getManifest() throws BundleException;
124 
125     /**
126      * Get the BundleData bundle ID.  This will be used as the bundle
127      * ID by the framework.
128      * @return The BundleData ID.
129      */
130     public long getBundleID();
131 
132     /**
133      * Get the BundleData Location.  This will be used as the bundle
134      * location by the framework.
135      * @return the BundleData location.
136      */
137     public String   getLocation();
138 
139     /**
140      * Get the last time this BundleData was modified.
141      * @return the last time this BundleData was modified
142      */
143     public long getLastModified();
144 
145     /**
146      * Close all resources for this BundleData
147      * @throws IOException If an error occurs closing.
148      */
149     public void close() throws IOException  ;
150 
151     /**
152      * Open the BundleData. This method will reopen the BundleData if it has been
153      * previously closed.
154      * @throws IOException If an error occurs opening.
155      */
156     public void open() throws IOException  ;
157 
158     /**
159      * Sets the Bundle object for this BundleData.
160      * @param bundle The Bundle Object for this BundleData.
161      */
162     public void setBundle(Bundle bundle);
163 
164     /**
165      * Returns the start level metadata for this BundleData.
166      * @return the start level metadata for this BundleData.
167      */
168     public int getStartLevel();
169 
170     /**
171      * Returns the status metadata for this BundleData.  A value of 1
172      * indicates that this bundle is started persistently.  A value of 0
173      * indicates that this bundle is not started persistently.
174      * @return the status metadata for this BundleData.
175      */
176     public int getStatus();
177 
178     /**
179      * Sets the start level metatdata for this BundleData.  Metadata must be
180      * stored persistently when BundleData.save() is called.
181      * @param value the start level metadata
182      */
183     public void setStartLevel(int value);
184 
185     /**
186      * Sets the status metadata for this BundleData.  Metadata must be
187      * stored persistently when BundleData.save() is called.
188      * @param value the status metadata.
189      */
190     public void setStatus(int value);
191 
192     /**
193      * Persistently stores all the metadata for this BundleData
194      * @throws IOException
195      */
196     public void save() throws IOException  ;
197 
198     /**
199      * Returns the Bundle-SymbolicName for this BundleData as specified in the bundle
200      * manifest file.
201      * @return the Bundle-SymbolicName for this BundleData.
202      */
203     public String   getSymbolicName();
204 
205     /**
206      * Returns the Bundle-Version for this BundleData as specified in the bundle 
207      * manifest file.
208      * @return the Bundle-Version for this BundleData.
209      */
210     public Version getVersion();
211 
212     /**
213      * Returns the type of bundle this BundleData is for.  
214      * @return returns the type of bundle this BundleData is for
215      */
216     public int getType();
217 
218     /**
219      * Returns the Bundle-ClassPath for this BundleData as specified in 
220      * the bundle manifest file.
221      * @return the classpath for this BundleData.
222      */
223     public String  [] getClassPath() throws BundleException;
224 
225     /**
226      * Returns the Bundle-Activator for this BundleData as specified in 
227      * the bundle manifest file.
228      * @return the Bundle-Activator for this BundleData.
229      */
230     public String   getActivator();
231 
232     /**
233      * Returns the Bundle-RequiredExecutionEnvironment for this BundleData as 
234      * specified in the bundle manifest file.
235      * @return the Bundle-RequiredExecutionEnvironment for this BundleData.
236      */
237     public String   getExecutionEnvironment();
238 
239     /**
240      * Returns the DynamicImport-Package for this BundleData as 
241      * specified in the bundle manifest file.
242      * @return the DynamicImport-Packaget for this BundleData.
243      */
244     public String   getDynamicImports();
245 
246     /**
247      * Matches the distinguished name chains of a bundle's signers against a 
248      * pattern of a distinguished name chain.
249      * 
250      * @param pattern the pattern of distinguished name (DN) chains to match
251      *        against the dnChain. Wildcards "*" can be used in three cases:
252      *        <ol>
253      *        <li>As a DN. In this case, the DN will consist of just the "*".
254      *        It will match zero or more DNs. For example, "cn=me,c=US;*;cn=you"
255      *        will match "cn=me,c=US";cn=you" and
256      *        "cn=me,c=US;cn=her,c=CA;cn=you".
257      *        <li>As a DN prefix. In this case, the DN must start with "*,".
258      *        The wild card will match zero or more RDNs at the start of a DN.
259      *        For example, "*,cn=me,c=US;cn=you" will match "cn=me,c=US";cn=you"
260      *        and "ou=my org unit,o=my org,cn=me,c=US;cn=you"</li>
261      *        <li>As a value. In this case the value of a name value pair in an
262      *        RDN will be a "*". The wildcard will match any value for the given
263      *        name. For example, "cn=*,c=US;cn=you" will match
264      *        "cn=me,c=US";cn=you" and "cn=her,c=US;cn=you", but it will not
265      *        match "ou=my org unit,c=US;cn=you". If the wildcard does not occur
266      *        by itself in the value, it will not be used as a wildcard. In
267      *        other words, "cn=m*,c=US;cn=you" represents the common name of
268      *        "m*" not any common name starting with "m".</li>
269      *        </ol>
270      * @return true if a dnChain matches the pattern. A value of false is returned
271      * if bundle signing is not supported.
272      * @throws IllegalArgumentException
273      */
274     public boolean matchDNChain(String   pattern);
275 }
276
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags