BundleContext

Syntax

public interface BundleContext

Description

Bundle's execution context. Represents the execution context of a bundle within the framework. The context provides methods which allow the bundle to interact with the framework.

The provided methods allow a bundle to:

• Subscribe to the events published by the framework.

• Register services in the framework's service registry.

• Retrieve references to service from the framework's service registry.

• Get and release the service objects for a referenced service.

• Install new bundles into the framework.

• Get the list of installed bundles.

• Get the Bundle object 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 the bundle when the bundle is started (BundleActivator.start(BundleContext) ). The same BundleContext object will be passed to the bundle when the bundle is stopped (BundleActivator.stop(BundleContext) ). The context is for the private use of the bundle and, in general, is not meant to be shared with other bundles. The context is used when accounting for services and event listeners.

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

The framework is the only one that can create BundleContext objects and these objects 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.

Methods

addBundleListener(BundleListener)

public void addBundleListener(BundleListener listener)
            throws java.lang.IllegalStateException

Add a bundle listener. BundleListener s are notified when a bundle has a life cycle state change. The listener is added to the context bundle's list of listeners. See getBundle() for a definition of context bundle.

Parameters:

listener— The bundle listener to add.

Throws:

javalang.IllegalStateException— If the context bundle has stopped.

See Also: BundleEvent, BundleListener

addFrameworkListener(FrameworkListener)

public void addFrameworkListener(FrameworkListener listener)
            throws java.lang.IllegalStateException

Add a general framework listener. FrameworkListener s are notified of general framework events. The listener is added to the context bundle's list of listeners. See getBundle() for a definition of context bundle.

Parameters:

listener— The framework listener to add.

Throws:

javalang.IllegalStateException— If the context bundle has stopped.

See Also: FrameworkEvent, FrameworkListener

addServiceListener(ServiceListener)

public void addServiceListener(ServiceListener listener)

Add a service listener.

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

See Also: addServiceListener(ServiceListener, String)

addServiceListener(ServiceListener, String)

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

Add a service listener with a filter. ServiceListener s are notified when a service has a life cycle state change. See getServiceReferences(String, String) for a description of the filter syntax. The listener is added to the context bundle's list of listeners. See getBundle() for a definition of context bundle.

The listener is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the “objectClass” property. If the filter parameter is null, all services are considered to match the filter.

If the Java runtime environment supports permissions, the service listener 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 service listener to add.

filter— The filter criteria.

Throws:

InvalidSyntaxException— If the filter parameter contains an invalid filter string which cannot be parsed.

javalang.IllegalStateException— If the context bundle has stopped.

See Also: ServiceEvent, ServiceListener

getBundle()

public Bundle getBundle()
            throws java.lang.IllegalStateException

Retrieve the Bundle object for the context bundle.

The context bundle is defined as the bundle which is associated with this BundleContext. More specifically, the context bundle is defined to be the bundle which was given this BundleContext in its BundleActivator.

Returns: The context bundle's Bundle object.

Throws:

javalang.IllegalStateException— If the context bundle has stopped.

getBundle(long)

public Bundle getBundle(long id)

Retrieve the bundle that has the given unique identifier.

Parameters:

id— The identifier of the bundle to retrieve.

Returns: A Bundle object, or null if the identifier doesn't match any installed bundle.

getBundles()

public Bundle[] getBundles()

Retrieve a list of all installed bundles. The list is valid at the time of the call to getBundles, but the framework is a very dynamic environment and bundles can be installed or uninstalled at anytime.

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

getDataFile(String)

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

Creates a File object for a file in the persistent storage area provided for the bundle by the framework. If the platform does not have file system support, this method will return null.

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 the empty string (“”) as the parameter. 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 by the framework.

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:

javalang.IllegalStateException— If the context bundle has stopped.

getProperty(String)

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

Retrieve the value of the named environment property. Values are provided for the following properties:

org.osgi.framework.version

The version of the framework.

org.osgi.framework.vendor

The vendor of this framework implementation.

org.osgi.framework.language

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

org.osgi.framework.os.name

The name of the operating system of the hosting computer.

org.osgi.framework.os.version

The version number of the operating system of the hosting computer.

org.osgi.framework.processor

The name of the processor of the hosting computer.

Note: These last four properties are used by the Bundle-NativeCode manifest header's matching algorithm for selecting native code.

Parameters:

key— The name of the requested property.

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

getService(ServiceReference)

public java.lang.Object getService(ServiceReference reference) throws
            java.lang.SecurityException, java.lang.Illegal-StateException

Get a service's service object. Retrieves the service object for a service. A bundle's use of a service is tracked by a use count. Each time a service's service object is returned by getService(ServiceReference), the context bundle's use count for the service is incremented by one. Each time the service is release by ungetService(ServiceReference), the context bundle's use count for the service is decremented by one. When a bundle's use count for a service drops to zero, the bundle should no longer use the 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 followed 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 now one and the service was registered with a ServiceFactory, the ServiceFactory. getService(Bundle, 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 is not an instanceof all the classes named when the service was registered or the ServiceFactory throws an exception, null is returned and a FrameworkEvent of type FrameworkEvent.ERROR is broadcast.
4.	The service object for the service is returned.

Parameters:

reference— A reference to the service whose service object is desired.

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

Throws:

javalang.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.

javalang.IllegalStateException— If the context bundle has stopped.

See Also: ungetService(ServiceReference), ServiceFactory

getServiceReference(String)

public ServiceReference getServiceReference(java.lang.String
            clazz)

Get a service reference. Retrieves a ServiceReference for a service which implements the named class.

This reference is valid at the time of the call to this method, but since the framework is a very dynamic environment, services can be modified or unregistered at anytime.

This method is provided as a convenience for when the caller is interested in any service which implements a named class. This method is the same as calling getServiceReferences(String, String) with a null filter string but only a single ServiceReference 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(String, String)

getServiceReferences(String, String)

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

Get a list of service references. Retrieves a list of ServiceReference s for services which implement and were registered under the named class and match the filter criteria.

The list is valid at the time of the call to this method, but the framework is a very dynamic environment and services can be modified or unregistered at anytime.

The filter parameter is used to select registered service whose properties objects contain keys and values which satisfy the filter. The syntax of the filter parameter is the string representation of LDAP search filters as defined in RFC 1960: A String Representation of LDAP Search Filters (http://www.ietf.org/rfc/rfc1960.txt). It should be noted that RFC 2254: A String Representation of LDAP Search Filters (http://www.ietf.org/rfc/rfc2254.txt) supersedes RFC 1960 but only adds extensible matching and is not applicable for this API.

The string representation of an LDAP search filter is defined by the following grammar. It uses a prefix format.

<filter> ::= '(' <filtercomp> ')'
<filtercomp> ::= <and> | <or> | <not> | <item>
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist>
<not> ::= '!' <filter>
<filterlist> ::= <filter> | <filter> <filterlist>
<item> ::= <simple> | <present> | <substring>
<simple> ::= <attr> <filtertype> <value>
<filtertype> ::= <equal> | <approx> | <greater> | <less>
<equal> ::= '='
<approx> ::= '~='
<greater> ::= '>='
<less> ::= '<='
<present> ::= <attr> '=*'
<substring> ::= <attr> '=' <initial> <any> <final>
<initial> ::= NULL | <value>
<any> ::= '*' <starval>
<starval> ::= NULL | <value> '*' <starval>
<final> ::= NULL | <value>

<attr> is a string representing an attributte, or key, in the properties objects of the registered services. Attribute names are not case sensitive; that is cn and CN both refer to the same attribute. <value> is a string representing the value, or part of one, of a key in the properties objects of the registered services. If a <value> must contain one of the characters '*' or '(' or ')', these characters should be escaped by preceding them with the backslash '' character. Note that although both the <substring> and <present> productions can produce the 'attr=*' construct, this construct is used only to denote a presence filter.

Examples of LDAP filters are:

(cn=Babs Jensen)
(!(cn=Tim Howes))
(&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
(o=univ*of*mich*)

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

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

The approximate match (~=) is implementation specific but should at least ignore case and white space differences. Optional are codes like soundex or other smart “closeness” comparisons.

Comparison of values is not straightforward. Strings are compared differently than numbers and it is possible for a key to have multiple values. Note that that keys in the properties object must always be strings. The comparison is defined by the object type of the key's value. The following rules apply for comparison:

Property Value Type	Comparison Type
String	String comparison
Integer, Long, Float, Double, Byte, Short, BigInteger, BigDecimal	numerical comparison
Character	character comparison
Boolean	equality comparisons only
[] (array)	recursively applied to values
Vector	recursively applied to elements

Note: arrays of primitives are also supported.

A filter matches a property that has multiple values if it matches at least one of those values. For example,

Properties p = new Properties();
p.put( "cn", new String[] { "a", "b", "c" } );

p will match (cn=a) and also (cn=b)

A filter with unrecognizable data types will be evaluated to be false .

The following steps are followed 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 named class. If the caller does not have the 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 the clazz parameter is not null, the set is further reduced to those services which are an instanceof and were registered under the named class.
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 the filter parameter contains an invalid filter string which cannot be parsed.

installBundle(String)

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

Install a bundle from a location. The bundle is obtained from the location parameter as interpreted by the framework in an implementation dependent way. Typically, location will most likely be a URL.

The following steps are followed to install a bundle:

 

1.	If a bundle having the same location is already installed, the Bundle object for that bundle is returned.
2.	The bundle's content is read from the location. If this fails, a BundleException is thrown.
3.	The bundle's associated resources are allocated. The associated resources consist of at least 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 state of the bundle is set to INSTALLED.
5.	A BundleEvent of type BundleEvent.INSTALLED is broadcast.
6.	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 install failed.

java.lang.SecurityException— If the caller does not have the AdminPermission and the Java runtime environment supports permissions.

installBundle(String, InputStream)

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

Install a bundle from an InputStream.

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

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

Parameters:

location— The location identifier of the bundle to install.

in— The InputStream from which the bundle will be read.

Returns: The Bundle of the installed bundle.

Throws:

BundleException— If the provided stream cannot be read.

See Also: installBundle(String)

registerService(String[], Object, Dictionary)

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

Register a service with multiple names. This method registers the given service object with the given properties under the given class names. 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(String, String) or getServiceReference(String) method.

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

The following steps are followed to register a service:

 

1.	If the service parameter is not a ServiceFactory, an IllegalArgumentException is thrown if the service parameter is not an instanceof all the classes named.
2.	The service is added to the framework's service registry and may now be used by other bundles.
3.	A ServiceEvent of type ServiceEvent.REGISTERED is synchronously sent.
4.	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 “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. Changes should not be made to this object after calling this method. To update the service's properties call the ServiceRegistration.setProperties(Dictionary) method. This parameter 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:

javalang.IllegalArgumentException— If one of the following is true:

• The service parameter is null.

• The service parameter is not a ServiceFactory and is not an instanceof all the named classes in the clazzes parameter.

javalang.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.

javalang.IllegalStateException— If the context bundle has stopped.

See Also: ServiceRegistration, ServiceFactory

registerService(String, Object, Dictionary)

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

Register a service with a single name. This method registers the given service object with the given properties under the given class name.

This method is otherwise identical to registerService(String[], Object, Dictionary) and is provided as a convenience when the service parameter will only be registered under a single class name.

See Also: registerService(String[], Object, Dictionary)

removeBundleListener(BundleListener)

public void removeBundleListener(BundleListener listener)
            throws java.lang.IllegalStateException

Remove a bundle listener. The listener is removed from the context bundle's list of listeners. See getBundle() for a definition of context bundle.

If this method is called with a listener which is not registered, then this method does nothing.

Parameters:

listener— The bundle listener to remove.

Throws:

javalang.IllegalStateException— If the context bundle has stopped.

removeFrameworkListener(FrameworkListener)

public void removeFrameworkListener(FrameworkListener listener)
            throws java.lang.IllegalStateException

Remove a framework listener. The listener is removed from the context bundle's list of listeners. See getBundle() for a definition of context bundle.

If this method is called with a listener which is not registered, then this method does nothing.

Parameters:

listener— The framework listener to remove.

Throws:

javalang.IllegalStateException— If the context bundle has stopped.

removeServiceListener(ServiceListener)

public void removeServiceListener(ServiceListener listener)
            throws java.lang.IllegalStateException

Remove a service listener. The listener is removed from the context bundle's list of listeners. See getBundle() for a definition of context bundle.

If this method is called with a listener which is not registered, then this method does nothing.

Parameters:

listener— The service listener to remove.

Throws:

javalang.IllegalStateException— If the context bundle has stopped.

ungetService(ServiceReference)

public boolean ungetService(ServiceReference reference)
            throws java.lang.IllegalStateException

Unget a service's service object. Releases the service object for a service. 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 followed 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 now zero and the service was registered with a ServiceFactory, the ServiceFactory.ungetService (Bundle, ServiceRegistration, 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, otherwise true.

Throws:

javalang.IllegalStateException— If the context bundle has stopped.

See Also: getService(ServiceReference), ServiceFactory