org.osgi.framework
public interface BundleContext
BundleContext
methods allow a bundle to:
ServiceReferences
from the Framework service
registry.
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 associated with this context when it is started using the
BundleActivator method. The same BundleContext
object will be passed to the bundle associated with this context when it is
stopped using the BundleActivator method. A
BundleContext
object is generally for the private use of its
associated bundle and is not meant to be shared with other bundles in the
OSGi environment.
The Bundle
object associated with a BundleContext
object is called the context bundle.
The BundleContext
object is only valid during the execution of
its context bundle; that is, during the period from when the context bundle
is in the STARTING
, STOPPING
, and
ACTIVE
bundle states. If the BundleContext
object is used subsequently, an IllegalStateException
must be
thrown. The BundleContext
object must never be reused after
its context bundle is stopped.
The Framework is the only entity that can create BundleContext
objects and they are only valid within the Framework that created them.
Version: $Revision: 1.22 $
UNKNOWN:
Method Summary | |
---|---|
void | addBundleListener(BundleListener listener)
Adds the specified BundleListener object to the context
bundle's list of listeners if not already present. |
void | addFrameworkListener(FrameworkListener listener)
Adds the specified FrameworkListener object to the context
bundle's list of listeners if not already present. |
void | addServiceListener(ServiceListener listener, String filter)
Adds the specified ServiceListener object with the
specified filter to the context bundle's list of
listeners. |
void | addServiceListener(ServiceListener listener)
Adds the specified ServiceListener object to the context
bundle's list of listeners.
|
Filter | createFilter(String filter)
Creates a Filter object. |
ServiceReference[] | getAllServiceReferences(String clazz, String filter)
Returns an array of ServiceReference objects. |
Bundle | getBundle()
Returns the Bundle object associated with this
BundleContext . |
Bundle | getBundle(long id)
Returns the bundle with the specified identifier.
|
Bundle[] | getBundles()
Returns 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. |
String | getProperty(String key)
Returns the value of the specified property. |
Object | getService(ServiceReference reference)
Returns the specified service object for a service.
|
ServiceReference | getServiceReference(String clazz)
Returns a ServiceReference object for a service that
implements and was registered under the specified class.
|
ServiceReference[] | getServiceReferences(String clazz, String filter)
Returns an array of ServiceReference objects. |
Bundle | installBundle(String location)
Installs a bundle from the specified location string. |
Bundle | installBundle(String location, InputStream input)
Installs a bundle from the specified InputStream object.
|
ServiceRegistration | registerService(String[] clazzes, Object service, Dictionary properties)
Registers the specified service object with the specified properties
under the specified class names into the Framework. |
ServiceRegistration | registerService(String clazz, Object service, Dictionary properties)
Registers the specified service object with the specified properties
under the specified class name with the Framework.
|
void | removeBundleListener(BundleListener listener)
Removes the specified BundleListener object from the
context bundle's list of listeners.
|
void | removeFrameworkListener(FrameworkListener listener)
Removes the specified FrameworkListener object from the
context bundle's list of listeners.
|
void | removeServiceListener(ServiceListener listener)
Removes the specified ServiceListener object from the
context bundle's list of listeners.
|
boolean | ungetService(ServiceReference reference)
Releases the service object referenced by the specified
ServiceReference object. |
BundleListener
object to the context
bundle's list of listeners if not already present. BundleListener objects
are notified when a bundle has a lifecycle state change.
If the context bundle's list of listeners already contains a listener
l
such that (l==listener)
, this method
does nothing.
Parameters: listener The BundleListener
to be added.
Throws: java.lang.IllegalStateException If this BundleContext is no
longer valid. java.lang.SecurityException If listener is a
SynchronousBundleListener
and the caller does not
have the appropriate AdminPermission[context bundle,LISTENER]
,
and the Java Runtime Environment supports permissions.
See Also: BundleEvent BundleListener
FrameworkListener
object to the context
bundle's list of listeners if not already present. FrameworkListeners are
notified of general Framework events.
If the context bundle's list of listeners already contains a listener
l
such that (l==listener)
, this method
does nothing.
Parameters: listener The FrameworkListener
object to be added.
Throws: java.lang.IllegalStateException If this BundleContext is no longer valid.
See Also: FrameworkEvent FrameworkListener
ServiceListener
object with the
specified filter
to the context bundle's list of
listeners. See Filter for a description of the filter syntax.
ServiceListener
objects are notified when a service has a
lifecycle state change.
If the context bundle's list of listeners already contains a listener
l
such that (l==listener)
, then this
method replaces that listener's filter (which may be null
)
with the specified one (which may be null
).
The listener is called if the filter criteria is met. To filter based
upon the class of the service, the filter should reference the
OBJECTCLASS property. If filter
is
null
, all services are considered to match the filter.
When using a filter
, it is possible that the
ServiceEvent
s for the complete lifecycle of a service
will not be delivered to the listener. For example, if the
filter
only matches when the property x
has
the value 1
, the listener will not be called if the
service is registered with the property x
not set to the
value 1
. Subsequently, when the service is modified
setting property x
to the value 1
, the
filter will match and the listener will be called with a
ServiceEvent
of type MODIFIED
. Thus, the
listener will not be called with a ServiceEvent
of type
REGISTERED
.
If the Java Runtime Environment supports permissions, the
ServiceListener
object will be notified of a service event
only if the bundle that is registering it has the
ServicePermission
to get the service using at least one of
the named classes the service was registered under.
Parameters: listener The ServiceListener
object to be added. filter The filter criteria.
Throws: InvalidSyntaxException If filter
contains an
invalid filter string that cannot be parsed. java.lang.IllegalStateException If this BundleContext is no
longer valid.
See Also: ServiceEvent ServiceListener ServicePermission
ServiceListener
object to the context
bundle's list of listeners.
This method is the same as calling
BundleContext.addServiceListener(ServiceListener listener,
String filter)
with filter
set to null
.
Parameters: listener The ServiceListener
object to be added.
Throws: java.lang.IllegalStateException If this BundleContext is no longer valid.
See Also: BundleContext
Filter
object. This Filter
object
may be used to match a ServiceReference
object or a
Dictionary
object.
If the filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.
Parameters: filter The filter string.
Returns: A Filter
object encapsulating the filter string.
Throws: InvalidSyntaxException If filter
contains an
invalid filter string that cannot be parsed. NullPointerException If filter
is null. java.lang.IllegalStateException If this BundleContext is no
longer valid.
Since: 1.1
See Also: "Framework specification for a description of the filter string syntax."
createFilter
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
OBJECTCLASS property.
ServiceReference
objects 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 filter
contains an
invalid filter string that cannot be parsed. java.lang.IllegalStateException If this BundleContext is no
longer valid.
Since: 1.3
Bundle
object associated with this
BundleContext
. This bundle is called the context bundle.
Returns: The Bundle
object associated with this
BundleContext
.
Throws: java.lang.IllegalStateException If this BundleContext is no longer valid.
Parameters: id The identifier of the bundle to retrieve.
Returns: A Bundle
object or null
if the
identifier does not match any installed bundle.
This method returns a list of all bundles installed in the OSGi environment at the time of the call to this method. However, since the Framework is a very dynamic environment, bundles can be installed or uninstalled at anytime.
Returns: An array of Bundle
objects, one object per
installed bundle.
File
object for a file in the persistent storage
area provided for the bundle by the Framework. This method will return
null
if the platform does not have file system support.
A File
object for the base directory of the persistent
storage area provided for the context bundle by the Framework can be
obtained by calling this method with an empty string as
filename
.
If the Java Runtime Environment supports permissions, the Framework will
ensure that the bundle has the java.io.FilePermission
with
actions read
,write
,delete
for all files (recursively) in the persistent storage area provided for
the context bundle.
Parameters: filename 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: java.lang.IllegalStateException If this BundleContext is no longer valid.
null
if the property is not found.
The Framework defines the following standard property keys:
All bundles must have permission to read these properties.
Note: The last four standard properties are used by the
BUNDLE_NATIVECODE Manifest
header's
matching algorithm for selecting native language code.
Parameters: key The name of the requested property.
Returns: The value of the requested property, or null
if
the property is undefined.
Throws: java.lang.SecurityException If the caller does not have the
appropriate PropertyPermission
to read the
property, and the Java Runtime Environment supports permissions.
A bundle's use of a service is tracked by the bundle's use count of that service. Each time a service's service object is returned by getService the context bundle's use count for that service is incremented by one. Each time the service is released by ungetService the context bundle's use count for that service is decremented by one.
When a bundle's use count for a service drops to zero, the bundle should no longer use that service.
This method will always return null
when the service
associated with this reference
has been unregistered.
The following steps are required to get the service object:
null
is
returned.
ServiceFactory
interface, the
ServiceFactory 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
object is not an instanceof
all the classes named when the
service was registered or the ServiceFactory
object throws
an exception, null
is returned and a Framework event of
type ERROR is fired.
Parameters: reference A reference to the service.
Returns: A service object for the service associated with
reference
or null
if the service is
not registered or does not implement the classes under which it
was registered in the case of a ServiceFactory
.
Throws: java.lang.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. java.lang.IllegalStateException If this BundleContext is no
longer valid.
See Also: ungetService ServiceFactory
ServiceReference
object for a service that
implements and was registered under the specified class.
This 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 anytime.
This method is the same as calling
BundleContext with a
null
filter string. 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 SERVICE_RANKING property) is returned.
If there is a tie in ranking, the service with the lowest service ID (as specified in its SERVICE_ID property); that is, the service that was registered first 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.
Throws: java.lang.IllegalStateException If this BundleContext is no longer valid.
See Also: BundleContext
ServiceReference
objects. The returned
array of ServiceReference
objects contains services that
were registered under the specified class, match the specified filter
criteria, and the packages for the class names under which the services
were registered match the context bundle's packages as defined in
ServiceReference.
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
OBJECTCLASS property.
ServiceReference
object and calling
ServiceReference with the context
bundle and each class name under which the ServiceReference
object was registered. For any given ServiceReference
object, if any call to
ServiceReference returns
false
, then it is removed from the set of
ServiceReference
objects.
ServiceReference
objects 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 filter
contains an
invalid filter string that cannot be parsed. java.lang.IllegalStateException If this BundleContext is no
longer valid.
location
as interpreted by the Framework in
an implementation dependent manner.
Every installed bundle is uniquely identified by its location string, typically in the form of a URL.
The following steps are required to install a bundle:
Bundle
object for that bundle is returned.
Bundle-NativeCode
dependencies are
resolved. If this fails, a BundleException
is thrown.
BundleException
is thrown.
BundleException
must be thrown.
INSTALLED
.
Bundle
object for the newly or previously
installed bundle is returned.
getState()
in {INSTALLED
,RESOLVED
}.
Parameters: location The location identifier of the bundle to install.
Returns: The Bundle
object of the installed bundle.
Throws: BundleException If the installation failed. java.lang.SecurityException If the caller does not have the
appropriate AdminPermission[installed bundle,LIFECYCLE]
, and the
Java Runtime Environment supports permissions. java.lang.IllegalStateException If this BundleContext is no
longer valid.
InputStream
object.
This method performs all of the steps listed in
BundleContext.installBundle(String location)
, except that
the bundle's content will be read from the InputStream
object. The location identifier string specified will be used as the
identity of the bundle.
This method must always close the InputStream
object, even
if an exception is thrown.
Parameters: location The location identifier of the bundle to install. input The InputStream
object from which this bundle
will be read.
Returns: The Bundle
object of the installed bundle.
Throws: BundleException If the provided stream cannot be read or the
installation failed. java.lang.SecurityException If the caller does not have the
appropriate AdminPermission[installed bundle,LIFECYCLE]
, and the
Java Runtime Environment supports permissions. java.lang.IllegalStateException If this BundleContext is no
longer valid.
See Also: BundleContext
ServiceRegistration
object is returned. The
ServiceRegistration
object is for the private use of the
bundle registering the service and should not be shared with other
bundles. The registering bundle is defined to be the context bundle.
Other bundles can locate the service by using either the
BundleContext or BundleContext method.
A bundle can register a service object that implements the ServiceFactory interface to have more flexibility in providing service objects to other bundles.
The following steps are required to register a service:
service
is not a ServiceFactory
,
an IllegalArgumentException
is thrown if
service
is not an instanceof
all the
classes named.
Dictionary
(which may be null
): a property
named SERVICE_ID identifying the registration number of
the service and a property named OBJECTCLASS containing
all the specified classes. If any of these properties have already been
specified by the registering bundle, their values will be overwritten by
the Framework.
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 String
objects. See
Constants for a list of standard service property keys.
Changes should not be made to this object after calling this
method. To update the service's properties the
ServiceRegistration method must be called.
The set of properties 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:
java.lang.SecurityException If the caller does not have the
service
is null
.
service
is not a ServiceFactory
object and is not an instance of all the named classes in
clazzes
.
properties
contains case variants of the same
key name.
ServicePermission
to register the service for all
the named classes and the Java Runtime Environment supports
permissions.
java.lang.IllegalStateException If this BundleContext is no
longer valid.
See Also: ServiceRegistration ServiceFactory
This method is otherwise identical to
(java.lang.String[], java.lang.Object,
java.util.Dictionary)
and is provided as a convenience when
service
will only be registered under a single class name.
Note that even in this case the value of the service's
OBJECTCLASS property will be an array of strings,
rather than just a single string.
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.
Throws: java.lang.IllegalStateException If this BundleContext is no longer valid.
See Also: (java.lang.String[], java.lang.Object,
java.util.Dictionary)
BundleListener
object from the
context bundle's list of listeners.
If listener
is not contained in the context bundle's list
of listeners, this method does nothing.
Parameters: listener The BundleListener
object to be removed.
Throws: java.lang.IllegalStateException If this BundleContext is no
longer valid. java.lang.SecurityException If listener is a
SynchronousBundleListener
and the caller does not
have the appropriate AdminPermission[context bundle,LISTENER]
,
and the Java Runtime Environment supports permissions.
FrameworkListener
object from the
context bundle's list of listeners.
If listener
is not contained in the context bundle's list
of listeners, this method does nothing.
Parameters: listener The FrameworkListener
object to be
removed.
Throws: java.lang.IllegalStateException If this BundleContext is no longer valid.
ServiceListener
object from the
context bundle's list of listeners.
If listener
is not contained in this context bundle's list
of listeners, this method does nothing.
Parameters: listener The ServiceListener
to be removed.
Throws: java.lang.IllegalStateException If this BundleContext is no longer valid.
ServiceReference
object. If the context bundle's use count
for the service is zero, this method returns false
.
Otherwise, the context bundle's use count for the service is decremented
by one.
The service'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 required to unget the service object:
false
is returned.
ServiceFactory
object, the
ServiceFactory
method is called to release the service object for the context bundle.
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;
true
otherwise.
Throws: java.lang.IllegalStateException If this BundleContext is no longer valid.
See Also: BundleContext ServiceFactory