| /******************************************************************************* |
| * Copyright (c) 2003, 2005 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| |
| package org.eclipse.osgi.framework.adaptor; |
| |
| import java.io.File; |
| import java.io.IOException; |
| import java.net.URL; |
| import java.util.Dictionary; |
| import java.util.Enumeration; |
| import org.osgi.framework.*; |
| import org.osgi.framework.Bundle; |
| import org.osgi.framework.BundleException; |
| |
| /** |
| * The <code>BundleData</code> represents a single bundle that is persistently |
| * stored by a <code>FrameworkAdaptor</code>. A <code>BundleData</code> creates |
| * the ClassLoader for a bundle, finds native libraries installed in the |
| * FrameworkAdaptor for the bundle, creates data files for the bundle, |
| * used to access bundle entries, manifest information, and getting and saving |
| * metadata. |
| * <p> |
| * Clients may implement this interface. |
| * </p> |
| * @since 3.1 |
| */ |
| public interface BundleData { |
| |
| /** The BundleData is for a fragment bundle */ |
| public static final int TYPE_FRAGMENT = 0x00000001; |
| /** The BundleData is for a framework extension bundle */ |
| public static final int TYPE_FRAMEWORK_EXTENSION = 0x00000002; |
| /** The BundleData is for a bootclasspath extension bundle */ |
| public static final int TYPE_BOOTCLASSPATH_EXTENSION = 0x00000004; |
| /** The BundleData is for a singleton bundle */ |
| public static final int TYPE_SINGLETON = 0x00000008; |
| |
| |
| /** |
| * Creates the ClassLoader for the BundleData. The ClassLoader created |
| * must use the <code>ClassLoaderDelegate</code> to delegate class, resource |
| * and library loading. The delegate is responsible for finding any resource |
| * or classes imported by the bundle through an imported package or a required |
| * bundle. <p> |
| * The <code>ProtectionDomain</code> domain must be used by the Classloader when |
| * defining a class. |
| * @param delegate The <code>ClassLoaderDelegate</code> to delegate to. |
| * @param domain The <code>BundleProtectionDomain</code> to use when defining a class. |
| * @param bundleclasspath An array of bundle classpaths to use to create this |
| * classloader. This is specified by the Bundle-ClassPath manifest entry. |
| * @return The new ClassLoader for the BundleData. |
| */ |
| public BundleClassLoader createClassLoader(ClassLoaderDelegate delegate, BundleProtectionDomain domain, String[] bundleclasspath); |
| |
| /** |
| * Gets a <code>URL</code> to the bundle entry specified by path. |
| * This method must not use the BundleClassLoader to find the |
| * bundle entry since the ClassLoader will delegate to find the resource. |
| * @see org.osgi.framework.Bundle#getEntry(String) |
| * @param path The bundle entry path. |
| * @return A URL used to access the entry or null if the entry |
| * does not exist. |
| */ |
| public URL getEntry(String path); |
| |
| /** |
| * Gets all of the bundle entries that exist under the specified path. |
| * For example: <p> |
| * <code>getEntryPaths("/META-INF")</code> <p> |
| * This will return all entries from the /META-INF directory of the bundle. |
| * @see org.osgi.framework.Bundle#getEntryPaths(String path) |
| * @param path The path to a directory in the bundle. |
| * @return An Enumeration of the entry paths or null if the specified path |
| * does not exist. |
| */ |
| public Enumeration getEntryPaths(String path); |
| |
| /** |
| * Returns the absolute path name of a native library. The BundleData |
| * ClassLoader invokes this method to locate the native libraries that |
| * belong to classes loaded from this BundleData. Returns |
| * null if the library does not exist in this BundleData. |
| * @param libname The name of the library to find the absolute path to. |
| * @return The absolute path name of the native library or null if |
| * the library does not exist. |
| */ |
| public String findLibrary(String libname); |
| |
| /** |
| * Installs the native code paths for this BundleData. Each |
| * element of nativepaths must be installed for lookup when findLibrary |
| * is called. |
| * @param nativepaths The array of native code paths to install for |
| * the bundle. |
| * @throws BundleException If any error occurs during install. |
| */ |
| public void installNativeCode(String[] nativepaths) throws BundleException; |
| |
| /** |
| * Return the bundle data directory. |
| * Attempt to create the directory if it does not exist. |
| * |
| * @see org.osgi.framework.BundleContext#getDataFile(String) |
| * @return Bundle data directory or null if not supported. |
| */ |
| |
| public File getDataFile(String path); |
| |
| /** |
| * Return the Dictionary of manifest headers for the BundleData. |
| * @return Dictionary that contains the Manifest headers for the BundleData. |
| * @throws BundleException if an error occurred while reading the |
| * bundle manifest data. |
| */ |
| public Dictionary getManifest() throws BundleException; |
| |
| /** |
| * Get the BundleData bundle ID. This will be used as the bundle |
| * ID by the framework. |
| * @return The BundleData ID. |
| */ |
| public long getBundleID(); |
| |
| /** |
| * Get the BundleData Location. This will be used as the bundle |
| * location by the framework. |
| * @return the BundleData location. |
| */ |
| public String getLocation(); |
| |
| /** |
| * Get the last time this BundleData was modified. |
| * @return the last time this BundleData was modified |
| */ |
| public long getLastModified(); |
| |
| /** |
| * Close all resources for this BundleData |
| * @throws IOException If an error occurs closing. |
| */ |
| public void close() throws IOException; |
| |
| /** |
| * Open the BundleData. This method will reopen the BundleData if it has been |
| * previously closed. |
| * @throws IOException If an error occurs opening. |
| */ |
| public void open() throws IOException; |
| |
| /** |
| * Sets the Bundle object for this BundleData. |
| * @param bundle The Bundle Object for this BundleData. |
| */ |
| public void setBundle(Bundle bundle); |
| |
| /** |
| * Returns the start level metadata for this BundleData. |
| * @return the start level metadata for this BundleData. |
| */ |
| public int getStartLevel(); |
| |
| /** |
| * Returns the status metadata for this BundleData. A value of 1 |
| * indicates that this bundle is started persistently. A value of 0 |
| * indicates that this bundle is not started persistently. |
| * @return the status metadata for this BundleData. |
| */ |
| public int getStatus(); |
| |
| /** |
| * Sets the start level metatdata for this BundleData. Metadata must be |
| * stored persistently when BundleData.save() is called. |
| * @param value the start level metadata |
| */ |
| public void setStartLevel(int value); |
| |
| /** |
| * Sets the status metadata for this BundleData. Metadata must be |
| * stored persistently when BundleData.save() is called. |
| * @param value the status metadata. |
| */ |
| public void setStatus(int value); |
| |
| /** |
| * Persistently stores all the metadata for this BundleData |
| * @throws IOException |
| */ |
| public void save() throws IOException; |
| |
| /** |
| * Returns the Bundle-SymbolicName for this BundleData as specified in the bundle |
| * manifest file. |
| * @return the Bundle-SymbolicName for this BundleData. |
| */ |
| public String getSymbolicName(); |
| |
| /** |
| * Returns the Bundle-Version for this BundleData as specified in the bundle |
| * manifest file. |
| * @return the Bundle-Version for this BundleData. |
| */ |
| public Version getVersion(); |
| |
| /** |
| * Returns the type of bundle this BundleData is for. |
| * @return returns the type of bundle this BundleData is for |
| */ |
| public int getType(); |
| |
| /** |
| * Returns the Bundle-ClassPath for this BundleData as specified in |
| * the bundle manifest file. |
| * @return the classpath for this BundleData. |
| */ |
| public String[] getClassPath() throws BundleException; |
| |
| /** |
| * Returns the Bundle-Activator for this BundleData as specified in |
| * the bundle manifest file. |
| * @return the Bundle-Activator for this BundleData. |
| */ |
| public String getActivator(); |
| |
| /** |
| * Returns the Bundle-RequiredExecutionEnvironment for this BundleData as |
| * specified in the bundle manifest file. |
| * @return the Bundle-RequiredExecutionEnvironment for this BundleData. |
| */ |
| public String getExecutionEnvironment(); |
| |
| /** |
| * Returns the DynamicImport-Package for this BundleData as |
| * specified in the bundle manifest file. |
| * @return the DynamicImport-Packaget for this BundleData. |
| */ |
| public String getDynamicImports(); |
| |
| /** |
| * Matches the distinguished name chains of a bundle's signers against a |
| * pattern of a distinguished name chain. |
| * |
| * @param pattern the pattern of distinguished name (DN) chains to match |
| * against the dnChain. Wildcards "*" can be used in three cases: |
| * <ol> |
| * <li>As a DN. In this case, the DN will consist of just the "*". |
| * It will match zero or more DNs. For example, "cn=me,c=US;*;cn=you" |
| * will match "cn=me,c=US";cn=you" and |
| * "cn=me,c=US;cn=her,c=CA;cn=you". |
| * <li>As a DN prefix. In this case, the DN must start with "*,". |
| * The wild card will match zero or more RDNs at the start of a DN. |
| * For example, "*,cn=me,c=US;cn=you" will match "cn=me,c=US";cn=you" |
| * and "ou=my org unit,o=my org,cn=me,c=US;cn=you"</li> |
| * <li>As a value. In this case the value of a name value pair in an |
| * RDN will be a "*". The wildcard will match any value for the given |
| * name. For example, "cn=*,c=US;cn=you" will match |
| * "cn=me,c=US";cn=you" and "cn=her,c=US;cn=you", but it will not |
| * match "ou=my org unit,c=US;cn=you". If the wildcard does not occur |
| * by itself in the value, it will not be used as a wildcard. In |
| * other words, "cn=m*,c=US;cn=you" represents the common name of |
| * "m*" not any common name starting with "m".</li> |
| * </ol> |
| * @return true if a dnChain matches the pattern. A value of false is returned |
| * if bundle signing is not supported. |
| * @throws IllegalArgumentException |
| */ |
| public boolean matchDNChain(String pattern); |
| } |