public class ServiceRegistry extends Object
Modifier and Type | Field and Description |
---|---|
static int |
SERVICEEVENT |
Constructor and Description |
---|
ServiceRegistry(Framework framework)
Initializes the internal data structures of this ServiceRegistry.
|
Modifier and Type | Method and Description |
---|---|
void |
addServiceListener(BundleContextImpl context,
ServiceListener listener,
String filter)
Add a new Service Listener for a bundle.
|
ServiceReferenceImpl<?>[] |
getRegisteredServices(BundleContextImpl context)
Returns this bundle's
ServiceReference list for all
services it has registered or null if this bundle has no
registered services. |
Object |
getService(BundleContextImpl context,
ServiceReferenceImpl<?> reference)
Returns the specified service object for a service.
|
ServiceReferenceImpl<?> |
getServiceReference(BundleContextImpl context,
String clazz)
Returns a
ServiceReference object for a service that
implements and was registered under the specified class. |
ServiceReferenceImpl<?>[] |
getServiceReferences(BundleContextImpl context,
String clazz,
String filterstring,
boolean allservices)
This method performs the same function as calling
getServiceReferences(BundleContextImpl, String, String, boolean, boolean) with a
true callHooks value. |
ServiceReferenceImpl<?>[] |
getServiceReferences(BundleContextImpl context,
String clazz,
String filterstring,
boolean allservices,
boolean callHooks)
Returns an array of
ServiceReferenceImpl objects. |
ServiceReferenceImpl<?>[] |
getServicesInUse(BundleContextImpl context)
Returns this bundle's
ServiceReference list for all
services it is using or returns null if this bundle is not
using any services. |
void |
notifyHooksPrivileged(HookContext hookContext)
Calls all hook services of the type specified by the hook context.
|
void |
publishServiceEvent(ServiceEvent event)
Deliver a ServiceEvent.
|
ServiceRegistrationImpl<?> |
registerService(BundleContextImpl context,
String[] clazzes,
Object service,
Dictionary<String,?> properties)
Registers the specified service object with the specified properties
under the specified class names into the Framework.
|
void |
releaseServicesInUse(BundleContextImpl context)
Called when the BundleContext is closing to unget all services
currently used by the bundle.
|
void |
removeAllServiceListeners(BundleContextImpl context)
Remove all Service Listener for a bundle.
|
void |
removeServiceListener(BundleContextImpl context,
ServiceListener listener)
Remove a Service Listener for a bundle.
|
boolean |
ungetService(BundleContextImpl context,
ServiceReferenceImpl<?> reference)
Releases the service object referenced by the specified
ServiceReference object. |
void |
unregisterServices(BundleContextImpl context)
Called when the BundleContext is closing to unregister all services
currently registered by the bundle.
|
public static final int SERVICEEVENT
public ServiceRegistry(Framework framework)
public ServiceRegistrationImpl<?> registerService(BundleContextImpl context, String[] clazzes, Object service, Dictionary<String,?> properties)
ServiceRegistrationImpl
object is returned. The
ServiceRegistrationImpl
object is for the private use of the
bundle registering the service and should not be shared with other
bundles. The registering bundle is defined to be the context bundle.
Other bundles can locate the service by using either the
getServiceReferences(org.eclipse.osgi.framework.internal.core.BundleContextImpl, java.lang.String, java.lang.String, boolean, boolean)
or getServiceReference(org.eclipse.osgi.framework.internal.core.BundleContextImpl, 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 fired.
ServiceRegistration
object for this registration is
returned.
context
- The BundleContext of the registering bundle.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<java.lang.String, ?>)
method must be called.
The set of properties may be null
if the service
has no properties.ServiceRegistrationImpl
object for use by the bundle
registering the service to update the service's properties or to
unregister the service.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.
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.IllegalStateException
- If this BundleContext is no
longer valid.ServiceRegistration
,
ServiceFactory
public ServiceReferenceImpl<?>[] getServiceReferences(BundleContextImpl context, String clazz, String filterstring, boolean allservices, boolean callHooks) throws InvalidSyntaxException
ServiceReferenceImpl
objects. The returned
array of ServiceReferenceImpl
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
ServiceReferenceImpl
objects:
null
, the filter string
is parsed and the set ServiceReferenceImpl
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.
ServiceReferenceImpl
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 ServiceReferenceImpl
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 ServiceReferenceImpl
object, if any call to
ServiceReference.isAssignableTo(Bundle, String)
returns
false
, then it is removed from the set of
ServiceReferenceImpl
objects.
ServiceReferenceImpl
objects is
returned.
context
- The BundleContext of the requesting bundle.clazz
- The class name with which the service was registered or
null
for all services.filterstring
- The filter criteria.allservices
- True if the bundle called getAllServiceReferences.callHooks
- True if the references should be filtered using service find hooks.ServiceReferenceImpl
objects or
null
if no services are registered which satisfy
the search.InvalidSyntaxException
- If filter
contains an
invalid filter string that cannot be parsed.IllegalStateException
- If this BundleContext is no
longer valid.public ServiceReferenceImpl<?>[] getServiceReferences(BundleContextImpl context, String clazz, String filterstring, boolean allservices) throws InvalidSyntaxException
getServiceReferences(BundleContextImpl, String, String, boolean, boolean)
with a
true
callHooks value.context
- The BundleContext of the requesting bundle.clazz
- The class name with which the service was registered or
null
for all services.filterstring
- The filter criteria.allservices
- True if the bundle called getAllServiceReferences.ServiceReferenceImpl
objects or
null
if no services are registered which satisfy
the search.InvalidSyntaxException
- If filter
contains an
invalid filter string that cannot be parsed.IllegalStateException
- If this BundleContext is no
longer valid.public ServiceReferenceImpl<?> getServiceReference(BundleContextImpl context, 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
BundleContext.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.
context
- The BundleContext of the requesting bundle.clazz
- The class name with which the service was registered.ServiceReference
object, or null
if no services are registered which implement the named class.IllegalStateException
- If this BundleContext is no
longer valid.public Object getService(BundleContextImpl context, ServiceReferenceImpl<?> 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(BundleContextImpl, ServiceReferenceImpl)
the context bundle's use count for
that service is incremented by one. Each time the service is released by
ungetService(BundleContextImpl, ServiceReferenceImpl)
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
containing a ServiceException
describing the error is fired.
context
- The BundleContext of the requesting bundle.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.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.ungetService(BundleContextImpl, ServiceReferenceImpl)
,
ServiceFactory
public boolean ungetService(BundleContextImpl context, ServiceReferenceImpl<?> 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.
context
- The BundleContext of the requesting bundle.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.IllegalStateException
- If this BundleContext is no
longer valid.getService(org.eclipse.osgi.framework.internal.core.BundleContextImpl, org.eclipse.osgi.internal.serviceregistry.ServiceReferenceImpl<?>)
,
ServiceFactory
public ServiceReferenceImpl<?>[] getRegisteredServices(BundleContextImpl context)
ServiceReference
list for all
services it has registered or null
if this bundle has no
registered services.
If the Java runtime supports permissions, a ServiceReference
object to a service is included in the returned list only if the caller
has the ServicePermission
to get the service using at
least one of the named classes the service was registered under.
The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.
context
- The BundleContext of the requesting bundle.ServiceReference
objects or
null
.IllegalStateException
- If this bundle has been
uninstalled.ServiceRegistration
,
ServiceReference
,
ServicePermission
public ServiceReferenceImpl<?>[] getServicesInUse(BundleContextImpl context)
ServiceReference
list for all
services it is using or returns null
if this bundle is not
using any services. A bundle is considered to be using a service if its
use count for that service is greater than zero.
If the Java Runtime Environment supports permissions, a
ServiceReference
object to a service is included in the
returned list only if the caller has the ServicePermission
to get the service using at least one of the named classes the service
was registered under.
The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.
context
- The BundleContext of the requesting bundle.ServiceReference
objects or
null
.IllegalStateException
- If this bundle has been
uninstalled.ServiceReference
,
ServicePermission
public void unregisterServices(BundleContextImpl context)
context
- The BundleContext of the closing bundle.public void releaseServicesInUse(BundleContextImpl context)
context
- The BundleContext of the closing bundle.public void addServiceListener(BundleContextImpl context, ServiceListener listener, String filter) throws InvalidSyntaxException
context
- Context of bundle adding listener.listener
- Service Listener to be added.filter
- Filter string for listener or null.InvalidSyntaxException
- If the filter string is invalid.public void removeServiceListener(BundleContextImpl context, ServiceListener listener)
context
- Context of bundle removing listener.listener
- Service Listener to be removed.public void removeAllServiceListeners(BundleContextImpl context)
context
- Context of bundle removing all listeners.public void publishServiceEvent(ServiceEvent event)
event
- The ServiceEvent to deliver.public void notifyHooksPrivileged(HookContext hookContext)
hookContext
- Context to use when calling the hook services.Copyright © 2007–2018 The Apache Software Foundation. All rights reserved.