Returns an array of 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:
If the specified class name, 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 Constants#OBJECTCLASS objectClass
property.
If the specified filter is not null, the filter
expression must match the service.
If the Java Runtime Environment supports permissions, the caller must
have ServicePermission with the GET action for at least
one of the class names under which the service was registered.
The class name with which the service was registered or
null for all services.
The filter expression or null for all services.
An array of 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.
IllegalStateException If this BundleContext is no longer valid.
1.3
Returns the Bundle object associated with this
BundleContext. This bundle is called the context bundle.
The Bundle object associated with this
BundleContext.
IllegalStateException If this BundleContext is no longer valid.
Returns the bundle with the specified identifier.
The identifier of the bundle to retrieve.
A Bundle object or null if the identifier does
not match any installed bundle.
Returns the bundle with the specified location.
The location of the bundle to retrieve.
A Bundle object or null if the location does not
match any installed bundle.
1.6
Returns a list of all installed bundles.
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.
An array of Bundle objects, one object per installed
bundle.
Creates a 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.
A relative name to the file to be accessed.
A File object that represents the requested file or
null if the platform does not have file system support.
IllegalStateException If this BundleContext is no longer valid.
Returns the value of the specified property. If the key is not found in
the Framework properties, the system properties are then searched. The
method returns null if the property is not found.
All bundles must have permission to read properties whose names start with "org.osgi.".
The name of the requested property.
The value of the requested property, or null if the
property is undefined.
SecurityException If the caller does not have the appropriate
PropertyPermission to read the property, and the Java
Runtime Environment supports permissions.
Returns the service object for the service referenced by the specified
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:
If the service has been unregistered, null is returned.
If the context bundle's use count for the service is currently zero
and the service has Constants#SCOPE_BUNDLE bundle or
Constants#SCOPE_PROTOTYPE 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.
The context bundle's use count for the service is incremented by one.
The service object for the service is returned.
A reference to the service.
A service object for the service associated with
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.
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.
IllegalStateException If this BundleContext is no longer valid.
IllegalArgumentException If the specified
ServiceReference was not created by the same framework
instance as this BundleContext.
Returns the 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 Constants#SCOPE_PROTOTYPE prototype scope.
For services with Constants#SCOPE_SINGLETON singleton or Constants#SCOPE_BUNDLE 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.
A reference to the service.
A ServiceObjects object for the service associated with
the specified reference or null if the service is
not registered.
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.
IllegalStateException If this BundleContext is no longer valid.
IllegalArgumentException If the specified
ServiceReference was not created by the same framework
instance as this BundleContext.
PrototypeServiceFactory
1.8
Returns a 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.
The class name with which the service was registered.
A ServiceReference object, or null if no services
are registered which implement the named class.
IllegalStateException If this BundleContext is no longer valid.
#getServiceReferences(String, String)
Returns an array of 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:
If the specified class name, 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 Constants#OBJECTCLASS objectClass
property.
If the specified filter is not null, the filter
expression must match the service.
If the Java Runtime Environment supports permissions, the caller must
have ServicePermission with the GET action for at least
one of the class names under which the service was registered.
For each class name with which the service was registered, calling
ServiceReference#isAssignableTo(Bundle, String) with the context
bundle and the class name on the service's ServiceReference
object must return true
The class name with which the service was registered or
null for all services.
The filter expression or null for all services.
An array of 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.
IllegalStateException If this BundleContext is no longer valid.
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.
BundleContextmethods allow a bundle to:Subscribe to events published by the Framework. Register service objects with the Framework service registry. Retrieve
ServiceReferencesfrom the Framework service registry. Get and release service objects for a referenced service. Install new bundles in the Framework. Get the list of bundles installed in the Framework. Get the Bundle object for a bundle. CreateFileobjects for files in a persistent storage area provided for the bundle by the Framework.A
BundleContextobject will be created for a bundle when the bundle is started. TheBundleobject associated with aBundleContextobject is called the context bundle.The
BundleContextobject will be passed to the BundleActivator#start(BundleContext) method during activation of the context bundle. The sameBundleContextobject will be passed to the BundleActivator#stop(BundleContext) method when the context bundle is stopped. ABundleContextobject 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
BundleContextobject is only valid during the execution of its context bundle; that is, during the period from when the context bundle is in theSTARTING,STOPPING, andACTIVEbundle states. However, theBundleContextobject becomes invalid after BundleActivator#stop(BundleContext) returns (if the bundle has a Bundle Activator). TheBundleContextobject 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 theSTOPPINGstate but with an invalidBundleContextobject. If theBundleContextobject is used after it has become invalid, anIllegalStateExceptionmust be thrown. TheBundleContextobject must never be reused after its context bundle is stopped.Two
BundleContextobjects are equal if they both refer to the same execution context of a bundle. The Framework is the only entity that can createBundleContextobjects and they are only valid within the Framework that created them.A Bundle can be Bundle#adapt(Class) adapted to its
BundleContext. In order for this to succeed, the caller must have the appropriateAdminPermission[bundle,CONTEXT]if the Java Runtime Environment supports permissions.Thread Safe
Author
$Id: 6c43d322b8ea2137c094ce10e1f33e9c54519dd6 $