Top Description Methods
org.osgi.framework

public Interface BundleContext

extends BundleReference
Annotations
@ProviderType
Imports
java.io.File, .InputStream, java.util.Collection, .Dictionary, org.osgi.annotation.versioning.ProviderType
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:

A BundleContext object will be created for a bundle when the bundle is started. The Bundle object associated with a BundleContext object is called the context bundle.

The BundleContext object will be passed to the BundleActivator#start(BundleContext) method during activation of the context bundle. The same BundleContext object will be passed to the BundleActivator#stop(BundleContext) method when the context bundle is stopped. A BundleContext object is generally for the private use of its associated bundle and is not meant to be shared with other bundles in the OSGi environment.

The BundleContext object is only valid during the execution of its context bundle; that is, during the period from when the context bundle is in the STARTING, STOPPING, and ACTIVE bundle states. However, the BundleContext object becomes invalid after BundleActivator#stop(BundleContext) returns (if the bundle has a Bundle Activator). The BundleContext object becomes invalid before disposing of any remaining registered services and releasing any remaining services in use. Since those activities can result in other bundles being called (for example, ServiceListeners for ServiceEvent#UNREGISTERING events and ServiceFactorys for unget operations), those other bundles can observe the stopping bundle in the STOPPING state but with an invalid BundleContext object. If the BundleContext object is used after it has become invalid, an IllegalStateException must be thrown. The BundleContext object must never be reused after its context bundle is stopped.

Two BundleContext objects are equal if they both refer to the same execution context of a bundle. The Framework is the only entity that can create BundleContext objects and they are only valid within the Framework that created them.

A Bundle can be adapted to its BundleContext. In order for this to succeed, the caller must have the appropriate AdminPermission[bundle,CONTEXT] if the Java Runtime Environment supports permissions.

Author
$Id: 6c43d322b8ea2137c094ce10e1f33e9c54519dd6 $

Method Summary

Modifier and TypeMethod and Description
public void
addBundleListener(BundleListener
The BundleListener to be added.
listener)

Adds the specified BundleListener object to the context bundle's list of listeners if not already present.

public void
addFrameworkListener(FrameworkListener
The FrameworkListener object to be added.
listener)

Adds the specified FrameworkListener object to the context bundle's list of listeners if not already present.

public void
addServiceListener(ServiceListener
The ServiceListener object to be added.
listener, String
The filter criteria.
filter)

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

public void
addServiceListener(ServiceListener
The ServiceListener object to be added.
listener)

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

public Filter

Returns:

A Filter object encapsulating the filter string.
createFilter(String
The filter string.
filter)

Creates a Filter object.

public ServiceReference<?>[]

Returns:

An array of ServiceReference objects or null if no services are registered which satisfy the search.
getAllServiceReferences(String
The class name with which the service was registered or null for all services.
clazz, String
The filter expression or null for all services.
filter)

Returns an array of ServiceReference objects.

public Bundle

Returns:

The Bundle object associated with this BundleContext.
getBundle()

Redeclares org.osgi.framework.BundleReference.getBundle.

Returns the Bundle object associated with this BundleContext.

public Bundle

Returns:

A Bundle object or null if the identifier does not match any installed bundle.
getBundle(long
The identifier of the bundle to retrieve.
id)

Returns the bundle with the specified identifier.

public Bundle

Returns:

A Bundle object or null if the location does not match any installed bundle.
getBundle(String
The location of the bundle to retrieve.
location)

Returns the bundle with the specified location.

public Bundle[]

Returns:

An array of Bundle objects, one object per installed bundle.
getBundles()

Returns a list of all installed bundles.

public File

Returns:

A File object that represents the requested file or null if the platform does not have file system support.
getDataFile(String
A relative name to the file to be accessed.
filename)

Creates a File object for a file in the persistent storage area provided for the bundle by the Framework.

public String

Returns:

The value of the requested property, or null if the property is undefined.
getProperty(String
The name of the requested property.
key)

Returns the value of the specified property.

public <
Type of Service.
S> S

Returns:

A service object for the service associated with reference or null if the service is not registered, the service object returned by a ServiceFactory does not implement the classes under which it was registered or the ServiceFactory threw an exception.
getService(ServiceReference<S>
A reference to the service.
reference)

Returns the service object for the service referenced by the specified ServiceReference object.

public <
Type of Service.
S> ServiceObjects<S>

Returns:

A ServiceObjects object for the service associated with the specified reference or null if the service is not registered.
getServiceObjects(ServiceReference<S>
A reference to the service.
reference)

Returns the ServiceObjects object for the service referenced by the specified ServiceReference object.

public ServiceReference<?>

Returns:

A ServiceReference object, or null if no services are registered which implement the named class.
getServiceReference(String
The class name with which the service was registered.
clazz)

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

public <
Type of Service.
S> ServiceReference<S>

Returns:

A ServiceReference object, or null if no services are registered which implement the specified class.
getServiceReference(Class<S>
The class under whose name the service was registered. Must not be null.
clazz)

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

public ServiceReference<?>[]

Returns:

An array of ServiceReference objects or null if no services are registered which satisfy the search.
getServiceReferences(String
The class name with which the service was registered or null for all services.
clazz, String
The filter expression or null for all services.
filter)

Returns an array of ServiceReference objects.

public <
Type of Service
S> Collection<ServiceReference<S>>

Returns:

A collection of ServiceReference objects. May be empty if no services are registered which satisfy the search.
getServiceReferences(Class<S>
The class under whose name the service was registered. Must not be null.
clazz, String
The filter expression or null for all services.
filter)

Returns a collection of ServiceReference objects.

public Bundle

Returns:

The Bundle object of the installed bundle.
installBundle(String
The location identifier of the bundle to install.
location, InputStream
The InputStream object from which this bundle will be read or null to indicate the Framework must create the input stream from the specified location identifier. The input stream must always be closed when this method completes, even if an exception is thrown.
input)

Installs a bundle from the specified InputStream object.

public Bundle

Returns:

The Bundle object of the installed bundle.
installBundle(String
The location identifier of the bundle to install.
location)

Installs a bundle from the specified location identifier.

public ServiceRegistration<?>

Returns:

A ServiceRegistration object for use by the bundle registering the service to update the service's properties or to unregister the service.
registerService(String[]
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.
clazzes, Object
The service object or an object implementing ServiceFactory.
service, Dictionary<String, ?>
The properties for this service. The keys in the properties object must all be String objects. See Constants for 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(Dictionary) method must be called. The set of properties may be null if the service has no properties.
properties)

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

public ServiceRegistration<?>

Returns:

A ServiceRegistration object for use by the bundle registering the service to update the service's properties or to unregister the service.
registerService(String
The class name under which the service can be located.
clazz, Object
The service object or an object implementing ServiceFactory.
service, Dictionary<String, ?>
The properties for this service.
properties)

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

public <
Type of Service.
S> ServiceRegistration<S>

Returns:

A ServiceRegistration object for use by the bundle registering the service to update the service's properties or to unregister the service.
registerService(Class<S>
The class under whose name the service can be located.
clazz, S
The service object or an object implementing ServiceFactory.
service, Dictionary<String, ?>
The properties for this service.
properties)

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

public <
Type of Service.
S> ServiceRegistration<S>

Returns:

A ServiceRegistration object for use by the bundle registering the service to update the service's properties or to unregister the service.
registerService(Class<S>
The class under whose name the service can be located.
clazz, ServiceFactory<S>
The ServiceFactory object.
factory, Dictionary<String, ?>
The properties for this service.
properties)

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

public void
removeBundleListener(BundleListener
The BundleListener object to be removed.
listener)

Removes the specified BundleListener object from the context bundle's list of listeners.

public void
removeFrameworkListener(FrameworkListener
The FrameworkListener object to be removed.
listener)

Removes the specified FrameworkListener object from the context bundle's list of listeners.

public void
removeServiceListener(ServiceListener
The ServiceListener to be removed.
listener)

Removes the specified ServiceListener object from the context bundle's list of listeners.

public boolean

Returns:

false if the context bundle's use count for the service is zero or if the service has been unregistered; true otherwise.
ungetService(ServiceReference<?>
A reference to the service to be released.
reference)

Releases the service object for the service referenced by the specified ServiceReference object.

Method Detail

addBundleListenerback to summary
public void addBundleListener(BundleListener listener)

Adds the specified BundleListener object to the context bundle's list of listeners if not already present. BundleListener objects are notified when a bundle has a lifecycle state change.

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

Parameters
listener:BundleListener

The BundleListener to be added.

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
SecurityException:
If listener is a SynchronousBundleListener and the caller does not have the appropriate AdminPermission[context bundle,LISTENER], and the Java Runtime Environment supports permissions.
See Also
BundleEvent, BundleListener
addFrameworkListenerback to summary
public void addFrameworkListener(FrameworkListener listener)

Adds the specified FrameworkListener object to the context bundle's list of listeners if not already present. FrameworkListeners are notified of general Framework events.

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

Parameters
listener:FrameworkListener

The FrameworkListener object to be added.

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
See Also
FrameworkEvent, FrameworkListener
addServiceListenerback to summary
public void addServiceListener(ServiceListener listener, String filter) throws InvalidSyntaxException

Adds the specified ServiceListener object with the specified filter to the context bundle's list of listeners. See Filter for a description of the filter syntax. ServiceListener objects are notified when a service has a lifecycle state change.

If the context bundle's list of listeners already contains a listener l such that (l==listener), then 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#OBJECTCLASS property. If filter is null , all services are considered to match the filter.

When using a filter, it is possible that the ServiceEvent s for the complete lifecycle of a service will not be delivered to the listener. For example, if the filter only matches when the property x has the value 1, the listener will not be called if the service is registered with the property x not set to the value 1. Subsequently, when the service is modified setting property x to the value 1, the filter will match and the listener will be called with a ServiceEvent of type MODIFIED. Thus, the listener will not be called with a ServiceEvent of type REGISTERED.

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:ServiceListener

The ServiceListener object to be added.

filter:String

The filter criteria.

Exceptions
InvalidSyntaxException:
If filter contains an invalid filter string that cannot be parsed.
IllegalStateException:
If this BundleContext is no longer valid.
See Also
ServiceEvent, ServiceListener, ServicePermission
addServiceListenerback to summary
public void addServiceListener(ServiceListener listener)

Adds the specified ServiceListener object to the 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:ServiceListener

The ServiceListener object to be added.

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
See Also
addServiceListener(ServiceListener, String)
createFilterback to summary
public Filter createFilter(String filter) throws InvalidSyntaxException

Creates a Filter object. This Filter object may be used to match a ServiceReference object or a Dictionary object.

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

Parameters
filter:String

The filter string.

Returns:Filter

A Filter object encapsulating the filter string.

Exceptions
InvalidSyntaxException:
If filter contains an invalid filter string that cannot be parsed.
NullPointerException:
If filter is null.
IllegalStateException:
If this BundleContext is no longer valid.
Since
1.1
See Also
Framework specification for a description of the filter string syntax., FrameworkUtil#createFilter(String)
getAllServiceReferencesback to summary
public ServiceReference<?>[] getAllServiceReferences(String clazz, String filter) throws InvalidSyntaxException

Returns an array of ServiceReference objects. The returned array of ServiceReference objects contains services that were registered under the specified class and match the specified filter expression.

The list is valid at the time of the call to this method. However since the Framework is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See Filter for a description of the filter syntax. If the specified filter is null, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

The result is an array of ServiceReference objects for all services that meet all of the following conditions:

  • If the specified class name, clazz, is not null, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service's objectClass property.
  • If the specified filter is not null, the filter expression must match the service.
  • If the Java Runtime Environment supports permissions, the caller must have ServicePermission with the GET action for at least one of the class names under which the service was registered.
Parameters
clazz:String

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

filter:String

The filter expression or null for all services.

Returns:ServiceReference<?>[]

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

Exceptions
InvalidSyntaxException:
If the specified filter contains an invalid filter expression that cannot be parsed.
IllegalStateException:
If this BundleContext is no longer valid.
Since
1.3
getBundleback to summary
public Bundle getBundle()

Redeclares org.osgi.framework.BundleReference.getBundle.

Returns the Bundle object associated with this BundleContext. This bundle is called the context bundle.

Returns:Bundle

The Bundle object associated with this BundleContext.

Annotations
@Override
Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
getBundleback to summary
public Bundle getBundle(long id)

Returns the bundle with the specified identifier.

Parameters
id:long

The identifier of the bundle to retrieve.

Returns:Bundle

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

getBundleback to summary
public Bundle getBundle(String location)

Returns the bundle with the specified location.

Parameters
location:String

The location of the bundle to retrieve.

Returns:Bundle

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

Since
1.6
getBundlesback to summary
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, since the Framework is a very dynamic environment, bundles can be installed or uninstalled at anytime.

Returns:Bundle[]

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

getDataFileback to summary
public File getDataFile(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.

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

Parameters
filename:String

A relative name to the file to be accessed.

Returns:File

A File object that represents the requested file or null if the platform does not have file system support.

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
getPropertyback to summary
public String getProperty(String key)

Returns the value of the specified property. If the key is not found in the Framework properties, the system properties are then searched. The method returns null if the property is not found.

All bundles must have permission to read properties whose names start with "org.osgi.".

Parameters
key:String

The name of the requested property.

Returns:String

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

Exceptions
SecurityException:
If the caller does not have the appropriate PropertyPermission to read the property, and the Java Runtime Environment supports permissions.
getServiceback to summary
public <S> S getService(ServiceReference<S> reference)

Returns the service object for the service referenced by the specified ServiceReference object.

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

When a bundle's use count for the service drops to zero, the bundle should no longer use the service object.

This method will always return null when the service associated with the specified 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. If the context bundle's use count for the service is currently zero and the service has bundle or prototype scope, the ServiceFactory#getService(Bundle, ServiceRegistration) method is called to supply the service object for the context bundle. If the service object returned by the ServiceFactory object is null, not an instanceof all the classes named when the service was registered or the ServiceFactory object throws an exception or will be recursively called for the context bundle, null is returned and a Framework event of type FrameworkEvent#ERROR containing a ServiceException describing the error is fired. The supplied 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 service object for the context bundle will return the cached service object.
  3. The context bundle's use count for the service is incremented by one.
  4. The service object for the service is returned.
Parameters
<S>
Type of Service.
reference:ServiceReference<S>

A reference to the service.

Returns:S

A service object for the service associated with reference or null if the service is not registered, the service object returned by a ServiceFactory does not implement the classes under which it was registered or the ServiceFactory threw an exception.

Exceptions
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.
IllegalStateException:
If this BundleContext is no longer valid.
IllegalArgumentException:
If the specified ServiceReference was not created by the same framework instance as this BundleContext.
See Also
ungetService(ServiceReference), ServiceFactory
getServiceObjectsback to summary
public <S> ServiceObjects<S> getServiceObjects(ServiceReference<S> reference)

Returns the ServiceObjects object for the service referenced by the specified ServiceReference object.

The ServiceObjects object can be used to obtain multiple service objects for services with prototype scope.

For services with singleton or bundle scope, the ServiceObjects#getService() method behaves the same as the getService(ServiceReference) method and the ServiceObjects#ungetService(Object) method behaves the same as the ungetService(ServiceReference) method. That is, only one, use-counted service object is available from the ServiceObjects object.

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

Parameters
<S>
Type of Service.
reference:ServiceReference<S>

A reference to the service.

Returns:ServiceObjects<S>

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

Exceptions
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.
IllegalStateException:
If this BundleContext is no longer valid.
IllegalArgumentException:
If the specified ServiceReference was not created by the same framework instance as this BundleContext.
Since
1.8
See Also
PrototypeServiceFactory
getServiceReferenceback to summary
public ServiceReference<?> getServiceReference(String clazz)

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

The returned 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 any time.

This method is the same as calling getServiceReferences(String, String) with a null filter expression and then finding the reference with the highest priority. 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 priority is selected. This priority is defined as the service reference with the highest ranking (as specified in its Constants#SERVICE_RANKING property) is returned.

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

Parameters
clazz:String

The class name with which the service was registered.

Returns:ServiceReference<?>

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

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
See Also
getServiceReferences(String, String)
getServiceReferenceback to summary
public <S> ServiceReference<S> getServiceReference(Class<S> clazz)

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

The returned 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 any time.

This method is the same as calling getServiceReferences(Class, String) with a null filter expression. 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_RANKING property) is returned.

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

Parameters
<S>
Type of Service.
clazz:Class<S>

The class under whose name the service was registered. Must not be null.

Returns:ServiceReference<S>

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

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
Since
1.6
See Also
getServiceReferences(Class, String)
getServiceReferencesback to summary
public ServiceReference<?>[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException

Returns an array of ServiceReference objects. The returned array of ServiceReference objects contains services that were registered under the specified class, match the specified filter expression, and the packages for the class names under which the services were registered match the context bundle's packages as defined in ServiceReference#isAssignableTo(Bundle, String).

The list is valid at the time of the call to this method. However since the Framework is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See Filter for a description of the filter syntax. If the specified filter is null, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

The result is an array of ServiceReference objects for all services that meet all of the following conditions:

  • If the specified class name, clazz, is not null, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service's objectClass property.
  • If the specified filter is not null, the filter expression must match the service.
  • If the Java Runtime Environment supports permissions, the caller must have ServicePermission with the GET action for at least one of the class names under which the service was registered.
  • For each class name with which the service was registered, calling ServiceReference#isAssignableTo(Bundle, String) with the context bundle and the class name on the service's ServiceReference object must return true
Parameters
clazz:String

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

filter:String

The filter expression or null for all services.

Returns:ServiceReference<?>[]

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

Exceptions
InvalidSyntaxException:
If the specified filter contains an invalid filter expression that cannot be parsed.
IllegalStateException:
If this BundleContext is no longer valid.
getServiceReferencesback to summary
public <S> Collection<ServiceReference<S>> getServiceReferences(Class<S> clazz, String filter) throws InvalidSyntaxException

Returns a collection of ServiceReference objects. The returned collection of ServiceReference objects contains services that were registered under the name of the specified class, match the specified filter expression, and the packages for the class names under which the services were registered match the context bundle's packages as defined in ServiceReference#isAssignableTo(Bundle, String).

The collection is valid at the time of the call to this method. However since the Framework is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See Filter for a description of the filter syntax. If the specified filter is null, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

The result is a collection of ServiceReference objects for all services that meet all of the following conditions:

  • The service must have been registered with the name of the specified class. The complete list of class names with which a service was registered is available from the service's objectClass property.
  • If the specified filter is not null, the filter expression must match the service.
  • If the Java Runtime Environment supports permissions, the caller must have ServicePermission with the GET action for at least one of the class names under which the service was registered.
  • For each class name with which the service was registered, calling ServiceReference#isAssignableTo(Bundle, String) with the context bundle and the class name on the service's ServiceReference object must return true
Parameters
<S>
Type of Service
clazz:Class<S>

The class under whose name the service was registered. Must not be null.

filter:String

The filter expression or null for all services.

Returns:Collection<ServiceReference<S>>

A collection of ServiceReference objects. May be empty if no services are registered which satisfy the search.

Exceptions
InvalidSyntaxException:
If the specified filter contains an invalid filter expression that cannot be parsed.
IllegalStateException:
If this BundleContext is no longer valid.
Since
1.6
installBundleback to summary
public Bundle installBundle(String location, InputStream input) throws BundleException

Installs a bundle from the specified InputStream object.

If the specified InputStream is null, the Framework must create the InputStream from which to read the bundle by interpreting, in an implementation dependent manner, the specified location.

The specified location identifier will be used as the identity of the bundle. Every installed bundle is uniquely identified by its location identifier which is typically in the form of a URL.

The following steps are required to install a bundle:

  1. If a bundle containing the same location identifier is already installed, the Bundle object for that bundle is returned.
  2. The bundle's content is read from the input stream. If this fails, a BundleException is thrown.
  3. 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.
  4. The bundle's state is set to INSTALLED.
  5. A bundle event of type BundleEvent#INSTALLED is fired.
  6. The Bundle object for the newly or previously 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. If there was an existing bundle for the specified location, then that bundle must still be in the state it was prior to calling this method.
Parameters
location:String

The location identifier of the bundle to install.

input:InputStream

The InputStream object from which this bundle will be read or null to indicate the Framework must create the input stream from the specified location identifier. The input stream must always be closed when this method completes, even if an exception is thrown.

Returns:Bundle

The Bundle object of the installed bundle.

Exceptions
BundleException:
If the installation failed. BundleException types thrown by this method include: BundleException#READ_ERROR , BundleException#DUPLICATE_BUNDLE_ERROR, BundleException#MANIFEST_ERROR, and BundleException#REJECTED_BY_HOOK.
SecurityException:
If the caller does not have the appropriate AdminPermission[installed bundle,LIFECYCLE], and the Java Runtime Environment supports permissions.
IllegalStateException:
If this BundleContext is no longer valid.
installBundleback to summary
public Bundle installBundle(String location) throws BundleException

Installs a bundle from the specified location identifier.

This method performs the same function as calling installBundle(String, InputStream) with the specified location identifier and a null InputStream.

Parameters
location:String

The location identifier of the bundle to install.

Returns:Bundle

The Bundle object of the installed bundle.

Exceptions
BundleException:
If the installation failed. BundleException types thrown by this method include: BundleException#READ_ERROR , BundleException#DUPLICATE_BUNDLE_ERROR, BundleException#MANIFEST_ERROR, and BundleException#REJECTED_BY_HOOK.
SecurityException:
If the caller does not have the appropriate AdminPermission[installed bundle,LIFECYCLE], and the Java Runtime Environment supports permissions.
IllegalStateException:
If this BundleContext is no longer valid.
See Also
installBundle(String, InputStream)
registerServiceback to summary
public ServiceRegistration<?> registerService(String[] clazzes, Object service, Dictionary<String, ?> 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. Other bundles can locate the service by using one of the getServiceReferences(Class, String), getServiceReferences(String, String), getServiceReference(Class) or getServiceReference(String) methods.

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

The following steps are required to register a service:

  1. If service does not implement ServiceFactory, an IllegalArgumentException is thrown if service is not an instanceof all the specified class names.
  2. The Framework adds the following service properties to the service properties from the specified Dictionary (which may be null): Properties with these names in the specified Dictionary will be ignored.
  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#REGISTERED is fired.
  5. A ServiceRegistration object for this registration is returned.
Parameters
clazzes:String[]

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:Object

The service object or an object implementing ServiceFactory.

properties:Dictionary<String, ?>

The properties for this service. The keys in the properties object must all be String objects. See Constants for 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(Dictionary) method must be called. The set of properties may be null if the service has no properties.

Returns:ServiceRegistration<?>

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

Exceptions
IllegalArgumentException:
If one of the following is true:
  • service is null.
  • service does not implement ServiceFactory and is not an instance of all the specified classes.
  • properties contains case variants of the same key name.
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.
IllegalStateException:
If this BundleContext is no longer valid.
See Also
ServiceRegistration, PrototypeServiceFactory, ServiceFactory
registerServiceback to summary
public ServiceRegistration<?> registerService(String clazz, Object service, Dictionary<String, ?> properties)

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

This method is otherwise identical to registerService(String[], Object, 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#OBJECTCLASS property will be an array of string, rather than just a single string.

Parameters
clazz:String

The class name under which the service can be located.

service:Object

The service object or an object implementing ServiceFactory.

properties:Dictionary<String, ?>

The properties for this service.

Returns:ServiceRegistration<?>

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

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
See Also
registerService(String[], Object, Dictionary)
registerServiceback to summary
public <S> ServiceRegistration<S> registerService(Class<S> clazz, S service, Dictionary<String, ?> properties)

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

This method is otherwise identical to registerService(String, Object, Dictionary) and is provided to return a type safe ServiceRegistration.

Parameters
<S>
Type of Service.
clazz:Class<S>

The class under whose name the service can be located.

service:S

The service object or an object implementing ServiceFactory.

properties:Dictionary<String, ?>

The properties for this service.

Returns:ServiceRegistration<S>

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

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
Since
1.6
See Also
registerService(String, Object, Dictionary)
registerServiceback to summary
public <S> ServiceRegistration<S> registerService(Class<S> clazz, ServiceFactory<S> factory, Dictionary<String, ?> properties)

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

This method is otherwise identical to registerService(Class, Object, Dictionary) and is provided to return a type safe ServiceRegistration when registering a ServiceFactory.

Parameters
<S>
Type of Service.
clazz:Class<S>

The class under whose name the service can be located.

factory:ServiceFactory<S>

The ServiceFactory object.

properties:Dictionary<String, ?>

The properties for this service.

Returns:ServiceRegistration<S>

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

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
Since
1.8
See Also
registerService(Class, Object, Dictionary)
removeBundleListenerback to summary
public void removeBundleListener(BundleListener listener)

Removes the specified BundleListener object from the context bundle's list of listeners.

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

Parameters
listener:BundleListener

The BundleListener object to be removed.

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
SecurityException:
If listener is a SynchronousBundleListener and the caller does not have the appropriate AdminPermission[context bundle,LISTENER], and the Java Runtime Environment supports permissions.
removeFrameworkListenerback to summary
public void removeFrameworkListener(FrameworkListener listener)

Removes the specified FrameworkListener object from the context bundle's list of listeners.

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

Parameters
listener:FrameworkListener

The FrameworkListener object to be removed.

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
removeServiceListenerback to summary
public void removeServiceListener(ServiceListener listener)

Removes the specified ServiceListener object from the context bundle's list of listeners.

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

Parameters
listener:ServiceListener

The ServiceListener to be removed.

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
ungetServiceback to summary
public boolean ungetService(ServiceReference<?> reference)

Releases the service object for the service 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.

The service object must 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 release 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 the service is decremented by one.
  3. If the context bundle's use count for the service is now zero and the service has bundle or prototype scope, the ServiceFactory#ungetService(Bundle, ServiceRegistration, Object) method is called to release the service object for the context bundle.
  4. true is returned.
Parameters
reference:ServiceReference<?>

A reference to the service to be released.

Returns:boolean

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

Exceptions
IllegalStateException:
If this BundleContext is no longer valid.
IllegalArgumentException:
If the specified ServiceReference was not created by the same framework instance as this BundleContext.
See Also
getService(ServiceReference), ServiceFactory