org.eclipse.osgi.framework.internal.core
Class BundleContextImpl

java.lang.Object
  org.eclipse.osgi.framework.internal.core.BundleContextImpl

All Implemented Interfaces:

EventDispatcher, BundleContext

public class BundleContextImpl
extends java.lang.Object
implements BundleContext, EventDispatcher

Bundle's execution context. This object is given out to bundles and wraps the internal BundleContext object. It is destroyed when a bundle is stopped.

Field Summary

protected BundleActivator	activator The current instantiation of the activator.
protected java.util.Map	bundleEvent Listener list for bundle's BundleListeners
protected java.util.Map	bundleEventSync Listener list for bundle's SynchronousBundleListeners
protected java.util.Map	frameworkEvent Listener list for bundle's FrameworkListeners

Constructor Summary

protected

BundleContextImpl(BundleHost bundle) Construct a BundleContext which wrappers the framework for a bundle

Method Summary

void	addBundleListener(BundleListener listener) Add a bundle listener.
void	addFrameworkListener(FrameworkListener listener) Add a general framework listener.
void	addServiceListener(ServiceListener listener) Add a service listener.
void	addServiceListener(ServiceListener listener, java.lang.String filter) Add a service listener with a filter.
void	checkValid() This method checks that the context is still valid.
protected void	close() Destroy the wrapper.
Filter	createFilter(java.lang.String filter) Construct a Filter object.
void	dispatchEvent(java.lang.Object originalListener, java.lang.Object l, int action, java.lang.Object object) Bottom level event dispatcher for the BundleContext.
ServiceReference[]	getAllServiceReferences(java.lang.String clazz, java.lang.String filter) Returns an array of ServiceReference objects.
Bundle	getBundle() Retrieve the Bundle object for the context bundle.
Bundle	getBundle(long id) Retrieve the bundle that has the given unique identifier.
AbstractBundle	getBundleByLocation(java.lang.String location) Retrieve the bundle that has the given location.
AbstractBundle	getBundleImpl()
Bundle[]	getBundles() Retrieve 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.
Framework	getFramework()
java.lang.String	getProperty(java.lang.String key) Retrieve the value of the named environment property.
java.lang.Object	getService(ServiceReference reference) Get a service's service object.
ServiceReference	getServiceReference(java.lang.String clazz) Get a service reference.
ServiceReference[]	getServiceReferences(java.lang.String clazz, java.lang.String filter) Returns a list of ServiceReference objects.
java.util.Map	getServicesInUseMap() Return the map of ServiceRegistrationImpl to ServiceUse for services being used by this context.
Bundle	installBundle(java.lang.String location) Installs a bundle from the specified location identifier.
Bundle	installBundle(java.lang.String location, java.io.InputStream in) Installs a bundle from the specified InputStream object.
protected boolean	isValid() This method checks that the context is still valid.
ServiceRegistration	registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary properties) Register a service with multiple names.
ServiceRegistration	registerService(java.lang.String clazz, java.lang.Object service, java.util.Dictionary properties) Register a service with a single name.
void	removeBundleListener(BundleListener listener) Remove a bundle listener.
void	removeFrameworkListener(FrameworkListener listener) Remove a framework listener.
void	removeServiceListener(ServiceListener listener) Remove a service listener.
protected void	start() Call bundle's BundleActivator.start() This method is called by Bundle.startWorker to start the bundle.
protected void	startActivator(BundleActivator bundleActivator) Calls the start method of a BundleActivator.
protected void	stop() Call bundle's BundleActivator.stop() This method is called by Bundle.stopWorker to stop the bundle.
boolean	ungetService(ServiceReference reference) Unget a service's service object.

Methods inherited from class java.lang.Object

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

Field Detail

bundleEvent

protected java.util.Map bundleEvent

Listener list for bundle's BundleListeners

bundleEventSync

protected java.util.Map bundleEventSync

Listener list for bundle's SynchronousBundleListeners

frameworkEvent

protected java.util.Map frameworkEvent

Listener list for bundle's FrameworkListeners

activator

protected BundleActivator activator

The current instantiation of the activator.

Constructor Detail

BundleContextImpl

protected BundleContextImpl(BundleHost bundle)

Construct a BundleContext which wrappers the framework for a bundle

Parameters:

bundle - The bundle we are wrapping.

Method Detail

close

protected void close()

Destroy the wrapper. This is called when the bundle is stopped.

getProperty

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

Retrieve the value of the named environment property.

Specified by:

getProperty in interface BundleContext

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()

Retrieve the Bundle object for the context bundle.

Specified by:

getBundle in interface BundleContext

Returns:

The context bundle's Bundle object.

getBundleImpl

public AbstractBundle getBundleImpl()

installBundle

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

Description copied from interface: BundleContext

Installs a bundle from the specified location identifier.

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

Specified by:

installBundle in interface BundleContext

Parameters:

location - The location identifier of the bundle to install.

Returns:

The Bundle object of the installed bundle.

Throws:

BundleException - If the installation failed.

See Also:

BundleContext.installBundle(String, InputStream)

installBundle

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

Description copied from interface: BundleContext

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 and no trace of the bundle exists.

Specified by:

installBundle in interface BundleContext

Parameters:

location - The location identifier of the bundle to install.

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

The Bundle object of the installed bundle.

Throws:

BundleException - If the input stream cannot be read or the installation failed.

getBundle

public Bundle getBundle(long id)

Retrieve the bundle that has the given unique identifier.

Specified by:

getBundle in interface BundleContext

Parameters:

id - The identifier of the bundle to retrieve.

Returns:

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

getBundleByLocation

public AbstractBundle getBundleByLocation(java.lang.String location)

Retrieve the bundle that has the given location.

Parameters:

location - The location string of the bundle to retrieve.

Returns:

A Bundle object, or null if the location 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.

Specified by:

getBundles in interface BundleContext

Returns:

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

addServiceListener

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

Add a service listener with a filter. ServiceListeners are notified when a service has a lifecycle state change. See getServiceReferences 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 paramater is null, all services are considered to match the filter.

If the Java runtime environment supports permissions, then additional filtering is done. Bundle.hasPermission is called for the bundle which defines the listener to validate that the listener has the ServicePermission permission to "get" the service using at least one of the named classes the service was registered under.

Specified by:

addServiceListener in interface BundleContext

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.

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

See Also:

ServiceEvent, ServiceListener

addServiceListener

public void addServiceListener(ServiceListener listener)

Add a service listener.

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

Specified by:

addServiceListener in interface BundleContext

Parameters:

listener - The ServiceListener object to be added.

See Also:

addServiceListener(ServiceListener, String)

removeServiceListener

public void removeServiceListener(ServiceListener listener)

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.

Specified by:

removeServiceListener in interface BundleContext

Parameters:

listener - The service listener to remove.

Throws:

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

addBundleListener

public void addBundleListener(BundleListener listener)

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

Specified by:

addBundleListener in interface BundleContext

Parameters:

listener - The bundle listener to add.

Throws:

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

See Also:

BundleEvent, BundleListener

removeBundleListener

public void removeBundleListener(BundleListener listener)

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.

Specified by:

removeBundleListener in interface BundleContext

Parameters:

listener - The bundle listener to remove.

Throws:

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

addFrameworkListener

public void addFrameworkListener(FrameworkListener listener)

Add a general framework listener. FrameworkListeners 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.

Specified by:

addFrameworkListener in interface BundleContext

Parameters:

listener - The framework listener to add.

Throws:

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

See Also:

FrameworkEvent, FrameworkListener

removeFrameworkListener

public void removeFrameworkListener(FrameworkListener listener)

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.

Specified by:

removeFrameworkListener in interface BundleContext

Parameters:

listener - The framework listener to remove.

Throws:

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

registerService

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

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 or getServiceReference 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.

Specified by:

registerService in interface BundleContext

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

java.lang.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.

java.lang.SecurityException - If the caller does not have ServicePermission permission to "register" the service for all the named classes and the Java runtime environment supports permissions.

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

See Also:

ServiceRegistration, ServiceFactory

registerService

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(java.lang.String[], java.lang.Object, java.util.Dictionary) and is provided as a convenience when the service parameter will only be registered under a single class name.

Specified by:

registerService in interface BundleContext

Parameters:

clazz - The class name under which the service can be located.

service - The service object or a ServiceFactory object.

properties - The properties for this service.

Returns:

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

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 InvalidSyntaxException will 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.

Specified by:

getServiceReferences in interface BundleContext

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.

getAllServiceReferences

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

Description copied from interface: BundleContext

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.

Specified by:

getAllServiceReferences in interface BundleContext

Parameters:

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

filter - The filter expression or null for all services.

Returns:

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

Throws:

InvalidSyntaxException - If the specified filter contains an invalid filter expression that cannot be parsed.

getServiceReference

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 with a null filter string but only a single ServiceReference is returned.

Specified by:

getServiceReference in interface BundleContext

Parameters:

clazz - The class name which the service must implement.

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)

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(org.osgi.framework.ServiceReference), the context bundle's use count for the service is incremented by one. Each time the service is release by ungetService(org.osgi.framework.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 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.

Specified by:

getService in interface BundleContext

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:

java.lang.SecurityException - If the caller does not have ServicePermission permission 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 bundle context has stopped.

See Also:

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

ungetService

public boolean ungetService(ServiceReference reference)

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 method is called to release the service object for the context bundle.
4. true is returned.

Specified by:

ungetService in interface BundleContext

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:

java.lang.IllegalStateException - If the bundle context 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. If the adaptor 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 the will ensure that the bundle has 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.

Specified by:

getDataFile in interface BundleContext

Parameters:

filename - A relative name to the file to be accessed.

Returns:

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

Throws:

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

start

protected void start()
              throws BundleException

Call bundle's BundleActivator.start() This method is called by Bundle.startWorker to start the bundle.

Throws:

BundleException - if the bundle has a class that implements the BundleActivator interface, but Framework couldn't instantiate it, or the BundleActivator.start() method failed

startActivator

protected void startActivator(BundleActivator bundleActivator)
                       throws BundleException

Calls the start method of a BundleActivator.

Parameters:

bundleActivator - that activator to start

Throws:

BundleException

stop

protected void stop()
             throws BundleException

Call bundle's BundleActivator.stop() This method is called by Bundle.stopWorker to stop the bundle.

Throws:

BundleException - if the bundle has a class that implements the BundleActivator interface, and the BundleActivator.stop() method failed

getServicesInUseMap

public java.util.Map getServicesInUseMap()

Return the map of ServiceRegistrationImpl to ServiceUse for services being used by this context.

Returns:

A map of ServiceRegistrationImpl to ServiceUse for services in use by this context.

dispatchEvent

public void dispatchEvent(java.lang.Object originalListener,
                          java.lang.Object l,
                          int action,
                          java.lang.Object object)

Bottom level event dispatcher for the BundleContext.

Specified by:

dispatchEvent in interface EventDispatcher

Parameters:

originalListener - listener object registered under.

l - listener to call (may be filtered).

action - Event class type

object - Event object

createFilter

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

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

Specified by:

createFilter in interface BundleContext

Parameters:

filter - The filter string.

Returns:

A Filter object encapsulating the filter string.

Throws:

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

See Also:

"Framework specification for a description of the filter string syntax.", FrameworkUtil.createFilter(String)

checkValid

public void checkValid()

This method checks that the context is still valid. If the context is no longer valid, an IllegalStateException is thrown.

Throws:

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

isValid

protected boolean isValid()

This method checks that the context is still valid.

Returns:

true if the context is still valid; false otherwise

getFramework

public Framework getFramework()