/* * Copyright (c) OSGi Alliance (2000, 2009). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.osgi.framework; import java.io.IOException; import java.io.InputStream; import java.net.URL; import java.util.Dictionary; import java.util.Enumeration; import java.util.Map; /** * An installed bundle in the Framework. * *

* A Bundle object is the access point to define the lifecycle of * an installed bundle. Each bundle installed in the OSGi environment must have * an associated Bundle object. * *

* A bundle must have a unique identity, a long, chosen by the * Framework. This identity must not change during the lifecycle of a bundle, * even when the bundle is updated. Uninstalling and then reinstalling the * bundle must create a new unique identity. * *

* A bundle can be in one of six states: *

*

* Values assigned to these states have no specified ordering; they represent * bit values that may be ORed together to determine if a bundle is in one of * the valid states. * *

* A bundle should only execute code when its state is one of * STARTING,ACTIVE, or STOPPING. * An UNINSTALLED bundle can not be set to another state; it is a * zombie and can only be reached because references are kept somewhere. * *

* The Framework is the only entity that is allowed to create * Bundle objects, and these objects are only valid within the * Framework that created them. * * @ThreadSafe * @version $Revision$ */ public interface Bundle { /** * The bundle is uninstalled and may not be used. * *

* The UNINSTALLED state is only visible after a bundle is * uninstalled; the bundle is in an unusable state but references to the * Bundle object may still be available and used for * introspection. *

* The value of UNINSTALLED is 0x00000001. */ public static final int UNINSTALLED = 0x00000001; /** * The bundle is installed but not yet resolved. * *

* A bundle is in the INSTALLED state when it has been * installed in the Framework but is not or cannot be resolved. *

* This state is visible if the bundle's code dependencies are not resolved. * The Framework may attempt to resolve an INSTALLED bundle's * code dependencies and move the bundle to the RESOLVED * state. *

* The value of INSTALLED is 0x00000002. */ public static final int INSTALLED = 0x00000002; /** * The bundle is resolved and is able to be started. * *

* A bundle is in the RESOLVED state when the Framework has * successfully resolved the bundle's code dependencies. These dependencies * include: *

*

* Note that the bundle is not active yet. A bundle must be put in the * RESOLVED state before it can be started. The Framework may * attempt to resolve a bundle at any time. *

* The value of RESOLVED is 0x00000004. */ public static final int RESOLVED = 0x00000004; /** * The bundle is in the process of starting. * *

* A bundle is in the STARTING state when its * {@link #start(int) start} method is active. A bundle must be in this * state when the bundle's {@link BundleActivator#start} is called. If the * BundleActivator.start method completes without exception, * then the bundle has successfully started and must move to the * ACTIVE state. *

* If the bundle has a * {@link Constants#ACTIVATION_LAZY lazy activation policy}, then the * bundle may remain in this state for some time until the activation is * triggered. *

* The value of STARTING is 0x00000008. */ public static final int STARTING = 0x00000008; /** * The bundle is in the process of stopping. * *

* A bundle is in the STOPPING state when its * {@link #stop(int) stop} method is active. A bundle must be in this state * when the bundle's {@link BundleActivator#stop} method is called. When the * BundleActivator.stop method completes the bundle is * stopped and must move to the RESOLVED state. *

* The value of STOPPING is 0x00000010. */ public static final int STOPPING = 0x00000010; /** * The bundle is now running. * *

* A bundle is in the ACTIVE state when it has been * successfully started and activated. *

* The value of ACTIVE is 0x00000020. */ public static final int ACTIVE = 0x00000020; /** * The bundle start operation is transient and the persistent autostart * setting of the bundle is not modified. * *

* This bit may be set when calling {@link #start(int)} to notify the * framework that the autostart setting of the bundle must not be modified. * If this bit is not set, then the autostart setting of the bundle is * modified. * * @since 1.4 * @see #start(int) */ public static final int START_TRANSIENT = 0x00000001; /** * The bundle start operation must activate the bundle according to the * bundle's declared * {@link Constants#BUNDLE_ACTIVATIONPOLICY activation policy}. * *

* This bit may be set when calling {@link #start(int)} to notify the * framework that the bundle must be activated using the bundle's declared * activation policy. * * @since 1.4 * @see Constants#BUNDLE_ACTIVATIONPOLICY * @see #start(int) */ public static final int START_ACTIVATION_POLICY = 0x00000002; /** * The bundle stop is transient and the persistent autostart setting of the * bundle is not modified. * *

* This bit may be set when calling {@link #stop(int)} to notify the * framework that the autostart setting of the bundle must not be modified. * If this bit is not set, then the autostart setting of the bundle is * modified. * * @since 1.4 * @see #stop(int) */ public static final int STOP_TRANSIENT = 0x00000001; /** * Request that all certificates used to sign the bundle be returned. * * @since 1.5 * @see #getSignerCertificates(int) */ public final static int SIGNERS_ALL = 1; /** * Request that only certificates used to sign the bundle that are trusted * by the framework be returned. * * @since 1.5 * @see #getSignerCertificates(int) */ public final static int SIGNERS_TRUSTED = 2; /** * Returns this bundle's current state. * *

* A bundle can be in only one state at any time. * * @return An element of UNINSTALLED,INSTALLED, * RESOLVED,STARTING, * STOPPING,ACTIVE. */ public int getState(); /** * Starts this bundle. * *

* If this bundle's state is UNINSTALLED then an * IllegalStateException is thrown. *

* If the Framework implements the optional Start Level service and the * current start level is less than this bundle's start level: *

*

* When the Framework's current start level becomes equal to or more than * this bundle's start level, this bundle will be started. *

* Otherwise, the following steps are required to start this bundle: *

    *
  1. If this bundle is in the process of being activated or deactivated * then this method must wait for activation or deactivation to complete * before continuing. If this does not occur in a reasonable time, a * BundleException is thrown to indicate this bundle was unable * to be started. * *
  2. If this bundle's state is ACTIVE then this method * returns immediately. * *
  3. If the {@link #START_TRANSIENT} option is not set then set this * bundle's autostart setting to Started with declared activation * if the {@link #START_ACTIVATION_POLICY} option is set or * Started with eager activation if not set. When the Framework is * restarted and this bundle's autostart setting is not Stopped, * this bundle must be automatically started. * *
  4. If this bundle's state is not RESOLVED, an attempt is * made to resolve this bundle. If the Framework cannot resolve this bundle, * a BundleException is thrown. * *
  5. If the {@link #START_ACTIVATION_POLICY} option is set and this * bundle's declared activation policy is {@link Constants#ACTIVATION_LAZY * lazy} then: * * *
  6. This bundle's state is set to STARTING. * *
  7. A bundle event of type {@link BundleEvent#STARTING} is fired. * *
  8. The {@link BundleActivator#start} method of this bundle's * BundleActivator, if one is specified, is called. If the * BundleActivator is invalid or throws an exception then: * * *
  9. If this bundle's state is UNINSTALLED, because this * bundle was uninstalled while the BundleActivator.start * method was running, a BundleException is thrown. * *
  10. This bundle's state is set to ACTIVE. * *
  11. A bundle event of type {@link BundleEvent#STARTED} is fired. *
* * Preconditions * * Postconditions, no exceptions thrown * * Postconditions, when an exception is thrown * * * @param options The options for starting this bundle. See * {@link #START_TRANSIENT} and {@link #START_ACTIVATION_POLICY}. The * Framework must ignore unrecognized options. * @throws BundleException If this bundle could not be started. This could * be because a code dependency could not be resolved or the * specified BundleActivator could not be loaded or * threw an exception or this bundle is a fragment. * @throws IllegalStateException If this bundle has been uninstalled or this * bundle tries to change its own state. * @throws SecurityException If the caller does not have the appropriate * AdminPermission[this,EXECUTE], and the Java Runtime * Environment supports permissions. * @since 1.4 */ public void start(int options) throws BundleException; /** * Starts this bundle with no options. * *

* This method performs the same function as calling start(0). * * @throws BundleException If this bundle could not be started. This could * be because a code dependency could not be resolved or the * specified BundleActivator could not be loaded or * threw an exception or this bundle is a fragment. * @throws IllegalStateException If this bundle has been uninstalled or this * bundle tries to change its own state. * @throws SecurityException If the caller does not have the appropriate * AdminPermission[this,EXECUTE], and the Java Runtime * Environment supports permissions. * @see #start(int) */ public void start() throws BundleException; /** * Stops this bundle. * *

* The following steps are required to stop a bundle: *

    *
  1. If this bundle's state is UNINSTALLED then an * IllegalStateException is thrown. * *
  2. If this bundle is in the process of being activated or deactivated * then this method must wait for activation or deactivation to complete * before continuing. If this does not occur in a reasonable time, a * BundleException is thrown to indicate this bundle was unable * to be stopped. *
  3. If the {@link #STOP_TRANSIENT} option is not set then then set this * bundle's persistent autostart setting to to Stopped. When the * Framework is restarted and this bundle's autostart setting is * Stopped, this bundle must not be automatically started. * *
  4. If this bundle's state is not STARTING or * ACTIVE then this method returns immediately. * *
  5. This bundle's state is set to STOPPING. * *
  6. A bundle event of type {@link BundleEvent#STOPPING} is fired. * *
  7. If this bundle's state was ACTIVE prior to setting the * state to STOPPING, the {@link BundleActivator#stop} method * of this bundle's BundleActivator, if one is specified, is * called. If that method throws an exception, this method must continue to * stop this bundle and a BundleException must be thrown after * completion of the remaining steps. * *
  8. Any services registered by this bundle must be unregistered. *
  9. Any services used by this bundle must be released. *
  10. Any listeners registered by this bundle must be removed. * *
  11. If this bundle's state is UNINSTALLED, because this * bundle was uninstalled while the BundleActivator.stop method * was running, a BundleException must be thrown. * *
  12. This bundle's state is set to RESOLVED. * *
  13. A bundle event of type {@link BundleEvent#STOPPED} is fired. *
* * Preconditions * * Postconditions, no exceptions thrown * * Postconditions, when an exception is thrown * * * @param options The options for stoping this bundle. See * {@link #STOP_TRANSIENT}. The Framework must ignore unrecognized * options. * @throws BundleException If this bundle's BundleActivator * threw an exception or this bundle is a fragment. * @throws IllegalStateException If this bundle has been uninstalled or this * bundle tries to change its own state. * @throws SecurityException If the caller does not have the appropriate * AdminPermission[this,EXECUTE], and the Java Runtime * Environment supports permissions. * @since 1.4 */ public void stop(int options) throws BundleException; /** * Stops this bundle with no options. * *

* This method performs the same function as calling stop(0). * * @throws BundleException If this bundle's BundleActivator * threw an exception or this bundle is a fragment. * @throws IllegalStateException If this bundle has been uninstalled or this * bundle tries to change its own state. * @throws SecurityException If the caller does not have the appropriate * AdminPermission[this,EXECUTE], and the Java Runtime * Environment supports permissions. * @see #start(int) */ public void stop() throws BundleException; /** * Updates this bundle from an InputStream. * *

* If the specified InputStream is null, the * Framework must create the InputStream from which to read the * updated bundle by interpreting, in an implementation dependent manner, * this bundle's {@link Constants#BUNDLE_UPDATELOCATION * Bundle-UpdateLocation} Manifest header, if present, or this bundle's * original location. * *

* If this bundle's state is ACTIVE, it must be stopped before * the update and started after the update successfully completes. * *

* If this bundle has exported any packages that are imported by another * bundle, these packages must not be updated. Instead, the previous package * version must remain exported until the * PackageAdmin.refreshPackages method has been has been called * or the Framework is relaunched. * *

* The following steps are required to update a bundle: *

    *
  1. If this bundle's state is UNINSTALLED then an * IllegalStateException is thrown. * *
  2. If this bundle's state is ACTIVE, STARTING * or STOPPING, this bundle is stopped as described in the * Bundle.stop method. If Bundle.stop throws an * exception, the exception is rethrown terminating the update. * *
  3. The updated version of this bundle is read from the input stream and * installed. If the Framework is unable to install the updated version of * this bundle, the original version of this bundle must be restored and a * BundleException must be thrown after completion of the * remaining steps. * *
  4. This bundle's state is set to INSTALLED. * *
  5. If the updated version of this bundle was successfully installed, a * bundle event of type {@link BundleEvent#UPDATED} is fired. * *
  6. If this bundle's state was originally ACTIVE, the * updated bundle is started as described in the Bundle.start * method. If Bundle.start throws an exception, a Framework * event of type {@link FrameworkEvent#ERROR} is fired containing the * exception. *
* * Preconditions * * Postconditions, no exceptions thrown * * Postconditions, when an exception is thrown * * * @param input The InputStream from which to read the new * bundle or null to indicate the Framework must create * the input stream from this bundle's * {@link Constants#BUNDLE_UPDATELOCATION Bundle-UpdateLocation} * Manifest header, if present, or this bundle's original location. * The input stream must always be closed when this method completes, * even if an exception is thrown. * @throws BundleException If the input stream cannot be read or the update * fails. * @throws IllegalStateException If this bundle has been uninstalled or this * bundle tries to change its own state. * @throws SecurityException If the caller does not have the appropriate * AdminPermission[this,LIFECYCLE] for both the current * bundle and the updated bundle, and the Java Runtime Environment * supports permissions. * @see #stop() * @see #start() */ public void update(InputStream input) throws BundleException; /** * Updates this bundle. * *

* This method performs the same function as calling * {@link #update(InputStream)} with a null InputStream. * * @throws BundleException If the update fails. * @throws IllegalStateException If this bundle has been uninstalled or this * bundle tries to change its own state. * @throws SecurityException If the caller does not have the appropriate * AdminPermission[this,LIFECYCLE] for both the current * bundle and the updated bundle, and the Java Runtime Environment * supports permissions. * @see #update(InputStream) */ public void update() throws BundleException; /** * Uninstalls this bundle. * *

* This method causes the Framework to notify other bundles that this bundle * is being uninstalled, and then puts this bundle into the * UNINSTALLED state. The Framework must remove any resources * related to this bundle that it is able to remove. * *

* If this bundle has exported any packages, the Framework must continue to * make these packages available to their importing bundles until the * PackageAdmin.refreshPackages method has been called or the * Framework is relaunched. * *

* The following steps are required to uninstall a bundle: *

    *
  1. If this bundle's state is UNINSTALLED then an * IllegalStateException is thrown. * *
  2. If this bundle's state is ACTIVE, STARTING * or STOPPING, this bundle is stopped as described in the * Bundle.stop method. If Bundle.stop throws an * exception, a Framework event of type {@link FrameworkEvent#ERROR} is * fired containing the exception. * *
  3. This bundle's state is set to UNINSTALLED. * *
  4. A bundle event of type {@link BundleEvent#UNINSTALLED} is fired. * *
  5. This bundle and any persistent storage area provided for this bundle * by the Framework are removed. *
* * Preconditions * * Postconditions, no exceptions thrown * * Postconditions, when an exception is thrown * * * @throws BundleException If the uninstall failed. This can occur if * another thread is attempting to change this bundle's state and * does not complete in a timely manner. * @throws IllegalStateException If this bundle has been uninstalled or this * bundle tries to change its own state. * @throws SecurityException If the caller does not have the appropriate * AdminPermission[this,LIFECYCLE], and the Java * Runtime Environment supports permissions. * @see #stop() */ public void uninstall() throws BundleException; /** * Returns this bundle's Manifest headers and values. This method returns * all the Manifest headers and values from the main section of this * bundle's Manifest file; that is, all lines prior to the first blank line. * *

* Manifest header names are case-insensitive. The methods of the returned * Dictionary object must operate on header names in a * case-insensitive manner. * * If a Manifest header value starts with "%", it must be * localized according to the default locale. If no localization is found * for a header value, the header value without the leading "%" is * returned. * *

* For example, the following Manifest headers and values are included if * they are present in the Manifest file: * * 

     *     Bundle-Name
     *     Bundle-Vendor
     *     Bundle-Version
     *     Bundle-Description
     *     Bundle-DocURL
     *     Bundle-ContactAddress
     *
* *

* This method must continue to return Manifest header information while * this bundle is in the UNINSTALLED state. * * @return A Dictionary object containing this bundle's * Manifest headers and values. * @throws SecurityException If the caller does not have the * appropriate AdminPermission[this,METADATA], and * the Java Runtime Environment supports permissions. * @see Constants#BUNDLE_LOCALIZATION */ public Dictionary/* */getHeaders(); /** * Returns this bundle's unique identifier. This bundle is assigned a unique * identifier by the Framework when it was installed in the OSGi * environment. * *

* A bundle's unique identifier has the following attributes: *

* *

* This method must continue to return this bundle's unique identifier while * this bundle is in the UNINSTALLED state. * * @return The unique identifier of this bundle. */ public long getBundleId(); /** * Returns this bundle's location identifier. * *

* The location identifier is the location passed to * BundleContext.installBundle when a bundle is installed. * The location identifier does not change while this bundle remains * installed, even if this bundle is updated. * *

* This method must continue to return this bundle's location identifier * while this bundle is in the UNINSTALLED state. * * @return The string representation of this bundle's location identifier. * @throws SecurityException If the caller does not have the * appropriate AdminPermission[this,METADATA], and * the Java Runtime Environment supports permissions. */ public String getLocation(); /** * Returns this bundle's ServiceReference list for all * services it has registered or null if this bundle has no * registered services. * *

* If the Java runtime supports permissions, a ServiceReference * object to a service is included in the returned list only if the caller * has the ServicePermission to get the service using at * least one of the named classes the service was registered under. * *

* The list is valid at the time of the call to this method, however, as the * Framework is a very dynamic environment, services can be modified or * unregistered at anytime. * * @return An array of ServiceReference objects or * null. * @throws IllegalStateException If this bundle has been * uninstalled. * @see ServiceRegistration * @see ServiceReference * @see ServicePermission */ public ServiceReference[] getRegisteredServices(); /** * Returns this bundle's ServiceReference list for all * services it is using or returns null if this bundle is not * using any services. A bundle is considered to be using a service if its * use count for that service is greater than zero. * *

* If the Java Runtime Environment supports permissions, a * ServiceReference object to a service is included in the * returned list only if the caller has the ServicePermission * to get the service using at least one of the named classes the service * was registered under. *

* The list is valid at the time of the call to this method, however, as the * Framework is a very dynamic environment, services can be modified or * unregistered at anytime. * * @return An array of ServiceReference objects or * null. * @throws IllegalStateException If this bundle has been * uninstalled. * @see ServiceReference * @see ServicePermission */ public ServiceReference[] getServicesInUse(); /** * Determines if this bundle has the specified permissions. * *

* If the Java Runtime Environment does not support permissions, this method * always returns true. *

* permission is of type Object to avoid * referencing the java.security.Permission class directly. * This is to allow the Framework to be implemented in Java environments * which do not support permissions. * *

* If the Java Runtime Environment does support permissions, this bundle and * all its resources including embedded JAR files, belong to the same * java.security.ProtectionDomain; that is, they must share * the same set of permissions. * * @param permission The permission to verify. * @return true if this bundle has the specified permission * or the permissions possessed by this bundle imply the specified * permission; false if this bundle does not have the * specified permission or permission is not an * instanceof java.security.Permission. * @throws IllegalStateException If this bundle has been * uninstalled. */ public boolean hasPermission(Object permission); /** * Find the specified resource from this bundle's class loader. * * This bundle's class loader is called to search for the specified * resource. If this bundle's state is INSTALLED, this method * must attempt to resolve this bundle before attempting to get the * specified resource. If this bundle cannot be resolved, then only this * bundle must be searched for the specified resource. Imported packages * cannot be searched when this bundle has not been resolved. If this bundle * is a fragment bundle then null is returned. *

* Note: Jar and zip files are not required to include directory entries. * URLs to directory entries will not be returned if the bundle contents do * not contain directory entries. * * @param name The name of the resource. See * ClassLoader.getResource for a description of the * format of a resource name. * @return A URL to the named resource, or null if the resource * could not be found or if this bundle is a fragment bundle or if * the caller does not have the appropriate * AdminPermission[this,RESOURCE], and the Java Runtime * Environment supports permissions. * @throws IllegalStateException If this bundle has been uninstalled. * @see #getEntry * @see #findEntries * @since 1.1 */ public URL getResource(String name); /** * Returns this bundle's Manifest headers and values localized to the * specified locale. * *

* This method performs the same function as * Bundle.getHeaders() except the manifest header values are * localized to the specified locale. * *

* If a Manifest header value starts with "%", it must be * localized according to the specified locale. If a locale is specified and * cannot be found, then the header values must be returned using the * default locale. Localizations are searched for in the following order: * * 

     *   bn + "_" + Ls + "_" + Cs + "_" + Vs
     *   bn + "_" + Ls + "_" + Cs
     *   bn + "_" + Ls
     *   bn + "_" + Ld + "_" + Cd + "_" + Vd
     *   bn + "_" + Ld + "_" + Cd
     *   bn + "_" + Ld
     *   bn
     *
* * Where bn is this bundle's localization basename, * Ls, Cs and Vs are the * specified locale (language, country, variant) and Ld, * Cd and Vd are the default locale (language, * country, variant). * * If null is specified as the locale string, the header * values must be localized using the default locale. If the empty string * ("") is specified as the locale string, the header values must * not be localized and the raw (unlocalized) header values, including any * leading "%", must be returned. If no localization is found for * a header value, the header value without the leading "%" is * returned. * *

* This method must continue to return Manifest header information while * this bundle is in the UNINSTALLED state, however the * header values must only be available in the raw and default locale * values. * * @param locale The locale name into which the header values are to be * localized. If the specified locale is null then the * locale returned by java.util.Locale.getDefault is * used. If the specified locale is the empty string, this method * will return the raw (unlocalized) manifest headers including any * leading "%". * @return A Dictionary object containing this bundle's * Manifest headers and values. * @throws SecurityException If the caller does not have the * appropriate AdminPermission[this,METADATA], and * the Java Runtime Environment supports permissions. * @see #getHeaders() * @see Constants#BUNDLE_LOCALIZATION * @since 1.3 */ public Dictionary/* */getHeaders(String locale); /** * Returns the symbolic name of this bundle as specified by its * Bundle-SymbolicName manifest header. The bundle symbolic * name together with a version must identify a unique bundle. The bundle * symbolic name should be based on the reverse domain name naming * convention like that used for java packages. * *

* This method must continue to return this bundle's symbolic name while * this bundle is in the UNINSTALLED state. * * @return The symbolic name of this bundle or null if this * bundle does not have a symbolic name. * @since 1.3 */ public String getSymbolicName(); /** * Loads the specified class using this bundle's class loader. * *

* If this bundle is a fragment bundle then this method must throw a * ClassNotFoundException. * *

* If this bundle's state is INSTALLED, this method must * attempt to resolve this bundle before attempting to load the class. * *

* If this bundle cannot be resolved, a Framework event of type * {@link FrameworkEvent#ERROR} is fired containing a * BundleException with details of the reason this bundle * could not be resolved. This method must then throw a * ClassNotFoundException. * *

* If this bundle's state is UNINSTALLED, then an * IllegalStateException is thrown. * * @param name The name of the class to load. * @return The Class object for the requested class. * @throws ClassNotFoundException If no such class can be found or * if this bundle is a fragment bundle or if the caller does not * have the appropriate AdminPermission[this,CLASS], * and the Java Runtime Environment supports permissions. * @throws IllegalStateException If this bundle has been * uninstalled. * @since 1.3 */ public Class loadClass(String name) throws ClassNotFoundException; /** * Find the specified resources from this bundle's class loader. * * This bundle's class loader is called to search for the specified * resources. If this bundle's state is INSTALLED, this method * must attempt to resolve this bundle before attempting to get the * specified resources. If this bundle cannot be resolved, then only this * bundle must be searched for the specified resources. Imported packages * cannot be searched when a bundle has not been resolved. If this bundle is * a fragment bundle then null is returned. *

* Note: Jar and zip files are not required to include directory entries. * URLs to directory entries will not be returned if the bundle contents do * not contain directory entries. * * @param name The name of the resource. See * ClassLoader.getResources for a description of the * format of a resource name. * @return An enumeration of URLs to the named resources, or * null if the resource could not be found or if this * bundle is a fragment bundle or if the caller does not have the * appropriate AdminPermission[this,RESOURCE], and the * Java Runtime Environment supports permissions. * @throws IllegalStateException If this bundle has been uninstalled. * @throws IOException If there is an I/O error. * @since 1.3 */ public Enumeration/* */getResources(String name) throws IOException; /** * Returns an Enumeration of all the paths (String objects) * to entries within this bundle whose longest sub-path matches the * specified path. This bundle's class loader is not used to search for * entries. Only the contents of this bundle are searched. *

* The specified path is always relative to the root of this bundle and may * begin with a "/". A path value of "/" indicates the * root of this bundle. *

* Returned paths indicating subdirectory paths end with a "/". * The returned paths are all relative to the root of this bundle and must * not begin with "/". *

* Note: Jar and zip files are not required to include directory entries. * Paths to directory entries will not be returned if the bundle contents do * not contain directory entries. * * @param path The path name for which to return entry paths. * @return An Enumeration of the entry paths (String * objects) or null if no entry could be found or if * the caller does not have the appropriate * AdminPermission[this,RESOURCE] and the Java * Runtime Environment supports permissions. * @throws IllegalStateException If this bundle has been * uninstalled. * @since 1.3 */ public Enumeration/* */getEntryPaths(String path); /** * Returns a URL to the entry at the specified path in this bundle. This * bundle's class loader is not used to search for the entry. Only the * contents of this bundle are searched for the entry. *

* The specified path is always relative to the root of this bundle and may * begin with "/". A path value of "/" indicates the * root of this bundle. *

* Note: Jar and zip files are not required to include directory entries. * URLs to directory entries will not be returned if the bundle contents do * not contain directory entries. * * @param path The path name of the entry. * @return A URL to the entry, or null if no entry could be * found or if the caller does not have the appropriate * AdminPermission[this,RESOURCE] and the Java * Runtime Environment supports permissions. * @throws IllegalStateException If this bundle has been * uninstalled. * @since 1.3 */ public URL getEntry(String path); /** * Returns the time when this bundle was last modified. A bundle is * considered to be modified when it is installed, updated or uninstalled. * *

* The time value is the number of milliseconds since January 1, 1970, * 00:00:00 GMT. * * @return The time when this bundle was last modified. * @since 1.3 */ public long getLastModified(); /** * Returns entries in this bundle and its attached fragments. This bundle's * class loader is not used to search for entries. Only the contents of this * bundle and its attached fragments are searched for the specified entries. * * If this bundle's state is INSTALLED, this method must * attempt to resolve this bundle before attempting to find entries. * *

* This method is intended to be used to obtain configuration, setup, * localization and other information from this bundle. This method takes * into account that the "contents" of this bundle can be extended * with fragments. This "bundle space" is not a namespace with * unique members; the same entry name can be present multiple times. This * method therefore returns an enumeration of URL objects. These URLs can * come from different JARs but have the same path name. This method can * either return only entries in the specified path or recurse into * subdirectories returning entries in the directory tree beginning at the * specified path. Fragments can be attached after this bundle is resolved, * possibly changing the set of URLs returned by this method. If this bundle * is not resolved, only the entries in the JAR file of this bundle are * returned. *

* Examples: * * 

     * // List all XML files in the OSGI-INF directory and below
     * Enumeration e = b.findEntries("OSGI-INF", "*.xml", true);
     * 
     * // Find a specific localization file
     * Enumeration e = b
     *      .findEntries("OSGI-INF/l10n", "bundle_nl_DU.properties", false);
     * if (e.hasMoreElements())
     *  return (URL) e.nextElement();
     *
* *

* Note: Jar and zip files are not required to include directory entries. * URLs to directory entries will not be returned if the bundle contents do * not contain directory entries. * * @param path The path name in which to look. The path is always relative * to the root of this bundle and may begin with "/". A * path value of "/" indicates the root of this bundle. * @param filePattern The file name pattern for selecting entries in the * specified path. The pattern is only matched against the last * element of the entry path. If the entry is a directory then the * trailing "/" is not used for pattern matching. Substring * matching is supported, as specified in the Filter specification, * using the wildcard character ("*"). If null is * specified, this is equivalent to "*" and matches all * files. * @param recurse If true, recurse into subdirectories. * Otherwise only return entries from the specified path. * @return An enumeration of URL objects for each matching entry, or * null if an entry could not be found or if the caller * does not have the appropriate * AdminPermission[this,RESOURCE], and the Java Runtime * Environment supports permissions. The URLs are sorted such that * entries from this bundle are returned first followed by the * entries from attached fragments in ascending bundle id order. If * this bundle is a fragment, then only matching entries in this * fragment are returned. * @throws IllegalStateException If this bundle has been uninstalled. * @since 1.3 */ public Enumeration/* */findEntries(String path, String filePattern, boolean recurse); /** * Returns this bundle's {@link BundleContext}. The returned * BundleContext can be used by the caller to act on behalf * of this bundle. * *

* If this bundle is not in the {@link #STARTING}, {@link #ACTIVE}, or * {@link #STOPPING} states or this bundle is a fragment bundle, then this * bundle has no valid BundleContext. This method will * return null if this bundle has no valid * BundleContext. * * @return A BundleContext for this bundle or * null if this bundle has no valid * BundleContext. * @throws SecurityException If the caller does not have the * appropriate AdminPermission[this,CONTEXT], and * the Java Runtime Environment supports permissions. * @since 1.4 */ public BundleContext getBundleContext(); /** * Return the certificates for the signers of this bundle and the * certificate chains for those signers. * * @param signersType If {@link #SIGNERS_ALL} is specified, then information * on all signers of this bundle is returned. If * {@link #SIGNERS_TRUSTED} is specified, then only information on * the signers of this bundle trusted by the framework is returned. * @return The X509Certificates for the signers of this bundle * and the X509Certificate chains for those signers. * The keys of the Map are the * X509Certificates of the signers of this bundle. The * value for a key is a List containing the * X509Certificate chain for the signer. The first item * in the List is the signer's * X509Certificate which is then followed by the rest * of the X509Certificate chain. The returned * Map will be empty if there are no signers. The * returned Map is the property of the caller who is * free to modify it. * @throws IllegalArgumentException If the specified * signersType is not {@link #SIGNERS_ALL} or * {@link #SIGNERS_TRUSTED}. * @since 1.5 */ public Map/* > */getSignerCertificates( int signersType); /** * Returns the version of this bundle as specified by its * Bundle-Version manifest header. If this bundle does not have a * specified version then {@link Version#emptyVersion} is returned. * *

* This method must continue to return this bundle's version while * this bundle is in the UNINSTALLED state. * * @return The version of this bundle. * @since 1.5 */ public Version getVersion(); /** * Adapt this bundle to the specified type. * *

* Adapting this bundle to the specified type may require certain checks, * including security checks, to succeed. If a check does not succeed, then * this bundle cannot be adapted and {@code null} is returned. * * @param The type to which this bundle is to be adapted. * @param type Class object for the type to which this bundle is to be * adapted. * @return The object, of the specified type, to which this bundle has been * adapted or {@code null} if this bundle cannot be adapted to the * specified type. * @throws SecurityException If the caller does not have the appropriate * {@code AdaptPermission[type,this,ADAPT]}, and the Java Runtime * Environment supports permissions. * @since 1.6 */ A adapt(Class type); }