org.osgi.framework
@ProviderType public interface BundleContext extends BundleReference
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 for a bundle when the bundle
is started. The Bundle object associated with a BundleContext
object is called the context bundle.
The BundleContext object will be passed to the
BundleActivator.start(BundleContext) method during activation of the
context bundle. The same BundleContext object will be passed to the
BundleActivator.stop(BundleContext) method when the context bundle is
stopped. 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 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.
However, the BundleContext object becomes invalid after
BundleActivator.stop(BundleContext) returns (if the bundle has a
Bundle Activator). The BundleContext object becomes invalid before
disposing of any remaining registered services and releasing any remaining
services in use. Since those activities can result in other bundles being
called (for example, ServiceListeners for
ServiceEvent.UNREGISTERING events and ServiceFactorys for
unget operations), those other bundles can observe the stopping bundle in the
STOPPING state but with an invalid BundleContext object. If
the BundleContext object is used after it has become invalid, an
IllegalStateException must be thrown. The BundleContext
object must never be reused after its context bundle is stopped.
Two BundleContext objects are equal if they both refer to the same
execution context of a bundle. The Framework is the only entity that can
create BundleContext objects and they are only valid within the
Framework that created them.
A Bundle can be adapted to its
BundleContext. In order for this to succeed, the caller must have the
appropriate AdminPermission[bundle,CONTEXT] if the Java Runtime
Environment supports permissions.
| Modifier and Type | Method and Description |
|---|---|
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 |
getBundle(java.lang.String location)
Returns the bundle with the specified location.
|
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.
|
<S> S |
getService(ServiceReference<S> reference)
Returns the service object for the service referenced by the specified
ServiceReference object. |
<S> ServiceObjects<S> |
getServiceObjects(ServiceReference<S> reference)
Returns the
ServiceObjects object for the service referenced by
the specified ServiceReference object. |
<S> ServiceReference<S> |
getServiceReference(java.lang.Class<S> clazz)
Returns a
ServiceReference object for a service that implements
and was registered under the name of the specified class. |
ServiceReference<?> |
getServiceReference(java.lang.String clazz)
Returns a
ServiceReference object for a service that implements
and was registered under the specified class. |
<S> java.util.Collection<ServiceReference<S>> |
getServiceReferences(java.lang.Class<S> clazz,
java.lang.String filter)
Returns a collection of
ServiceReference objects. |
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 identifier. |
Bundle |
installBundle(java.lang.String location,
java.io.InputStream input)
Installs a bundle from the specified
InputStream object. |
<S> ServiceRegistration<S> |
registerService(java.lang.Class<S> clazz,
S service,
java.util.Dictionary<java.lang.String,?> properties)
Registers the specified service object with the specified properties
under the name of the specified class with the Framework.
|
<S> ServiceRegistration<S> |
registerService(java.lang.Class<S> clazz,
ServiceFactory<S> factory,
java.util.Dictionary<java.lang.String,?> properties)
Registers the specified service factory object with the specified
properties under the name of the specified class with the Framework.
|
ServiceRegistration<?> |
registerService(java.lang.String[] clazzes,
java.lang.Object service,
java.util.Dictionary<java.lang.String,?> 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<java.lang.String,?> 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 for the service referenced by the specified
ServiceReference object. |
java.lang.String getProperty(java.lang.String key)
null if the property is not found.
All bundles must have permission to read properties whose names start with "org.osgi.".
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.Bundle getBundle()
Bundle object associated with this
BundleContext. This bundle is called the context bundle.getBundle in interface BundleReferenceBundle object associated with this
BundleContext.java.lang.IllegalStateException - If this BundleContext is no longer valid.Bundle installBundle(java.lang.String location, java.io.InputStream input) throws BundleException
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
}.location - The location identifier of the bundle to install.input - 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.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.Bundle installBundle(java.lang.String location) throws BundleException
location identifier.
This method performs the same function as calling
installBundle(String,InputStream) with the specified
location identifier and a null InputStream.
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.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.installBundle(String, InputStream)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.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.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,
ServicePermissionvoid 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)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.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.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.BundleEvent,
BundleListenervoid 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.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.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,
FrameworkListenervoid 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.ServiceRegistration<?> registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary<java.lang.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. Other bundles can
locate the service by using one of the
getServiceReferences(Class, String),
getServiceReferences(String, String),
getServiceReference(Class) or
getServiceReference(String) methods.
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 does not implement ServiceFactory, an
IllegalArgumentException is thrown if service is not an
instanceof all the specified class names.Dictionary (which may be
null):
Constants.SERVICE_ID identifying the
registration number of the serviceConstants.OBJECTCLASS containing all the
specified classes.Constants.SERVICE_SCOPE identifying the
scope of the service.Constants.SERVICE_BUNDLEID identifying the
the context bundle.Dictionary will be
ignored.ServiceEvent.REGISTERED is fired.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 an object implementing
ServiceFactory.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(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 does
not implement ServiceFactory and is not an instance of
all the specified classes.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,
PrototypeServiceFactory,
ServiceFactoryServiceRegistration<?> registerService(java.lang.String clazz, java.lang.Object service, java.util.Dictionary<java.lang.String,?> properties)
This method is otherwise identical to
registerService(String[], Object, 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 string, rather
than just a single string.
clazz - The class name under which the service can be located.service - The service object or an object implementing
ServiceFactory.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.java.lang.IllegalStateException - If this BundleContext is no longer valid.registerService(String[], Object, Dictionary)<S> ServiceRegistration<S> registerService(java.lang.Class<S> clazz, S service, java.util.Dictionary<java.lang.String,?> properties)
This method is otherwise identical to
registerService(String, Object, Dictionary) and is provided to
return a type safe ServiceRegistration.
S - Type of Service.clazz - The class under whose name the service can be located.service - The service object or an object implementing
ServiceFactory.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.java.lang.IllegalStateException - If this BundleContext is no longer valid.registerService(String, Object, Dictionary)<S> ServiceRegistration<S> registerService(java.lang.Class<S> clazz, ServiceFactory<S> factory, java.util.Dictionary<java.lang.String,?> properties)
This method is otherwise identical to
registerService(Class, Object, Dictionary) and is provided to
return a type safe ServiceRegistration when registering a
ServiceFactory.
S - Type of Service.clazz - The class under whose name the service can be located.factory - The 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.java.lang.IllegalStateException - If this BundleContext is no longer valid.registerService(Class, Object, Dictionary)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
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 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.ServiceReference.isAssignableTo(Bundle, String) with the context
bundle and the class name on the service's ServiceReference
object must return trueclazz - 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.java.lang.IllegalStateException - If this BundleContext is no longer valid.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
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.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.java.lang.IllegalStateException - If this BundleContext is no longer valid.ServiceReference<?> getServiceReference(java.lang.String clazz)
ServiceReference object for a service that implements
and was registered under 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
getServiceReferences(String, String) with a null filter
expression and then finding the reference with the highest priority. 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 priority is
selected. This priority is defined as the service reference 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)<S> ServiceReference<S> getServiceReference(java.lang.Class<S> clazz)
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
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.
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.java.lang.IllegalStateException - If this BundleContext is no longer valid.getServiceReferences(Class, String)<S> java.util.Collection<ServiceReference<S>> getServiceReferences(java.lang.Class<S> clazz, java.lang.String filter) throws InvalidSyntaxException
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 trueS - 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.java.lang.IllegalStateException - If this BundleContext is no longer valid.<S> S getService(ServiceReference<S> reference)
ServiceReference object.
A bundle's use of a service object obtained from this method is tracked
by the bundle's use count of that service. Each time the service object
is returned by getService(ServiceReference) the context bundle's
use count for the service is incremented by one. Each time the service
object is released by ungetService(ServiceReference) the context
bundle's use count for the service is decremented by one.
When a bundle's use count for the service drops to zero, the bundle should no longer use the service object.
This method will always return null when the service associated
with the specified reference has been unregistered.
The following steps are required to get the service object:
null is returned.bundle or
prototype scope, the
ServiceFactory.getService(Bundle, ServiceRegistration) method is
called to supply the service object for the context bundle. If the
service object returned by the ServiceFactory object is
null, not an instanceof all the classes named when the
service was registered or the ServiceFactory object throws an
exception or will be recursively called for the context bundle,
null is returned and a Framework event of type
FrameworkEvent.ERROR containing a ServiceException
describing the error is fired. The supplied 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 service object for the
context bundle will return the cached service object.S - Type of Service.reference - A reference to the service.reference or null if the service is not
registered, the service object returned by a
ServiceFactory does not implement the classes under which
it was registered or the ServiceFactory threw an
exception.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.java.lang.IllegalArgumentException - If the specified
ServiceReference was not created by the same framework
instance as this BundleContext.ungetService(ServiceReference),
ServiceFactoryboolean 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 object must 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 release the service object:
false is returned.bundle or
prototype scope, 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.java.lang.IllegalArgumentException - If the specified
ServiceReference was not created by the same framework
instance as this BundleContext.getService(ServiceReference),
ServiceFactory<S> ServiceObjects<S> getServiceObjects(ServiceReference<S> reference)
ServiceObjects object for the service referenced by
the specified ServiceReference object.
The ServiceObjects object can be used to obtain multiple service
objects for services with prototype
scope.
For services with singleton or
bundle scope, the
ServiceObjects.getService() method behaves the same as the
getService(ServiceReference) method and the
ServiceObjects.ungetService(Object) method behaves the same as
the ungetService(ServiceReference) method. That is, only one,
use-counted service object is available from the ServiceObjects
object.
This method will always return null when the service associated
with the specified reference has been unregistered.
S - Type of Service.reference - A reference to the service.ServiceObjects object for the service associated with
the specified reference or null if the service is
not registered.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.java.lang.IllegalArgumentException - If the specified
ServiceReference was not created by the same framework
instance as this BundleContext.PrototypeServiceFactoryjava.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.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.FrameworkUtil.createFilter(String)Bundle getBundle(java.lang.String location)
location - The location of the bundle to retrieve.Bundle object or null if the location does not
match any installed bundle.