|
OSGi Service Platform Release 4 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
A bundle's execution context within the Framework. The context is used to grant access to other methods so that this bundle can interact with the Framework.
BundleContext
methods allow a bundle to:
ServiceReferences
from the Framework service
registry.
Bundle
object for a bundle.
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.start(org.osgi.framework.BundleContext)
method. The same BundleContext
object will be passed to the bundle associated with this context when it is
stopped using the BundleActivator.stop(org.osgi.framework.BundleContext)
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.
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)
Adds the specified ServiceListener object to the context
bundle's list of listeners. |
void |
addServiceListener(ServiceListener listener,
java.lang.String filter)
Adds the specified ServiceListener object with the specified
filter to the context bundle's list of listeners. |
Filter |
createFilter(java.lang.String filter)
Creates a Filter object. |
ServiceReference[] |
getAllServiceReferences(java.lang.String clazz,
java.lang.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. |
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)
Returns the value of the specified property. |
java.lang.Object |
getService(ServiceReference reference)
Returns the specified service object for a service. |
ServiceReference |
getServiceReference(java.lang.String clazz)
Returns a ServiceReference object for a service that
implements and was registered under the specified class. |
ServiceReference[] |
getServiceReferences(java.lang.String clazz,
java.lang.String filter)
Returns an array of ServiceReference objects. |
Bundle |
installBundle(java.lang.String location)
Installs a bundle from the specified location string. |
Bundle |
installBundle(java.lang.String location,
java.io.InputStream input)
Installs a bundle from the specified InputStream object. |
ServiceRegistration |
registerService(java.lang.String[] clazzes,
java.lang.Object service,
java.util.Dictionary properties)
Registers the specified service object with the specified properties under the specified class names into the Framework. |
ServiceRegistration |
registerService(java.lang.String clazz,
java.lang.Object service,
java.util.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. |
Method Detail |
public java.lang.String getProperty(java.lang.String key)
null
if the property is not found.
The Framework defines the following standard property keys:
Constants.FRAMEWORK_VERSION
- The OSGi Framework version.
Constants.FRAMEWORK_VENDOR
- The Framework implementation
vendor.Constants.FRAMEWORK_LANGUAGE
- The language being used. See
ISO 639 for possible values.Constants.FRAMEWORK_OS_NAME
- The host computer operating
system.Constants.FRAMEWORK_OS_VERSION
- The host computer operating
system version number.Constants.FRAMEWORK_PROCESSOR
- The host computer processor
name.All bundles must have permission to read these properties.
Note: The last four standard properties are used by the
Constants.BUNDLE_NATIVECODE
Manifest
header's matching
algorithm for selecting native language code.
key
- The name of the requested property.
null
if the
property is undefined.
java.lang.SecurityException
- If the caller does not have the
appropriate PropertyPermission
to read the
property, and the Java Runtime Environment supports
permissions.public Bundle getBundle()
Bundle
object associated with this
BundleContext
. This bundle is called the context bundle.
Bundle
object associated with this
BundleContext
.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.public Bundle installBundle(java.lang.String location) throws BundleException
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.
BundleException
is thrown.
Bundle-NativeCode
dependencies are resolved.
If this fails, a BundleException
is thrown.
BundleException
is thrown.
BundleException
must be thrown.
INSTALLED
.
BundleEvent.INSTALLED
is broadcast.
Bundle
object for the newly or previously installed
bundle is returned.
getState()
in {INSTALLED
,RESOLVED
}.
location
- The location identifier of the bundle to install.
Bundle
object of the installed bundle.
BundleException
- If the installation failed.
java.lang.SecurityException
- If the caller does not have the
appropriate AdminPermission
, and the Java Runtime
Environment supports permissions.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.public Bundle installBundle(java.lang.String location, java.io.InputStream input) throws BundleException
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.
location
- The location identifier of the bundle to install.input
- The InputStream
object from which this bundle
will be read.
Bundle
object of the installed bundle.
BundleException
- If the provided stream cannot be read or the
installation failed.
java.lang.SecurityException
- If the caller does not have the
appropriate AdminPermission
, and the Java Runtime
Environment supports permissions.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.installBundle(java.lang.String)
public Bundle getBundle(long id)
id
- The identifier of the bundle to retrieve.
Bundle
object or null
if the identifier
does not match any installed bundle.public Bundle[] getBundles()
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.
Bundle
objects, one object per installed
bundle.public void addServiceListener(ServiceListener listener, java.lang.String filter) throws InvalidSyntaxException
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
Constants.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.
listener
- The ServiceListener
object to be added.filter
- The filter criteria.
InvalidSyntaxException
- If filter
contains an
invalid filter string that cannot be parsed.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.ServiceEvent
,
ServiceListener
,
ServicePermission
public void addServiceListener(ServiceListener listener)
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
.
listener
- The ServiceListener
object to be added.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.addServiceListener(ServiceListener, String)
public void removeServiceListener(ServiceListener listener)
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.
listener
- The ServiceListener
to be removed.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.public void addBundleListener(BundleListener listener)
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.
listener
- The BundleListener
to be added.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.BundleEvent
,
BundleListener
public void removeBundleListener(BundleListener listener)
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.
listener
- The BundleListener
object to be removed.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.public void addFrameworkListener(FrameworkListener listener)
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.
listener
- The FrameworkListener
object to be added.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.FrameworkEvent
,
FrameworkListener
public void removeFrameworkListener(FrameworkListener listener)
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.
listener
- The FrameworkListener
object to be removed.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.public ServiceRegistration registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary 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.
Other bundles can locate the service by using either the
getServiceReferences(java.lang.String, java.lang.String)
or getServiceReference(java.lang.String)
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
Constants.SERVICE_ID
identifying the registration number of the
service and a property named Constants.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.
ServiceEvent.REGISTERED
is
synchronously sent.
ServiceRegistration
object for this registration is
returned.
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 Constants.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.setProperties(java.util.Dictionary)
method must be called.
The set of properties 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.
java.lang.IllegalArgumentException
- If one of the following is
true:
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.
java.lang.SecurityException
- If the caller does not have the
ServicePermission
to register the service for all
the named classes and the Java Runtime Environment supports
permissions.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.ServiceRegistration
,
ServiceFactory
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
service
will only be registered under a single class name.
Note that even in this case the value of the service's
Constants.OBJECTCLASS
property will be an array of strings,
rather than just a single string.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.registerService(java.lang.String[], java.lang.Object,
java.util.Dictionary)
public ServiceReference[] getServiceReferences(java.lang.String clazz, java.lang.String filter) throws InvalidSyntaxException
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.isAssignableTo(Bundle, String)
.
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
object and calling
ServiceReference.isAssignableTo(Bundle, String)
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.isAssignableTo(Bundle, String)
returns
false
, then it is removed from the set of
ServiceReference
objects.
ServiceReference
objects
is returned.
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.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.public ServiceReference[] getAllServiceReferences(java.lang.String clazz, java.lang.String filter) throws InvalidSyntaxException
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.
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.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.public ServiceReference getServiceReference(java.lang.String clazz)
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
getServiceReferences(String, String)
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 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.
clazz
- The class name with which the service was registered.
ServiceReference
object, or null
if no
services are registered which implement the named class.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.getServiceReferences(String, String)
public java.lang.Object getService(ServiceReference reference)
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(ServiceReference)
the context bundle's use count for
that service is incremented by one. Each time the service is released by
ungetService(ServiceReference)
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.getService(Bundle, ServiceRegistration)
method
is called to create a service object for the context bundle. This service
object is cached by the Framework. While the context bundle's use count
for the service is greater than zero, subsequent calls to get the
services's service object for the context bundle will return the cached
service object.
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
FrameworkEvent.ERROR
is broadcast.
reference
- A reference to the service.
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
.
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.ungetService(ServiceReference)
,
ServiceFactory
public boolean ungetService(ServiceReference reference)
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.ungetService(Bundle, ServiceRegistration, Object)
method is called to release the service object for the context bundle.
true
is returned.
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;
true
otherwise.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.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. 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.
filename
- A relative name to the file to be accessed.
File
object that represents the requested file or
null
if the platform does not have file system
support.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.public Filter createFilter(java.lang.String filter) throws InvalidSyntaxException
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.
filter
- The filter string.
Filter
object encapsulating the filter string.
InvalidSyntaxException
- If filter
contains an
invalid filter string that cannot be parsed.
java.lang.NullPointerException
- If filter
is null.
java.lang.IllegalStateException
- If this BundleContext is no
longer valid.
|
OSGi Service Platform Release 4 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |