org.osgi.framework
Interface BundleContext

public interface BundleContext

A bundle's execution context within the Framework. The context is used to grant access to other methods so that this bundle can interact with the Framework.

BundleContext methods allow a bundle to:

• Subscribe to events published by the Framework.
• Register services in the Framework service registry.
• Retrieve ServiceReferences from the Framework service registry.
• Get and release service objects for a referenced service.
• Install new bundles in the Framework.
• Get the list of bundles installed in the Framework.
• Get the Bundleobject for a bundle.
• Create File objects for files in a persistent storage area provided for the bundle by the Framework.

A BundleContext object will be created and provided to this bundle when it is started using the BundleActivator.start(org.osgi.framework.BundleContext)method. The same BundleContext object will be passed to this bundle when it is stopped using the BundleActivator.stop(org.osgi.framework.BundleContext)method. BundleContext is generally for the private use of this bundle and is not meant to be shared with other bundles in the OSGi environment. BundleContext is used when resolving ServiceListeners and EventListeners.

The BundleContext object is only valid during an execution instance of this bundle; that is, during the period from when this bundle is called by BundleActivator.start until after this bundle is called and returns from BundleActivator.stop (or if BundleActivator.start terminates with an exception). If the BundleContext object is used subsequently, an IllegalStateException may be thrown. When this bundle is restarted, a new BundleContext object will be created.

The Framework is the only entity that can create BundleContext objects and they are only valid within the Framework that created them.

Note: A single virtual machine may host multiple Framework instances at any given time, but objects created by one Framework instance cannot be used by bundles running in the execution context of another Framework instance.

Method Summary

void	addBundleListener(BundleListener listener) Adds the specified BundleListener object to this context bundle's list of listeners if not already present.
void	addFrameworkListener(FrameworkListener listener) Adds the specified FrameworkListener object to this context bundle's list of listeners if not already present.
void	addServiceListener(ServiceListener listener) Adds the specified ServiceListener object to this context bundle's list of listeners.
void	addServiceListener(ServiceListener listener, java.lang.String filter) Adds the specified ServiceListener object with the specified filter to this context bundle's list of listeners.
Filter	createFilter(java.lang.String filter) Creates a Filter object.
Bundle	getBundle() Returns the Bundle object for this context bundle.
Bundle	getBundle(long id) Returns the bundle with the specified identifier.
Bundle[]	getBundles() Returns a list of all installed bundles.
java.io.File	getDataFile(java.lang.String filename) Creates a File object for a file in the persistent storage area provided for the bundle by the Framework.
java.lang.String	getProperty(java.lang.String key) Returns the value of the specified environment property.
java.lang.Object	getService(ServiceReference reference) Returns the specified service object for a service.
ServiceReference	getServiceReference(java.lang.String clazz) Returns a ServiceReference object for a service that implements, and was registered under, the specified class.
ServiceReference[]	getServiceReferences(java.lang.String clazz, java.lang.String filter) Returns a list of ServiceReference objects.
Bundle	installBundle(java.lang.String location) Installs the bundle from the specified location string.
Bundle	installBundle(java.lang.String location, java.io.InputStream in) Installs the bundle from the specified InputStream object.
ServiceRegistration	registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary properties) Registers the specified service object with the specified properties under the specified class names into the Framework.
ServiceRegistration	registerService(java.lang.String clazz, java.lang.Object service, java.util.Dictionary properties) Registers the specified service object with the specified properties under the specified class name into the Framework.
void	removeBundleListener(BundleListener listener) Removes the specified BundleListener object from this context bundle's list of listeners.
void	removeFrameworkListener(FrameworkListener listener) Removes the specified FrameworkListener object from this context bundle's list of listeners.
void	removeServiceListener(ServiceListener listener) Removes the specified ServiceListener object from this context bundle's list of listeners.
boolean	ungetService(ServiceReference reference) Releases the service object referenced by the specified ServiceReference object.

Method Detail

getProperty

public java.lang.String getProperty(java.lang.String key)

Returns the value of the specified environment property.

The following standard property keys are valid:

Constants.FRAMEWORK_VERSION

The OSGi Framework version.

Constants.FRAMEWORK_VENDOR

The Framework implementation vendor.

Constants.FRAMEWORK_LANGUAGE

The language being used. See ISO 639 for possible values.

Constants.FRAMEWORK_OS_NAME

The host computer operating system.

Constants.FRAMEWORK_OS_VERSION

The host computer operating system version number.

Constants.FRAMEWORK_PROCESSOR

The host computer processor name.

Note: The last four standard properties are used by the Constants.BUNDLE_NATIVECODEManifest header's matching algorithm for selecting native language code.

Parameters:

key - The name of the requested property.

Returns:

The value of the requested property, or null if the property is undefined.

getBundle

public Bundle getBundle()

Returns the Bundle object for this context bundle.

The context bundle is defined as the bundle that was assigned this BundleContext in its BundleActivator.

Returns:

The context bundle's Bundle object.

Throws:

java.lang.IllegalStateException - If this context bundle has stopped.

installBundle

public Bundle installBundle(java.lang.String location)
                     throws BundleException

Installs the bundle from the specified location string. A bundle is obtained from location as interpreted by the Framework in an implementation dependent manner.

Every installed bundle is uniquely identified by its location string, typically in the form of a URL.

The following steps are required to install a bundle:

1. If a bundle containing the same location string is already installed, the Bundle object for that bundle is returned.
2. The bundle's content is read from the location string. If this fails, a BundleExceptionis thrown.
3. The bundle's Bundle-ClassPath and Bundle-NativeCode dependencies are resolved. If this fails, a BundleException is thrown.
4. The bundle's associated resources are allocated. The associated resources minimally consist of a unique identifier, and a persistent storage area if the platform has file system support. If this step fails, a BundleException is thrown.
5. The bundle's state is set to INSTALLED.
6. If the bundle has not declared an Import-Package Manifest header (that is, the bundle does not depend on any packages from other OSGi bundles), the bundle's state may be set to RESOLVED.
7. A bundle event of type BundleEvent.INSTALLEDis broadcast.
8. The Bundle object for the newly installed bundle is returned.

Postconditions, no exceptions thrown

• getState() in {INSTALLED}, RESOLVED}.
• Bundle has a unique ID.

Postconditions, when an exception is thrown

• Bundle is not installed and no trace of the bundle exists.

Parameters:

location - The location identifier of the bundle to install.

Returns:

The Bundle object of the installed bundle.

Throws:

BundleException - If the installation failed.

java.lang.SecurityException - If the caller does not have the appropriate AdminPermission, and the Java Runtime Environment supports permissions.

installBundle

public Bundle installBundle(java.lang.String location,
                            java.io.InputStream in)
                     throws BundleException

Installs the bundle from the specified InputStream object.

This method performs all of the steps listed in BundleContext.installBundle(String location), except that the bundle's content will be read from the InputStream object. The location identifier string specified will be used as the identity of the bundle.

This method will always close the InputStream object, even if an exception is thrown.

Parameters:

location - The location identifier of the bundle to install.

in - The InputStream object from which this bundle will be read.

Returns:

The Bundle object of the installed bundle.

Throws:

BundleException - If the provided stream cannot be read.

See Also:

installBundle(java.lang.String)

getBundle

public Bundle getBundle(long id)

Returns the bundle with the specified identifier.

Parameters:

id - The identifier of the bundle to retrieve.

Returns:

A Bundle object, or null if the identifier does not match any installed bundle.

getBundles

public Bundle[] getBundles()

Returns a list of all installed bundles.

This method returns a list of all bundles installed in the OSGi environment at the time of the call to this method. However, as the Framework is a very dynamic environment, bundles can be installed or uninstalled at anytime.

Returns:

An array of Bundle objects; one object per installed bundle.

addServiceListener

public void addServiceListener(ServiceListener listener,
                               java.lang.String filter)
                        throws InvalidSyntaxException

Adds the specified ServiceListener object with the specified filter to this context bundle's list of listeners.

See getBundle()for a definition of context bundle, and Filterfor a description of the filter syntax. ServiceListener objects are notified when a service has a lifecycle state change.

If this context bundle's list of listeners already contains a listener l such that (l==listener), this method replaces that listener's filter (which may be null) with the specified one (which may be null).

The listener is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the Constants.OBJECTCLASSproperty. If filter is null, all services are considered to match the filter.

If the Java Runtime Environment supports permissions, the ServiceListener object will be notified of a service event only if the bundle that is registering it has the ServicePermission to get the service using at least one of the named classes the service was registered under.

Parameters:

listener - The ServiceListener object to be added.

filter - The filter criteria.

Throws:

InvalidSyntaxException - If filter contains an invalid filter string which cannot be parsed.

java.lang.IllegalStateException - If this context bundle has stopped.

See Also:

ServiceEvent, ServiceListener, ServicePermission

addServiceListener

public void addServiceListener(ServiceListener listener)

Adds the specified ServiceListener object to this context bundle's list of listeners.

This method is the same as calling BundleContext.addServiceListener(ServiceListener listener, String filter) with filter set to null.

Parameters:

listener - The ServiceListener object to be added.

Throws:

java.lang.IllegalStateException - If this context bundle has stopped.

See Also:

addServiceListener(ServiceListener, String)

removeServiceListener

public void removeServiceListener(ServiceListener listener)

Removes the specified ServiceListener object from this context bundle's list of listeners. See getBundle()for a definition of context bundle.

If listener is not contained in this context bundle's list of listeners, this method does nothing.

Parameters:

listener - The ServiceListener to be removed.

Throws:

java.lang.IllegalStateException - If this context bundle has stopped.

addBundleListener

public void addBundleListener(BundleListener listener)

Adds the specified BundleListener object to this context bundle's list of listeners if not already present. See getBundle()for a definition of context bundle. BundleListener objects are notified when a bundle has a lifecycle state change.

If this context bundle's list of listeners already contains a listener l such that (l==listener), this method does nothing.

Parameters:

listener - The BundleListener to be added.

Throws:

java.lang.IllegalStateException - If this context bundle has stopped.

See Also:

BundleEvent, BundleListener

removeBundleListener

public void removeBundleListener(BundleListener listener)

Removes the specified BundleListener object from this context bundle's list of listeners. See getBundle()for a definition of context bundle.

If listener is not contained in this context bundle's list of listeners, this method does nothing.

Parameters:

listener - The BundleListener object to be removed.

Throws:

java.lang.IllegalStateException - If this context bundle has stopped.

addFrameworkListener

public void addFrameworkListener(FrameworkListener listener)

Adds the specified FrameworkListener object to this context bundle's list of listeners if not already present. See getBundle()for a definition of context bundle. FrameworkListeners are notified of general Framework events.

If this context bundle's list of listeners already contains a listener l such that (l==listener), this method does nothing.

Parameters:

listener - The FrameworkListener object to be added.

Throws:

java.lang.IllegalStateException - If this context bundle has stopped.

See Also:

FrameworkEvent, FrameworkListener

removeFrameworkListener

public void removeFrameworkListener(FrameworkListener listener)

Removes the specified FrameworkListener object from this context bundle's list of listeners. See getBundle()for a definition of context bundle.

If listener is not contained in this context bundle's list of listeners, this method does nothing.

Parameters:

listener - The FrameworkListener object to be removed.

Throws:

java.lang.IllegalStateException - If this context bundle has stopped.

registerService

public ServiceRegistration registerService(java.lang.String[] clazzes,
                                           java.lang.Object service,
                                           java.util.Dictionary properties)

Registers the specified service object with the specified properties under the specified class names into the Framework. A ServiceRegistration object is returned. The ServiceRegistration object is for the private use of the bundle registering the service and should not be shared with other bundles. The registering bundle is defined to be the context bundle. See getBundle()for a definition of context bundle. Other bundles can locate the service by using either the getServiceReferences(java.lang.String, java.lang.String)or getServiceReference(java.lang.String)method.

A bundle can register a service object that implements the ServiceFactoryinterface to have more flexibility in providing service objects to other bundles.

The following steps are required to register a service:

1. If service is not a ServiceFactory, an IllegalArgumentException is thrown if service is not an instanceof all the classes named.
2. The Framework adds these service properties to the specified Dictionary (which may be null): a property named Constants.SERVICE_IDidentifying the registration number of the service, and a property named Constants.OBJECTCLASScontaining all the specified classes. If any of these properties have already been specified by the registering bundle, their values will be overwritten by the Framework.
3. The service is added to the Framework service registry and may now be used by other bundles.
4. A service event of type ServiceEvent.REGISTEREDis synchronously sent.
5. A ServiceRegistration object for this registration is returned.

Parameters:

clazzes - The class names under which the service can be located. The class names in this array will be stored in the service's properties under the key Constants.OBJECTCLASS.

service - The service object or a ServiceFactory object.

properties - The properties for this service. The keys in the properties object must all be Strings. See Constantsfor a list of standard service property keys. Changes should not be made to this object after calling this method. To update the service's properties the ServiceRegistration.setProperties(java.util.Dictionary)method must be called. properties may be null if the service has no properties.

Returns:

A ServiceRegistration object for use by the bundle registering the service to update the service's properties or to unregister the service.

Throws:

java.lang.IllegalArgumentException - If one of the following is true:

• service is null.
• service is not a ServiceFactory object and is not an instanceof all the named classes in clazzes.
• properties contains case variants of the same key name.

java.lang.SecurityException - If the caller does not have the ServicePermission to register the service for all the named classes and the Java Runtime Environment supports permissions.

java.lang.IllegalStateException - If this context bundle has stopped.

See Also:

ServiceRegistration, ServiceFactory

registerService

public ServiceRegistration registerService(java.lang.String clazz,
                                           java.lang.Object service,
                                           java.util.Dictionary properties)

Registers the specified service object with the specified properties under the specified class name into the Framework.

This method is otherwise identical to registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)and is provided as a convenience when service will only be registered under a single class name. Note that even in this case the value of the service's Constants.OBJECTCLASSproperty will be an array of strings, rather than just a single string.

See Also:

registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)

getServiceReferences

public ServiceReference[] getServiceReferences(java.lang.String clazz,
                                               java.lang.String filter)
                                        throws InvalidSyntaxException

Returns a list of ServiceReference objects. This method returns a list of ServiceReference objects for services which implement and were registered under the specified class and match the specified filter criteria.

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.

filter is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See Filterfor a description of the filter string syntax.

If filter is null, all registered services are considered to match the filter.

If filter cannot be parsed, an InvalidSyntaxExceptionwill be thrown with a human readable message where the filter became unparsable.

The following steps are required to select a service:

1. If the Java Runtime Environment supports permissions, the caller is checked for the ServicePermission to get the service with the specified class. If the caller does not have the correct permission, null is returned.
2. If the filter string is not null, the filter string is parsed and the set of registered services which satisfy the filter is produced. If the filter string is null, then all registered services are considered to satisfy the filter.
3. If clazz is not null, the set is further reduced to those services which are an instanceof and were registered under the specified class. The complete list of classes of which a service is an instance and which were specified when the service was registered is available from the service's Constants.OBJECTCLASSproperty.
4. An array of ServiceReference to the selected services is returned.

Parameters:

clazz - The class name with which the service was registered, or null for all services.

filter - The filter criteria.

Returns:

An array of ServiceReference objects, or null if no services are registered which satisfy the search.

Throws:

InvalidSyntaxException - If filter contains an invalid filter string which cannot be parsed.

getServiceReference

public ServiceReference getServiceReference(java.lang.String clazz)

Returns a ServiceReference object for a service that implements, and was registered under, the specified class.

This ServiceReference object 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.

This method is the same as calling getServiceReferences(java.lang.String, java.lang.String)with a null filter string. It is provided as a convenience for when the caller is interested in any service that implements the specified class.

If multiple such services exist, the service with the highest ranking (as specified in its Constants.SERVICE_RANKINGproperty) is returned.

If there is a tie in ranking, the service with the lowest service ID (as specified in its Constants.SERVICE_IDproperty); that is, the service that was registered first is returned.

Parameters:

clazz - The class name with which the service was registered.

Returns:

A ServiceReference object, or null if no services are registered which implement the named class.

See Also:

getServiceReferences(java.lang.String, java.lang.String)

getService

public java.lang.Object getService(ServiceReference reference)

Returns the specified service object for a service.

A bundle's use of a service is tracked by the bundle's use count of that service. Each time a service's service object is returned by getService(org.osgi.framework.ServiceReference)the context bundle's use count for that service is incremented by one. Each time the service is released by ungetService(org.osgi.framework.ServiceReference)the context bundle's use count for that service is decremented by one.

When a bundle's use count for a service drops to zero, the bundle should no longer use that service. See getBundle()for a definition of context bundle.

This method will always return null when the service associated with this reference has been unregistered.

The following steps are required to get the service object:

1. If the service has been unregistered, null is returned.
2. The context bundle's use count for this service is incremented by one.
3. If the context bundle's use count for the service is currently one and the service was registered with an object implementing the ServiceFactory interface, the ServiceFactory.getService(org.osgi.framework.Bundle, org.osgi.framework.ServiceRegistration)method is called to create a service object for the context bundle. This service object is cached by the Framework. While the context bundle's use count for the service is greater than zero, subsequent calls to get the services's service object for the context bundle will return the cached service object.
   If the service object returned by the ServiceFactory object is not an instanceof all the classes named when the service was registered or the ServiceFactory object throws an exception, null is returned and a Framework event of type FrameworkEvent.ERRORis broadcast.
4. The service object for the service is returned.

Parameters:

reference - A reference to target service object's service.

Returns:

A service object for the service associated with reference, or null if the service is not registered.

Throws:

java.lang.SecurityException - If the caller does not have the ServicePermission to get the service using at least one of the named classes the service was registered under, and the Java Runtime Environment supports permissions.

java.lang.IllegalStateException - If the context bundle has stopped.

See Also:

ungetService(org.osgi.framework.ServiceReference), ServiceFactory

ungetService

public boolean ungetService(ServiceReference reference)

Releases the service object referenced by the specified ServiceReference object. If the context bundle's use count for the service is zero, this method returns false. Otherwise, the context bundle's use count for the service is decremented by one. See getBundle()for a definition of context bundle.

The service's service object should no longer be used and all references to it should be destroyed when a bundle's use count for the service drops to zero.

The following steps are required to unget the service object:

1. If the context bundle's use count for the service is zero or the service has been unregistered, false is returned.
2. The context bundle's use count for this service is decremented by one.
3. If the context bundle's use count for the service is currently zero and the service was registered with a ServiceFactory object, the ServiceFactory.ungetService(org.osgi.framework.Bundle, org.osgi.framework.ServiceRegistration, java.lang.Object)method is called to release the service object for the context bundle.
4. true is returned.

Parameters:

reference - A reference to the service to be released.

Returns:

false if the context bundle's use count for the service is zero or if the service has been unregistered; true otherwise.

Throws:

java.lang.IllegalStateException - If the context bundle has stopped.

See Also:

getService(org.osgi.framework.ServiceReference), ServiceFactory

getDataFile

public java.io.File getDataFile(java.lang.String filename)

Creates a File object for a file in the persistent storage area provided for the bundle by the Framework. This method will return null if the platform does not have file system support.

A File object for the base directory of the persistent storage area provided for the context bundle by the Framework can be obtained by calling this method with an empty string (" ") as filename. See getBundle()for a definition of context bundle.

If the Java Runtime Environment supports permissions, the Framework will ensure that the bundle has the java.io.FilePermission with actions read, write, execute, delete for all files (recursively) in the persistent storage area provided for the context 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.

Throws:

java.lang.IllegalStateException - If the context bundle has stopped.

createFilter

public Filter createFilter(java.lang.String filter)
                    throws InvalidSyntaxException

Creates a Filter object. This Filter object may be used to match a ServiceReference object or a Dictionary object. See Filterfor a description of the filter string syntax.

If the filter cannot be parsed, an InvalidSyntaxExceptionwill be thrown with a human readable message where the filter became unparsable.

Parameters:

filter - The filter string.

Returns:

A Filter object encapsulating the filter string.

Throws:

InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.

Since:

1.1