public class BundleContextImpl extends Object implements BundleContext, EventDispatcher<Object,Object,Object>
Modifier and Type | Field and Description |
---|---|
protected BundleActivator |
activator
The current instantiation of the activator.
|
Modifier | Constructor and Description |
---|---|
protected |
BundleContextImpl(BundleHost bundle)
Construct a BundleContext which wrappers the framework for a
bundle
|
Modifier and Type | Method and Description |
---|---|
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,
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(String filter)
Construct a Filter object.
|
void |
dispatchEvent(Object originalListener,
Object l,
int action,
Object object)
Bottom level event dispatcher for the BundleContext.
|
ServiceReference<?>[] |
getAllServiceReferences(String clazz,
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.
|
Bundle |
getBundle(String location)
Returns the bundle with the specified location.
|
AbstractBundle |
getBundleByLocation(String location)
Retrieve the bundle that has the given location.
|
AbstractBundle |
getBundleImpl() |
Bundle[] |
getBundles()
Retrieve a list of all installed bundles.
|
File |
getDataFile(String filename)
Creates a
File object for a file in the
persistent storage area provided for the bundle by the framework. |
Framework |
getFramework() |
String |
getProperty(String key)
Retrieve the value of the named environment property.
|
<S> S |
getService(ServiceReference<S> reference)
Get a service's service object.
|
<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. |
ServiceReference<?> |
getServiceReference(String clazz)
Get a service reference.
|
<S> Collection<ServiceReference<S>> |
getServiceReferences(Class<S> clazz,
String filter)
Returns a collection of
ServiceReference objects. |
ServiceReference<?>[] |
getServiceReferences(String clazz,
String filter)
Returns a list of ServiceReference objects.
|
Map<ServiceRegistrationImpl<?>,ServiceUse<?>> |
getServicesInUseMap()
Return the map of ServiceRegistrationImpl to ServiceUse for services being
used by this context.
|
Bundle |
installBundle(String location)
Installs a bundle from the specified
location identifier. |
Bundle |
installBundle(String location,
InputStream in)
Installs a bundle from the specified
InputStream object. |
protected boolean |
isValid()
This method checks that the context is still valid.
|
<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.
|
ServiceRegistration<?> |
registerService(String[] clazzes,
Object service,
Dictionary<String,?> properties)
Register a service with multiple names.
|
ServiceRegistration<?> |
registerService(String clazz,
Object service,
Dictionary<String,?> 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.
|
protected BundleActivator activator
protected BundleContextImpl(BundleHost bundle)
bundle
- The bundle we are wrapping.protected void close()
public String getProperty(String key)
getProperty
in interface BundleContext
key
- The name of the requested property.null
if
the property is undefined.public Bundle getBundle()
getBundle
in interface BundleContext
getBundle
in interface BundleReference
public AbstractBundle getBundleImpl()
public Bundle installBundle(String location) throws BundleException
BundleContext
location
identifier.
This method performs the same function as calling
BundleContext.installBundle(String,InputStream)
with the specified
location
identifier and a null
InputStream.
installBundle
in interface BundleContext
location
- The location identifier of the bundle to install.Bundle
object of the installed bundle.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
.BundleContext.installBundle(String, InputStream)
public Bundle installBundle(String location, InputStream in) throws BundleException
BundleContext
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:
Bundle
object for that bundle is returned.
BundleException
is thrown.
BundleException
is thrown.
INSTALLED
.
BundleEvent.INSTALLED
is fired.
Bundle
object for the newly or previously installed
bundle is returned.
getState()
in { INSTALLED
, RESOLVED
}.
installBundle
in interface BundleContext
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.Bundle
object of the installed bundle.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
.public Bundle getBundle(long id)
getBundle
in interface BundleContext
id
- The identifier of the bundle to retrieve.null
if the identifier doesn't match any installed bundle.public Bundle getBundle(String location)
BundleContext
getBundle
in interface BundleContext
location
- The location of the bundle to retrieve.Bundle
object or null
if the location does not
match any installed bundle.public AbstractBundle getBundleByLocation(String location)
location
- The location string of the bundle to retrieve.null
if the location doesn't match any installed bundle.public Bundle[] getBundles()
getBundles
in interface BundleContext
AbstractBundle
objects, one
object per installed bundle.public void addServiceListener(ServiceListener listener, String filter) throws InvalidSyntaxException
ServiceListener
s 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.
addServiceListener
in interface BundleContext
listener
- The service listener to add.filter
- The filter criteria.InvalidSyntaxException
- If the filter parameter contains
an invalid filter string which cannot be parsed.IllegalStateException
- If the bundle context has stopped.ServiceEvent
,
ServiceListener
public void addServiceListener(ServiceListener listener)
This method is the same as calling
addServiceListener(ServiceListener, String)
with filter set to null
.
addServiceListener
in interface BundleContext
listener
- The ServiceListener
object to be added.addServiceListener(ServiceListener, String)
public void removeServiceListener(ServiceListener listener)
getBundle()
for a definition of context bundle.
If this method is called with a listener which is not registered, then this method does nothing.
removeServiceListener
in interface BundleContext
listener
- The service listener to remove.IllegalStateException
- If the bundle context has stopped.public void addBundleListener(BundleListener listener)
BundleListener
s 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.addBundleListener
in interface BundleContext
listener
- The bundle listener to add.IllegalStateException
- If the bundle context has stopped.BundleEvent
,
BundleListener
public void removeBundleListener(BundleListener listener)
getBundle()
for a definition of context bundle.
If this method is called with a listener which is not registered, then this method does nothing.
removeBundleListener
in interface BundleContext
listener
- The bundle listener to remove.IllegalStateException
- If the bundle context has stopped.public void addFrameworkListener(FrameworkListener 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.addFrameworkListener
in interface BundleContext
listener
- The framework listener to add.IllegalStateException
- If the bundle context has stopped.FrameworkEvent
,
FrameworkListener
public void removeFrameworkListener(FrameworkListener listener)
getBundle()
for a definition of context bundle.
If this method is called with a listener which is not registered, then this method does nothing.
removeFrameworkListener
in interface BundleContext
listener
- The framework listener to remove.IllegalStateException
- If the bundle context has stopped.public ServiceRegistration<?> registerService(String[] clazzes, Object service, Dictionary<String,?> properties)
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:
ServiceFactory
,
an IllegalArgumentException
is thrown if the
service parameter is not an instanceof
all the classes named.
ServiceEvent
of type ServiceEvent.REGISTERED
is synchronously sent.
ServiceRegistration
object for this registration
is returned.
registerService
in interface BundleContext
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.ServiceRegistration
object for use by the bundle
registering the service to update the
service's properties or to unregister the service.IllegalArgumentException
- If one of the following is true:
ServiceFactory
and is not an
instanceof
all the named classes in the clazzes parameter.
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.IllegalStateException
- If the bundle context has stopped.ServiceRegistration
,
ServiceFactory
public ServiceRegistration<?> registerService(String clazz, Object service, Dictionary<String,?> properties)
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.
registerService
in interface BundleContext
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.ServiceRegistration
object for use by the bundle
registering the service to update the service's properties or to
unregister the service.registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
public ServiceReference<?>[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException
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 Filter
for 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:
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.OBJECTCLASS
property.
getServiceReferences
in interface BundleContext
clazz
- The class name with which the service was registered, or
null for all services.filter
- The filter criteria.InvalidSyntaxException
- If filter contains
an invalid filter string which cannot be parsed.public ServiceReference<?>[] getAllServiceReferences(String clazz, String filter) throws InvalidSyntaxException
BundleContext
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:
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.
filter
is not null
, the filter
expression must match the service.
ServicePermission
with the GET
action for at least
one of the class names under which the service was registered.
getAllServiceReferences
in interface BundleContext
clazz
- The class name with which the service was registered or
null
for all services.filter
- The filter expression or null
for all services.ServiceReference
objects or null
if
no services are registered which satisfy the search.InvalidSyntaxException
- If the specified filter
contains
an invalid filter expression that cannot be parsed.public ServiceReference<?> getServiceReference(String clazz)
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.
getServiceReference
in interface BundleContext
clazz
- The class name which the service must implement.ServiceReference
object, or null
if no services are registered which implement the named class.getServiceReferences(java.lang.String, java.lang.String)
public <S> S getService(ServiceReference<S> reference)
getService(org.osgi.framework.ServiceReference<S>)
, 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:
null
is returned.
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.
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.
getService
in interface BundleContext
S
- Type of Service.reference
- A reference to the service whose service object is desired.null
if the service is not registered.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.IllegalStateException
- If the bundle context has stopped.ungetService(org.osgi.framework.ServiceReference<?>)
,
ServiceFactory
public boolean ungetService(ServiceReference<?> reference)
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:
false
is returned.
ServiceFactory
,
the ServiceFactory.ungetService
method
is called to release the service object for the context bundle.
true
is returned.
ungetService
in interface BundleContext
reference
- A reference to the service to be released.false
if the context bundle's use count for the service
is zero or if the service has been unregistered,
otherwise true
.IllegalStateException
- If the bundle context has stopped.getService(org.osgi.framework.ServiceReference<S>)
,
ServiceFactory
public File getDataFile(String filename)
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.
getDataFile
in interface BundleContext
filename
- A relative name to the file to be accessed.File
object that represents the requested file or
null
if the adaptor does not have file system support.IllegalStateException
- If the bundle context has stopped.protected void start() throws BundleException
BundleException
- if
the bundle has a class that implements the BundleActivator interface,
but Framework couldn't instantiate it, or the BundleActivator.start()
method failedprotected void startActivator(BundleActivator bundleActivator) throws BundleException
bundleActivator
- that activator to startBundleException
protected void stop() throws BundleException
BundleException
- if
the bundle has a class that implements the BundleActivator interface,
and the BundleActivator.stop() method failedpublic Map<ServiceRegistrationImpl<?>,ServiceUse<?>> getServicesInUseMap()
public void dispatchEvent(Object originalListener, Object l, int action, Object object)
dispatchEvent
in interface EventDispatcher<Object,Object,Object>
originalListener
- listener object registered under.l
- listener to call (may be filtered).action
- Event class typeobject
- Event objectpublic Filter createFilter(String filter) throws InvalidSyntaxException
createFilter
in interface BundleContext
filter
- The filter string.InvalidSyntaxException
- If the filter parameter contains
an invalid filter string which cannot be parsed.FrameworkUtil.createFilter(String)
public void checkValid()
IllegalStateException
- If the context bundle has stopped.protected boolean isValid()
public Framework getFramework()
public <S> ServiceRegistration<S> registerService(Class<S> clazz, S service, Dictionary<String,?> properties)
BundleContext
This method is otherwise identical to
BundleContext.registerService(String, Object, Dictionary)
and is provided to
return a type safe ServiceRegistration
.
registerService
in interface BundleContext
S
- Type of Service.clazz
- The class under whose name the service can be located.service
- The service object or a ServiceFactory
object.properties
- The properties for this service.ServiceRegistration
object for use by the bundle
registering the service to update the service's properties or to
unregister the service.BundleContext.registerService(String, Object, Dictionary)
public <S> ServiceReference<S> getServiceReference(Class<S> clazz)
BundleContext
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
BundleContext.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.
getServiceReference
in interface BundleContext
S
- Type of Service.clazz
- The class under whose name the service was registered. Must
not be null
.ServiceReference
object, or null
if no services
are registered which implement the specified class.BundleContext.getServiceReferences(Class, String)
public <S> Collection<ServiceReference<S>> getServiceReferences(Class<S> clazz, String filter) throws InvalidSyntaxException
BundleContext
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:
objectClass
property.
filter
is not null
, the filter
expression must match the service.
ServicePermission
with the GET
action for at least
one of the class names under which the service was registered.
ServiceReference.isAssignableTo(Bundle, String)
with the context
bundle and the class name on the service's ServiceReference
object must return true
getServiceReferences
in interface BundleContext
S
- Type of Serviceclazz
- The class under whose name the service was registered. Must
not be null
.filter
- The filter expression or null
for all services.ServiceReference
objects. May be empty if
no services are registered which satisfy the search.InvalidSyntaxException
- If the specified filter
contains
an invalid filter expression that cannot be parsed.Copyright © 2007–2018 The Apache Software Foundation. All rights reserved.