org.osgi.framework.Bundle Maven / Gradle / Ivy
/*
* 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:
*
* - {@link #UNINSTALLED}
*
- {@link #INSTALLED}
*
- {@link #RESOLVED}
*
- {@link #STARTING}
*
- {@link #STOPPING}
*
- {@link #ACTIVE}
*
*
* 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: 6906 $
*/
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:
*
* - The bundle's class path from its {@link Constants#BUNDLE_CLASSPATH}
* Manifest header.
*
- The bundle's package dependencies from its
* {@link Constants#EXPORT_PACKAGE} and {@link Constants#IMPORT_PACKAGE}
* Manifest headers.
*
- The bundle's required bundle dependencies from its
* {@link Constants#REQUIRE_BUNDLE} Manifest header.
*
- A fragment bundle's host dependency from its
* {@link Constants#FRAGMENT_HOST} Manifest header.
*
*
* 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:
*
* - If the {@link #START_TRANSIENT} option is set, then a
*
BundleException is thrown indicating this bundle cannot be
* started due to the Framework's current start level.
*
* - Otherwise, the Framework must set this bundle's persistent 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'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:
*
* - 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.
*
* - If this bundle's state is
ACTIVE then this method
* returns immediately.
*
* - 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.
*
*
- 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.
*
* - If the {@link #START_ACTIVATION_POLICY} option is set and this
* bundle's declared activation policy is {@link Constants#ACTIVATION_LAZY
* lazy} then:
*
* - If this bundle's state is
STARTING then this method
* returns immediately.
* - This bundle's state is set to
STARTING.
* - A bundle event of type {@link BundleEvent#LAZY_ACTIVATION} is fired.
*
- This method returns immediately and the remaining steps will be
* followed when this bundle's activation is later triggered.
*
*
* - This bundle's state is set to
STARTING.
*
* - A bundle event of type {@link BundleEvent#STARTING} is fired.
*
*
- 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:
*
* - This bundle's state is set to
STOPPING.
* - A bundle event of type {@link BundleEvent#STOPPING} is fired.
*
- Any services registered by this bundle must be unregistered.
*
- Any services used by this bundle must be released.
*
- Any listeners registered by this bundle must be removed.
*
- This bundle's state is set to
RESOLVED.
* - A bundle event of type {@link BundleEvent#STOPPED} is fired.
*
- A
BundleException is then thrown.
*
*
* - If this bundle's state is
UNINSTALLED, because this
* bundle was uninstalled while the BundleActivator.start
* method was running, a BundleException is thrown.
*
* - This bundle's state is set to
ACTIVE.
*
* - A bundle event of type {@link BundleEvent#STARTED} is fired.
*
*
* Preconditions
*
* getState() in { INSTALLED,
* RESOLVED } or { INSTALLED,
* RESOLVED, STARTING } if this bundle has
* a lazy activation policy.
*
* Postconditions, no exceptions thrown
*
* - Bundle autostart setting is modified unless the
* {@link #START_TRANSIENT} option was set.
*
getState() in { ACTIVE }
* unless the lazy activation policy was used.
* BundleActivator.start() has been called and did not
* throw an exception unless the lazy activation policy was used.
*
* Postconditions, when an exception is thrown
*
* - Depending on when the exception occurred, bundle autostart setting is
* modified unless the {@link #START_TRANSIENT} option was set.
*
getState() not in { STARTING,
* ACTIVE }.
*
*
* @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:
*
* - If this bundle's state is
UNINSTALLED then an
* IllegalStateException is thrown.
*
* - 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.
* - 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.
*
*
- If this bundle's state is not
STARTING or
* ACTIVE then this method returns immediately.
*
* - This bundle's state is set to
STOPPING.
*
* - A bundle event of type {@link BundleEvent#STOPPING} is fired.
*
*
- 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.
*
* - Any services registered by this bundle must be unregistered.
*
- Any services used by this bundle must be released.
*
- Any listeners registered by this bundle must be removed.
*
*
- If this bundle's state is
UNINSTALLED, because this
* bundle was uninstalled while the BundleActivator.stop method
* was running, a BundleException must be thrown.
*
* - This bundle's state is set to
RESOLVED.
*
* - A bundle event of type {@link BundleEvent#STOPPED} is fired.
*
*
* Preconditions
*
* getState() in { ACTIVE }.
*
* Postconditions, no exceptions thrown
*
* - Bundle autostart setting is modified unless the
* {@link #STOP_TRANSIENT} option was set.
*
getState() not in { ACTIVE,
* STOPPING }.
* BundleActivator.stop has been called and did not throw
* an exception.
*
* Postconditions, when an exception is thrown
*
* - Bundle autostart setting is modified unless the
* {@link #STOP_TRANSIENT} option was set.
*
*
* @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:
*
* - If this bundle's state is
UNINSTALLED then an
* IllegalStateException is thrown.
*
* - 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.
*
* - 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.
*
* - This bundle's state is set to
INSTALLED.
*
* - If the updated version of this bundle was successfully installed, a
* bundle event of type {@link BundleEvent#UPDATED} is fired.
*
*
- 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
*
* getState() not in { UNINSTALLED
* }.
*
* Postconditions, no exceptions thrown
*
* getState() in { INSTALLED,
* RESOLVED, ACTIVE }.
* - This bundle has been updated.
*
* Postconditions, when an exception is thrown
*
* getState() in { INSTALLED,
* RESOLVED, ACTIVE }.
* - Original bundle is still used; no update occurred.
*
*
* @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:
*
* - If this bundle's state is
UNINSTALLED then an
* IllegalStateException is thrown.
*
* - 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.
*
* - This bundle's state is set to
UNINSTALLED.
*
* - A bundle event of type {@link BundleEvent#UNINSTALLED} is fired.
*
*
- This bundle and any persistent storage area provided for this bundle
* by the Framework are removed.
*
*
* Preconditions
*
* getState() not in { UNINSTALLED
* }.
*
* Postconditions, no exceptions thrown
*
* getState() in { UNINSTALLED
* }.
* - This bundle has been uninstalled.
*
* Postconditions, when an exception is thrown
*
* getState() not in { UNINSTALLED
* }.
* - This Bundle has not been uninstalled.
*
*
* @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:
*
* - Is unique and persistent.
*
- Is a
long.
* - Its value is not reused for another bundle, even after a bundle is
* uninstalled.
*
- Does not change while a bundle remains installed.
*
- Does not change when a bundle is updated.
*
*
*
* 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();
}