|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.osgi.framework.internal.core.BundleContextImpl
public class BundleContextImpl
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 BundleHost |
bundle
Bundle object this context is associated with. |
protected EventListeners |
bundleEvent
Listener list for bundle's BundleListeners |
protected EventListeners |
bundleEventSync
Listener list for bundle's SynchronousBundleListeners |
protected java.lang.Object |
contextLock
private object for locking |
protected Framework |
framework
Internal framework object. |
protected EventListeners |
frameworkEvent
Listener list for bundle's FrameworkListeners |
static java.lang.String |
PROP_SCOPE_SERVICE_EVENTS
|
static boolean |
scopeEvents
|
protected EventListeners |
serviceEvent
Listener list for bundle's ServiceListeners |
protected java.util.Hashtable |
servicesInUse
Services that bundle has used. |
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. |
protected 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. |
protected ServiceRegistrationImpl |
createServiceRegistration(java.lang.String[] clazzes,
java.lang.Object service,
java.util.Dictionary properties)
Create a new ServiceRegistration 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. |
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. |
java.lang.String |
getProperty(java.lang.String key)
Retrieve the value of the named environment property. |
protected ServiceReference[] |
getRegisteredServices()
Provides a list of ServiceReference s for the services
registered by this bundle
or null if the bundle has no registered
services. |
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. |
protected ServiceReferenceImpl[] |
getServicesInUse()
Provides a list of ServiceReferenceImpl s for the
services this bundle is using,
or null if the bundle is not using any services. |
protected boolean |
hasListenServicePermission(ServiceEvent event)
Check for permission to listen to a service. |
Bundle |
installBundle(java.lang.String location)
Install a bundle from a location. |
Bundle |
installBundle(java.lang.String location,
java.io.InputStream in)
Install a bundle from an InputStream. |
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 |
---|
public static final java.lang.String PROP_SCOPE_SERVICE_EVENTS
public static final boolean scopeEvents
protected BundleHost bundle
protected Framework framework
protected java.util.Hashtable servicesInUse
protected EventListeners bundleEvent
protected EventListeners bundleEventSync
protected EventListeners serviceEvent
protected EventListeners frameworkEvent
protected BundleActivator activator
protected java.lang.Object contextLock
Constructor Detail |
---|
protected BundleContextImpl(BundleHost bundle)
bundle
- The bundle we are wrapping.Method Detail |
---|
protected void close()
public java.lang.String getProperty(java.lang.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
public Bundle installBundle(java.lang.String location) throws BundleException
installBundle
in interface BundleContext
location
- The location identifier of the bundle to install.
BundleException
- If the installation failed.public Bundle installBundle(java.lang.String location, java.io.InputStream in) throws BundleException
This method performs all the steps listed in
installBundle(java.lang.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.
installBundle
in interface BundleContext
location
- The location identifier of the bundle to install.in
- The InputStream from which the bundle will be read.
BundleException
- If the provided stream cannot be read or the
installation failed.BundleContext.installBundle(java.lang.String)
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 AbstractBundle getBundleByLocation(java.lang.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, java.lang.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.
java.lang.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.
java.lang.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.
java.lang.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.
java.lang.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.
java.lang.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.
java.lang.IllegalStateException
- If the bundle context has stopped.public ServiceRegistration registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary properties)
ServiceRegistrationImpl
object is returned.
The ServiceRegistrationImpl
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.
ServiceRegistrationImpl
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.
ServiceRegistrationImpl
object for use by the bundle
registering the service to update the
service's properties or to unregister the service.
java.lang.IllegalArgumentException
- If one of the following is true:
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.ServiceRegistrationImpl
,
ServiceFactory
protected ServiceRegistrationImpl createServiceRegistration(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary properties)
clazzes
- The class names under which the service can be located.service
- The service object or a ServiceFactory
object.properties
- The properties for this service.
ServiceRegistrationImpl
object for use by the bundle.public ServiceRegistration registerService(java.lang.String clazz, java.lang.Object service, java.util.Dictionary 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(java.lang.String clazz, java.lang.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 FilterImpl
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(java.lang.String clazz, java.lang.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
criteria.
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 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 set of
ServiceReference
objects:
null
, the filter string
is parsed and the set ServiceReference
objects of
registered services that satisfy the filter is produced. If the filter
string is null
, then all registered services are
considered to satisfy the filter.
ServiceReference
objects produced by the previous step is
reduced by checking that the caller has the
ServicePermission
to get at least one of the class names
under which the service was registered. If the caller does not have the
correct permission for a particular ServiceReference
object, then it is removed from the set.
clazz
is not null
, the set is
further reduced to those services that 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.
ServiceReference
objects is
returned.
getAllServiceReferences
in interface BundleContext
clazz
- The class name with which the service was registered or
null
for all services.filter
- The filter criteria.
ServiceReference
objects or
null
if no services are registered which satisfy
the search.
InvalidSyntaxException
- If filter
contains an
invalid filter string that cannot be parsed.public ServiceReference getServiceReference(java.lang.String clazz)
ServiceReferenceImpl
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 ServiceReferenceImpl
is returned.
getServiceReference
in interface BundleContext
clazz
- The class name which the service must implement.
ServiceReferenceImpl
object, or null
if no services are registered which implement the named class.getServiceReferences(java.lang.String, java.lang.String)
public java.lang.Object getService(ServiceReference reference)
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:
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
reference
- A reference to the service whose service object is desired.
null
if the service is not registered.
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.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
.
java.lang.IllegalStateException
- If the bundle context has stopped.getService(org.osgi.framework.ServiceReference)
,
ServiceFactory
public java.io.File getDataFile(java.lang.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.
java.lang.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 start
BundleException
protected void stop() throws BundleException
BundleException
- if
the bundle has a class that implements the BundleActivator interface,
and the BundleActivator.stop() method failedprotected ServiceReference[] getRegisteredServices()
ServiceReference
s for the services
registered by this bundle
or null
if the bundle has no registered
services.
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.
ServiceReference
or null
.
java.lang.IllegalStateException
- If the
bundle has been uninstalled.ServiceRegistrationImpl
,
ServiceReferenceImpl
protected ServiceReferenceImpl[] getServicesInUse()
ServiceReferenceImpl
s for the
services this bundle is using,
or null
if the bundle is not using any services.
A bundle is considered to be using a service if the bundle's
use count for the service is greater than zero.
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.
ServiceReferenceImpl
or null
.
java.lang.IllegalStateException
- If the
bundle has been uninstalled.ServiceReferenceImpl
public void dispatchEvent(java.lang.Object originalListener, java.lang.Object l, int action, java.lang.Object object)
dispatchEvent
in interface EventDispatcher
originalListener
- listener object registered under.l
- listener to call (may be filtered).action
- Event class typeobject
- Event objectprotected boolean hasListenServicePermission(ServiceEvent event)
public Filter createFilter(java.lang.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)
protected void checkValid()
java.lang.IllegalStateException
- If the context bundle has stopped.protected boolean isValid()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |