org.apache.felix.framework

## Class Felix

- java.lang.Object
- - org.apache.felix.framework.Felix

All Implemented Interfaces:
  Comparable<Bundle>, Bundle, BundleReference, Framework, BundleRevisions

    public class Felix
    extends Object
    implements Framework

### Field Summary

### Fields inherited from interface org.osgi.framework.Bundle

`ACTIVE, INSTALLED, RESOLVED, SIGNERS_ALL, SIGNERS_TRUSTED, START_ACTIVATION_POLICY, START_TRANSIENT, STARTING, STOP_TRANSIENT, STOPPING, UNINSTALLED`

### Constructor Summary

Constructors
Constructor and Description
`Felix(Map configMap)` This constructor creates a framework instance with a specified `Map` of configuration properties.
`Felix(Map configMap, ModuleConnector connectFramework)`

### Method Summary

All Methods Instance Methods Concrete Methods
`<A> A` `adapt(Class<A> type)` Adapt this bundle to the specified type.
`int` `compareTo(Bundle t)`
`Enumeration` `findEntries(String path, String filePattern, boolean recurse)` Returns entries in this bundle and its attached fragments.
`Bundle` `getBundle()` Returns the `Bundle` object associated with this `BundleReference`.
`BundleContext` `getBundleContext()` Returns this bundle's `BundleContext`.
`long` `getBundleId()` Returns this bundle's unique identifier.
`File` `getDataFile(String filename)` Creates a `File` object for a file in the persistent storage area provided for this bundle by the Framework.
`URL` `getEntry(String name)` Returns a URL to the entry at the specified path in this bundle.
`Enumeration` `getEntryPaths(String path)` Returns an Enumeration of all the paths (`String` objects) to entries within this bundle whose longest sub-path matches the specified path.
`Dictionary` `getHeaders()` Returns this bundle's Manifest headers and values.
`Dictionary` `getHeaders(String locale)` Returns this bundle's Manifest headers and values localized to the specified locale.
`long` `getLastModified()` Returns the time when this bundle was last modified.
`String` `getLocation()` Returns this bundle's location identifier.
`int` `getPersistentState()`
`ServiceReference[]` `getRegisteredServices()` Returns an array of service references corresponding to the bundle's registered services.
`URL` `getResource(String name)` Returns a URL to a named resource in the bundle.
`Enumeration` `getResources(String name)` Find the specified resources from this bundle's class loader.
`List<BundleRevision>` `getRevisions()` Return the bundle revisions for the `referenced` bundle.
`ServiceReference[]` `getServicesInUse()` Returns this bundle's `ServiceReference` list for all services it is using or returns `null` if this bundle is not using any services.
`Map` `getSignerCertificates(int signersType)` Return the certificates for the signers of this bundle and the certificate chains for those signers.
`int` `getState()` Returns this bundle's current state.
`String` `getSymbolicName()` Returns the symbolic name of this bundle as specified by its `Bundle-SymbolicName` manifest header.
`Version` `getVersion()` Returns the version of this bundle as specified by its `Bundle-Version` manifest header.
`boolean` `hasConnectFramework()`
`boolean` `hasPermission(Object obj)` Determines if this bundle has the specified permissions.
`void` `init()` Initialize this Framework.
`void` `init(FrameworkListener... listeners)` Initialize this Framework.
`Class` `loadClass(String name)` Loads the specified class using this bundle's class loader.
`void` `setPersistentStateActive()`
`void` `setPersistentStateInactive()`
`void` `setPersistentStateUninstalled()`
`void` `start()` This method starts the framework instance, which will transition the framework from start level 0 to its active start level as specified in its configuration properties (1 by default).
`void` `start(int options)` Starts this bundle.
`void` `stop()` This method asynchronously shuts down the framework, it must be called at the end of a session in order to shutdown all active bundles.
`void` `stop(int options)` Stops this bundle.
`String` `toString()`
`void` `uninstall()` Uninstalls this bundle.
`void` `update()` Updates this bundle.
`void` `update(InputStream is)` Updates this bundle from an `InputStream`.
`FrameworkEvent` `waitForStop(long timeout)` This method will cause the calling thread to block until the framework shuts down.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface org.osgi.framework.launch.Framework

`findEntries, getEntry, getEntryPaths, getLocation, getSymbolicName`

### Methods inherited from interface org.osgi.framework.Bundle

`getBundleContext, getDataFile, getHeaders, getHeaders, getRegisteredServices, getResource, getResources, getServicesInUse, getSignerCertificates, getState, getVersion, loadClass`

### Methods inherited from interface java.lang.Comparable

`compareTo`

### Constructor Detail

#### Felix

    public Felix(Map configMap)

This constructor creates a framework instance with a specified `Map` of configuration properties. Configuration properties are used internally by the framework to alter its default behavior. The configuration properties should have a `String` key and an `Object` value. The passed in `Map` is copied by the framework and all keys are converted to `String`s.

Configuration properties are generally the sole means to configure the framework's default behavior; the framework does not typically refer to any system properties for configuration information. If a `Map` is supplied to this method for configuration properties, then the framework will consult the `Map` instance for any and all configuration properties. It is possible to specify a `null` for the configuration property map, in which case the framework will use its default behavior in all cases.

The following configuration properties can be specified (properties starting with "`felix`" are specific to Felix, while those starting with "`org.osgi`" are standard OSGi properties):

- `org.osgi.framework.storage` - Sets the directory to use as the bundle cache; by default bundle cache directory is `felix-cache` in the current working directory. The value should be a valid directory name. The directory name can be either absolute or relative. Relative directory names are relative to the current working directory. The specified directory will be created if it does not exist.
- `org.osgi.framework.storage.clean` - Determines whether the bundle cache is flushed. The value can either be "`none`" or "`onFirstInit`", where "`none`" does not flush the bundle cache and "`onFirstInit`" flushes the bundle cache when the framework instance is first initialized. The default value is "`none`".
- `felix.cache.rootdir` - Sets the root directory to use to calculate the bundle cache directory for relative directory names. If `org.osgi.framework.storage` is set to a relative name, by default it is relative to the current working directory. If this property is set, then it will be calculated as being relative to the specified root directory.
- `felix.cache.filelimit` - The integer value of this string sets an upper limit on how many files the cache will open. The default value is zero, which means there is no limit.
- `felix.cache.locking` - Enables or disables bundle cache locking, which is used to prevent concurrent access to the bundle cache. This is enabled by default, but on older/smaller JVMs file channel locking is not available; set this property to `false` to disable it.
- `felix.cache.bufsize` - Sets the buffer size to be used by the cache; the default value is 4096. The integer value of this string provides control over the size of the internal buffer of the disk cache for performance reasons.
- `org.osgi.framework.system.packages` - Specifies a comma-delimited list of packages that should be exported via the System Bundle from the parent class loader. The framework will set this to a reasonable default. If the value is specified, it replaces any default value.
- `org.osgi.framework.system.packages.extra` - Specifies a comma-delimited list of packages that should be exported via the System Bundle from the parent class loader in addition to the packages in `org.osgi.framework.system.packages`. The default value is empty. If a value is specified, it is appended to the list of default or specified packages in `org.osgi.framework.system.packages`.
- `org.osgi.framework.bootdelegation` - Specifies a comma-delimited list of packages that should be made implicitly available to all bundles from the parent class loader. It is recommended not to use this property since it breaks modularity. The default value is empty.
- `felix.systembundle.activators` - A `List` of `BundleActivator` instances that are started/stopped when the System Bundle is started/stopped. The specified instances will receive the System Bundle's `BundleContext` when invoked.
- `felix.log.logger` - An instance of `Logger` that the framework uses as its default logger.
- `felix.log.level` - An integer value indicating the degree of logging reported by the framework; the higher the value the more logging is reported. If zero ('0') is specified, then logging is turned off completely. The log levels match those specified in the OSGi Log Service (i.e., 1 = error, 2 = warning, 3 = information, and 4 = debug). The default value is 1.
- `org.osgi.framework.startlevel.beginning` - The initial start level of the framework once it starts execution; the default value is 1.
- `felix.startlevel.bundle` - The default start level for newly installed bundles; the default value is 1.
- `felix.service.urlhandlers` - Flag to indicate whether to activate the URL Handlers service for the framework instance; the default value is "`true`". Activating the URL Handlers service will result in the `URL.setURLStreamHandlerFactory()` and `URLConnection.setContentHandlerFactory()` being called.
- `felix.fragment.validation` - Determines if installing unsupported fragment bundles throws an exception or logs a warning. Possible values are "`exception`" or "`warning`". The default value is "`exception`".
- `felix.security.defaultpolicy` - Flag to indicate whether to consult the default java securtiy policy if no security extension is present. The default value is "`false`".

The `Main` class implements some functionality for default property file handling, which makes it possible to specify configuration properties and framework properties in files that are automatically loaded when starting the framework. If you plan to create your own framework instance, you may be able to take advantage of the features it provides; refer to its class documentation for more information.

The framework is not actually started until the `start()` method is called.

Parameters:
  `configMap` - A map for obtaining configuration properties, may be `null`.

#### Felix

    public Felix(Map configMap,
                 ModuleConnector connectFramework)

### Method Detail

#### adapt

    public <A> A adapt(Class<A> type)

Description copied from interface: `Bundle`
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 `null` is returned.

Specified by:
  `adapt` in interface `Bundle`
Specified by:
  `adapt` in interface `Framework`
Type Parameters:
  `A` - The type to which this bundle is to be adapted.
Parameters:
  `type` - Class object for the type to which this bundle is to be adapted.
Returns:
  The object, of the specified type, to which this bundle has been adapted or `null` if this bundle cannot be adapted to the specified type.

#### getBundleId

    public long getBundleId()

Description copied from interface: `Bundle`
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.

Specified by:
  `getBundleId` in interface `Bundle`
Specified by:
  `getBundleId` in interface `Framework`
Returns:
  The unique identifier of this bundle.
See Also:
  `Bundle.getBundleId()`

#### getLastModified

    public long getLastModified()

Description copied from interface: `Bundle`
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 UTC.

Specified by:
  `getLastModified` in interface `Bundle`
Specified by:
  `getLastModified` in interface `Framework`
Returns:
  The time when this bundle was last modified.

#### getPersistentState

    public int getPersistentState()

#### setPersistentStateInactive

    public void setPersistentStateInactive()

#### setPersistentStateActive

    public void setPersistentStateActive()

#### setPersistentStateUninstalled

    public void setPersistentStateUninstalled()

#### hasPermission

    public boolean hasPermission(Object obj)

Description copied from interface: `Bundle`
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.

Specified by:
  `hasPermission` in interface `Bundle`
Parameters:
  `obj` - The permission to verify.
Returns:
  `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`.

#### init

    public void init()
              throws BundleException

Description copied from interface: `Framework`
Initialize this Framework.

This method performs the same function as calling `Framework.init(FrameworkListener...)` with no framework listeners.

Specified by:
  `init` in interface `Framework`
Throws:
  `BundleException` - If this Framework could not be initialized.
See Also:
  `Framework.init(FrameworkListener...)`

#### init

    public void init(FrameworkListener... listeners)
              throws BundleException

Description copied from interface: `Framework`
Initialize this Framework. After calling this method, this Framework must:

- Have generated a new `framework UUID`.
- Be in the `Bundle.STARTING` state.
- Have a valid Bundle Context.
- Be at start level 0.
- Have event handling enabled.
- Have reified Bundle objects for all installed bundles.
- Have registered any framework services. For example, `ConditionalPermissionAdmin`.
- Be `adaptable` to the OSGi defined types to which a system bundle can be adapted.
- Have called the `start` method of the extension bundle activator for all resolved extension bundles.

This Framework will not actually be started until `start` is called.

This method does nothing if called when this Framework is in the `Bundle.STARTING`, `Bundle.ACTIVE` or `Bundle.STOPPING` states.

All framework events fired by this method are also delivered to the specified FrameworkListeners in the order they are specified before returning from this method. After returning from this method the specified listeners are no longer notified of framework events.

Specified by:
  `init` in interface `Framework`
Parameters:
  `listeners` - Zero or more listeners to be notified when framework events occur while initializing the framework. The specified listeners do not need to be otherwise registered with the framework. If a specified listener is registered with the framework, it will be notified twice for each framework event.
Throws:
  `BundleException` - If this Framework could not be initialized.
See Also:
  `Framework.init(org.osgi.framework.FrameworkListener[])`

#### start

    public void start()
               throws BundleException

This method starts the framework instance, which will transition the framework from start level 0 to its active start level as specified in its configuration properties (1 by default). If the `init()` was not explicitly invoked before calling this method, then it will be implicitly invoked before starting the framework.

Specified by:
  `start` in interface `Bundle`
Specified by:
  `start` in interface `Framework`
Throws:
  `BundleException` - if any error occurs.
See Also:
  `Bundle.start(int)`

#### start

    public void start(int options)
               throws BundleException

Description copied from interface: `Bundle`
Starts this bundle.

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

If the current start level is less than this bundle's start level:

- If the `Bundle.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 `Bundle.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:

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 the `Bundle.START_TRANSIENT` option is not set then set this bundle's autostart setting to Started with declared activation if the `Bundle.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.
3. If this bundle's state is `ACTIVE` then this method returns immediately.
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 `Bundle.START_ACTIVATION_POLICY` option is set and this bundle's declared activation policy is `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 `BundleEvent.LAZY_ACTIVATION` is fired.
   - This method returns immediately and the remaining steps will be followed when this bundle's activation is later triggered.
6. This bundle's state is set to `STARTING`.
7. A bundle event of type `BundleEvent.STARTING` is fired.
8. The `BundleActivator.start(BundleContext)` 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 `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 `BundleEvent.STOPPED` is fired.
   - A `BundleException` is then thrown.
9. This bundle's state is set to `ACTIVE`.
10. A bundle event of type `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 `Bundle.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 `Bundle.START_TRANSIENT` option was set.
- `getState()` not in { `STARTING`, `ACTIVE` }.

Specified by:
  `start` in interface `Bundle`
Specified by:
  `start` in interface `Framework`
Parameters:
  `options` - The options for starting this bundle. See `Bundle.START_TRANSIENT` and `Bundle.START_ACTIVATION_POLICY`. The Framework must ignore unrecognized options.
Throws:
  `BundleException` - If this bundle could not be started. BundleException types thrown by this method include: `BundleException.START_TRANSIENT_ERROR`, `BundleException.NATIVECODE_ERROR`, `BundleException.RESOLVE_ERROR`, `BundleException.STATECHANGE_ERROR`, and `BundleException.ACTIVATOR_ERROR`.
See Also:
  `Framework.start()`

#### stop

    public void stop()
              throws BundleException

This method asynchronously shuts down the framework, it must be called at the end of a session in order to shutdown all active bundles.

Specified by:
  `stop` in interface `Bundle`
Specified by:
  `stop` in interface `Framework`
Throws:
  `BundleException` - BundleException types thrown by this method include: `BundleException.STATECHANGE_ERROR` and `BundleException.ACTIVATOR_ERROR`.
See Also:
  `Bundle.start(int)`

#### stop

    public void stop(int options)
              throws BundleException

Description copied from interface: `Bundle`
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 `Bundle.STOP_TRANSIENT` option is not set then set this bundle's persistent autostart setting 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 `BundleEvent.STOPPING` is fired.
7. If this bundle's state was `ACTIVE` prior to setting the state to `STOPPING`, the `BundleActivator.stop(BundleContext)` 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 `BundleEvent.STOPPED` is fired.

Preconditions

- `getState()` in { `ACTIVE` }.

Postconditions, no exceptions thrown

- Bundle autostart setting is modified unless the `Bundle.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 `Bundle.STOP_TRANSIENT` option was set.

Specified by:
  `stop` in interface `Bundle`
Specified by:
  `stop` in interface `Framework`
Parameters:
  `options` - The options for stopping this bundle. See `Bundle.STOP_TRANSIENT`. The Framework must ignore unrecognized options.
Throws:
  `BundleException` - BundleException types thrown by this method include: `BundleException.STATECHANGE_ERROR` and `BundleException.ACTIVATOR_ERROR`.
See Also:
  `Framework.stop()`

#### waitForStop

    public FrameworkEvent waitForStop(long timeout)
                               throws InterruptedException

This method will cause the calling thread to block until the framework shuts down.

Specified by:
  `waitForStop` in interface `Framework`
Parameters:
  `timeout` - A timeout value.
Returns:
  A Framework Event indicating the reason this method returned. The following `FrameworkEvent` types may be returned by this method.
  - `STOPPED` - This Framework has been stopped.
  - `STOPPED_UPDATE` - This Framework has been updated which has shutdown and will now restart.
  - `STOPPED_SYSTEM_REFRESHED` - The Framework has been stopped because of a refresh operation on the system bundle. A new class loader must be used to restart the Framework.
  - `ERROR` - The Framework encountered an error while shutting down or an error has occurred which forced the framework to shutdown.
  - `WAIT_TIMEDOUT` - This method has timed out and returned before this Framework has stopped.
Throws:
  `InterruptedException` - If the thread was interrupted.

#### uninstall

    public void uninstall()
                   throws BundleException

Description copied from interface: `Bundle`
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 `FrameworkWiring.refreshBundles` 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 `FrameworkEvent.ERROR` is fired containing the exception.
3. This bundle's state is set to `UNINSTALLED`.
4. A bundle event of type `BundleEvent.UNINSTALLED` is fired.
5. 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.

Specified by:
  `uninstall` in interface `Bundle`
Specified by:
  `uninstall` in interface `Framework`
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. BundleException types thrown by this method include: `BundleException.STATECHANGE_ERROR`
See Also:
  `Bundle.stop()`

#### update

    public void update()
                throws BundleException

Description copied from interface: `Bundle`
Updates this bundle.

This method performs the same function as calling `Bundle.update(InputStream)` with a `null` InputStream.

Specified by:
  `update` in interface `Bundle`
Specified by:
  `update` in interface `Framework`
Throws:
  `BundleException` - If this bundle could not be updated. BundleException types thrown by this method include: `BundleException.READ_ERROR`, `BundleException.DUPLICATE_BUNDLE_ERROR`, `BundleException.MANIFEST_ERROR`, `BundleException.NATIVECODE_ERROR`, `BundleException.RESOLVE_ERROR`, `BundleException.STATECHANGE_ERROR`, and `BundleException.ACTIVATOR_ERROR`.
See Also:
  `Bundle.update(InputStream)`

#### update

    public void update(InputStream is)
                throws BundleException

Description copied from interface: `Bundle`
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 `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 remain exported until the `FrameworkWiring.refreshBundles` 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 `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 `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.

Specified by:
  `update` in interface `Bundle`
Specified by:
  `update` in interface `Framework`
Parameters:
  `is` - The `InputStream` from which to read the new bundle or `null` to indicate the Framework must create the input stream from this bundle's `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 this bundle could not be updated. BundleException types thrown by this method include: `BundleException.READ_ERROR`, `BundleException.DUPLICATE_BUNDLE_ERROR`, `BundleException.MANIFEST_ERROR`, `BundleException.NATIVECODE_ERROR`, `BundleException.RESOLVE_ERROR`, `BundleException.STATECHANGE_ERROR`, and `BundleException.ACTIVATOR_ERROR`.
See Also:
  `Bundle.stop()`, `Bundle.start()`

#### toString

    public String toString()

#### hasConnectFramework

    public boolean hasConnectFramework()

#### getBundleContext

    public BundleContext getBundleContext()

Description copied from interface: `Bundle`
Returns this bundle's `BundleContext`. The returned `BundleContext` can be used by the caller to act on behalf of this bundle.

If this bundle is not in the `Bundle.STARTING`, `Bundle.ACTIVE`, or `Bundle.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`.

Specified by:
  `getBundleContext` in interface `Bundle`
Returns:
  A `BundleContext` for this bundle or `null` if this bundle has no valid `BundleContext`.

#### getEntry

    public URL getEntry(String name)

Description copied from interface: `Bundle`
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.

Specified by:
  `getEntry` in interface `Bundle`
Parameters:
  `name` - The path name of the entry.
Returns:
  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.

#### getEntryPaths

    public Enumeration getEntryPaths(String path)

Description copied from interface: `Bundle`
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.

Specified by:
  `getEntryPaths` in interface `Bundle`
Parameters:
  `path` - The path name for which to return entry paths.
Returns:
  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.

#### findEntries

    public Enumeration findEntries(String path,
                                   String filePattern,
                                   boolean recurse)

Description copied from interface: `Bundle`
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();

URLs for directory entries must have their path end with "/".

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.

Specified by:
  `findEntries` in interface `Bundle`
Parameters:
  `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.
  `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.
  `recurse` - If `true`, recurse into subdirectories. Otherwise only return entries from the specified path.
Returns:
  An enumeration of URL objects for each matching entry, or `null` if no matching entry could 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 attachment order. If this bundle is a fragment, then only matching entries in this fragment are returned.

#### getHeaders

    public Dictionary getHeaders()

Description copied from interface: `Bundle`
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.

Specified by:
  `getHeaders` in interface `Bundle`
Returns:
  An unmodifiable `Dictionary` object containing this bundle's Manifest headers and values.
See Also:
  `Constants.BUNDLE_LOCALIZATION`

#### getHeaders

    public Dictionary getHeaders(String locale)

Description copied from interface: `Bundle`
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.

Specified by:
  `getHeaders` in interface `Bundle`
Parameters:
  `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 "%".
Returns:
  An unmodifiable `Dictionary` object containing this bundle's Manifest headers and values.
See Also:
  `Bundle.getHeaders()`, `Constants.BUNDLE_LOCALIZATION`

#### getLocation

    public String getLocation()

Description copied from interface: `Bundle`
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.

Specified by:
  `getLocation` in interface `Bundle`
Returns:
  The string representation of this bundle's location identifier.

#### getResource

    public URL getResource(String name)

Returns a URL to a named resource in the bundle.

Specified by:
  `getResource` in interface `Bundle`
Parameters:
  `name` - The name of the resource. See `ClassLoader.getResource` for a description of the format of a resource name.
Returns:
  a URL to named resource, or null if not found.
See Also:
  `Bundle.getEntry(String)`, `Bundle.findEntries(String, String, boolean)`

#### getResources

    public Enumeration getResources(String name)
                             throws IOException

Description copied from interface: `Bundle`
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.

Specified by:
  `getResources` in interface `Bundle`
Parameters:
  `name` - The name of the resource. See `ClassLoader.getResources` for a description of the format of a resource name.
Returns:
  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:
  `IOException` - If there is an I/O error.

#### getRegisteredServices

    public ServiceReference[] getRegisteredServices()

Returns an array of service references corresponding to the bundle's registered services.

Specified by:
  `getRegisteredServices` in interface `Bundle`
Returns:
  an array of service references or null.
See Also:
  `ServiceRegistration`, `ServiceReference`, `ServicePermission`

#### getServicesInUse

    public ServiceReference[] getServicesInUse()

Description copied from interface: `Bundle`
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 it has any unreleased service objects.

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.

Specified by:
  `getServicesInUse` in interface `Bundle`
Returns:
  An array of `ServiceReference` objects or `null`.
See Also:
  `ServiceReference`, `ServicePermission`

#### getState

    public int getState()

Description copied from interface: `Bundle`
Returns this bundle's current state.

A bundle can be in only one state at any time.

Specified by:
  `getState` in interface `Bundle`
Returns:
  An element of `UNINSTALLED`,`INSTALLED`, `RESOLVED`, `STARTING`, `STOPPING`, `ACTIVE`.

#### getSymbolicName

    public String getSymbolicName()

Description copied from interface: `Bundle`
Returns the symbolic name of this bundle as specified by its `Bundle-SymbolicName` manifest header. 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.

Specified by:
  `getSymbolicName` in interface `Bundle`
Returns:
  The symbolic name of this bundle or `null` if this bundle does not have a symbolic name.

#### getVersion

    public Version getVersion()

Description copied from interface: `Bundle`
Returns the version of this bundle as specified by its `Bundle-Version` manifest header. If this bundle does not have a specified version then `Version.emptyVersion` is returned.

This method must continue to return this bundle's version while this bundle is in the `UNINSTALLED` state.

Specified by:
  `getVersion` in interface `Bundle`
Returns:
  The version of this bundle.

#### getSignerCertificates

    public Map getSignerCertificates(int signersType)

Description copied from interface: `Bundle`
Return the certificates for the signers of this bundle and the certificate chains for those signers.

Specified by:
  `getSignerCertificates` in interface `Bundle`
Parameters:
  `signersType` - If `Bundle.SIGNERS_ALL` is specified, then information on all signers of this bundle is returned. If `Bundle.SIGNERS_TRUSTED` is specified, then only information on the signers of this bundle trusted by the framework is returned.
Returns:
  The `X509Certificate`s for the signers of this bundle and the `X509Certificate` chains for those signers. The keys of the `Map` are the `X509Certificate`s 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.

#### loadClass

    public Class loadClass(String name)
                    throws ClassNotFoundException

Description copied from interface: `Bundle`
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 `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.

Specified by:
  `loadClass` in interface `Bundle`
Parameters:
  `name` - The name of the class to load.
Returns:
  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.

#### getDataFile

    public File getDataFile(String filename)

Description copied from interface: `Bundle`
Creates a `File` object for a file in the persistent storage area provided for this bundle by the Framework. This method will return `null` if the platform does not have file system support or this bundle is a fragment bundle.

A `File` object for the base directory of the persistent storage area provided for this bundle by the Framework can be obtained by calling this method with an empty string as `filename`.

If the Java Runtime Environment supports permissions, the Framework will ensure that this bundle has the `java.io.FilePermission` with actions `read`,`write`,`delete` for all files (recursively) in the persistent storage area provided for this bundle.

Specified by:
  `getDataFile` in interface `Bundle`
Parameters:
  `filename` - A relative name to the file to be accessed.
Returns:
  A `File` object that represents the requested file or `null` if the platform does not have file system support or this bundle is a fragment bundle.

#### compareTo

    public int compareTo(Bundle t)

Specified by:
  `compareTo` in interface `Comparable<Bundle>`

#### getBundle

    public Bundle getBundle()

Description copied from interface: `BundleReference`
Returns the `Bundle` object associated with this `BundleReference`.

Specified by:
  `getBundle` in interface `BundleReference`
Returns:
  The `Bundle` object associated with this `BundleReference`.

#### getRevisions

    public List<BundleRevision> getRevisions()

Description copied from interface: `BundleRevisions`
Return the bundle revisions for the `referenced` bundle.

The result is a list containing the current bundle revision, if there is one, and all in use bundle revisions. The list may also contain intermediate bundle revisions which are not in use.

The list is ordered in reverse chronological order such that the first item is the most recent bundle revision and last item is the oldest bundle revision.

Generally the list will have at least one bundle revision for the bundle: the current bundle revision. However, for an uninstalled bundle with no in use bundle revisions, the list may be empty.

Specified by:
  `getRevisions` in interface `BundleRevisions`
Returns:
  A list containing a snapshot of the `BundleRevision`s for the referenced bundle.