org.eclipse.osgi.internal.serviceregistry
Class ServiceRegistry

java.lang.Object
  org.eclipse.osgi.internal.serviceregistry.ServiceRegistry

public class ServiceRegistry
extends java.lang.Object

The Service Registry. This class is the main control point for service layer operations in the framework.

Field Summary

static int

SERVICEEVENT

Constructor Summary

ServiceRegistry(Framework framework)
Initializes the internal data structures of this ServiceRegistry.

Method Summary

void	addServiceListener(BundleContextImpl context, ServiceListener listener, java.lang.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.
java.lang.Object	getService(BundleContextImpl context, ServiceReferenceImpl<?> reference) Returns the specified service object for a service.
ServiceReferenceImpl<?>	getServiceReference(BundleContextImpl context, java.lang.String clazz) Returns a ServiceReference object for a service that implements and was registered under the specified class.
ServiceReferenceImpl<?>[]	getServiceReferences(BundleContextImpl context, java.lang.String clazz, java.lang.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, java.lang.String clazz, java.lang.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, 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.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SERVICEEVENT

public static final int SERVICEEVENT

See Also:

Constant Field Values

Constructor Detail

ServiceRegistry

public ServiceRegistry(Framework framework)

Initializes the internal data structures of this ServiceRegistry.

Method Detail

registerService

public ServiceRegistrationImpl<?> registerService(BundleContextImpl context,
                                                  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. A 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:

1. If service is not a ServiceFactory, an IllegalArgumentException is thrown if service is not an instanceof all the classes named.
2. The Framework adds these service properties to the specified 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.
3. The service is added to the Framework service registry and may now be used by other bundles.
4. A service event of type ServiceEvent.REGISTERED is fired.
5. A ServiceRegistration object for this registration is returned.

Parameters:

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) method must be called. The set of properties may be null if the service has no properties.

Returns:

A ServiceRegistrationImpl object for use by the bundle registering the service to update the service's properties or to unregister the service.

Throws:

java.lang.IllegalArgumentException - If one of the following is true:

• 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.

See Also:

ServiceRegistration, ServiceFactory

getServiceReferences

public ServiceReferenceImpl<?>[] getServiceReferences(BundleContextImpl context,
                                                      java.lang.String clazz,
                                                      java.lang.String filterstring,
                                                      boolean allservices,
                                                      boolean callHooks)
                                               throws InvalidSyntaxException

Returns an array of 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:

1. If the filter string is not 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.
2. If the Java Runtime Environment supports permissions, the set of 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.
3. If 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.
4. The set is reduced one final time by cycling through each 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.
5. An array of the remaining ServiceReferenceImpl objects is returned.

Parameters:

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.

Returns:

An array of ServiceReferenceImpl objects or null if no services are registered which satisfy the search.

Throws:

InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.

java.lang.IllegalStateException - If this BundleContext is no longer valid.

getServiceReferences

public ServiceReferenceImpl<?>[] getServiceReferences(BundleContextImpl context,
                                                      java.lang.String clazz,
                                                      java.lang.String filterstring,
                                                      boolean allservices)
                                               throws InvalidSyntaxException

This method performs the same function as calling getServiceReferences(BundleContextImpl, String, String, boolean, boolean) with a true callHooks value.

Parameters:

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.

Returns:

An array of ServiceReferenceImpl objects or null if no services are registered which satisfy the search.

Throws:

InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.

java.lang.IllegalStateException - If this BundleContext is no longer valid.

getServiceReference

public ServiceReferenceImpl<?> getServiceReference(BundleContextImpl context,
                                                   java.lang.String clazz)

Returns a 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.

Parameters:

context - The BundleContext of the requesting bundle.

clazz - The class name with which the service was registered.

Returns:

A ServiceReference object, or null if no services are registered which implement the named class.

Throws:

java.lang.IllegalStateException - If this BundleContext is no longer valid.

getService

public java.lang.Object getService(BundleContextImpl context,
                                   ServiceReferenceImpl<?> reference)

Returns the specified service object for a service.

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:

1. If the service has been unregistered, null is returned.
2. The context bundle's use count for this service is incremented by one.
3. If the context bundle's use count for the service is currently one and the service was registered with an object implementing the 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.
   If the service object returned by the 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.
4. The service object for the service is returned.

Parameters:

context - The BundleContext of the requesting bundle.

reference - A reference to the service.

Returns:

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.

Throws:

java.lang.SecurityException - If the caller does not have the ServicePermission to get the service using at least one of the named classes the service was registered under and the Java Runtime Environment supports permissions.

java.lang.IllegalStateException - If this BundleContext is no longer valid.

See Also:

ungetService(BundleContextImpl, ServiceReferenceImpl), ServiceFactory

ungetService

public boolean ungetService(BundleContextImpl context,
                            ServiceReferenceImpl<?> reference)

Releases the service object referenced by the specified 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:

1. If the context bundle's use count for the service is zero or the service has been unregistered, false is returned.
2. The context bundle's use count for this service is decremented by one.
3. If the context bundle's use count for the service is currently zero and the service was registered with a ServiceFactory object, the ServiceFactory.ungetService(Bundle, ServiceRegistration, Object) method is called to release the service object for the context bundle.
4. true is returned.

Parameters:

context - The BundleContext of the requesting bundle.

reference - A reference to the service to be released.

Returns:

false if the context bundle's use count for the service is zero or if the service has been unregistered; true otherwise.

Throws:

java.lang.IllegalStateException - If this BundleContext is no longer valid.

See Also:

getService(org.eclipse.osgi.framework.internal.core.BundleContextImpl, org.eclipse.osgi.internal.serviceregistry.ServiceReferenceImpl), ServiceFactory

getRegisteredServices

public 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.

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.

Parameters:

context - The BundleContext of the requesting bundle.

Returns:

An array of ServiceReference objects or null.

Throws:

java.lang.IllegalStateException - If this bundle has been uninstalled.

See Also:

ServiceRegistration, ServiceReference, ServicePermission

getServicesInUse

public 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. 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.

Parameters:

context - The BundleContext of the requesting bundle.

Returns:

An array of ServiceReference objects or null.

Throws:

java.lang.IllegalStateException - If this bundle has been uninstalled.

See Also:

ServiceReference, ServicePermission

unregisterServices

public void unregisterServices(BundleContextImpl context)

Called when the BundleContext is closing to unregister all services currently registered by the bundle.

Parameters:

context - The BundleContext of the closing bundle.

releaseServicesInUse

public void releaseServicesInUse(BundleContextImpl context)

Called when the BundleContext is closing to unget all services currently used by the bundle.

Parameters:

context - The BundleContext of the closing bundle.

addServiceListener

public void addServiceListener(BundleContextImpl context,
                               ServiceListener listener,
                               java.lang.String filter)
                        throws InvalidSyntaxException

Add a new Service Listener for a bundle.

Parameters:

context - Context of bundle adding listener.

listener - Service Listener to be added.

filter - Filter string for listener or null.

Throws:

InvalidSyntaxException - If the filter string is invalid.

removeServiceListener

public void removeServiceListener(BundleContextImpl context,
                                  ServiceListener listener)

Remove a Service Listener for a bundle.

Parameters:

context - Context of bundle removing listener.

listener - Service Listener to be removed.

removeAllServiceListeners

public void removeAllServiceListeners(BundleContextImpl context)

Remove all Service Listener for a bundle.

Parameters:

context - Context of bundle removing all listeners.

publishServiceEvent

public void publishServiceEvent(ServiceEvent event)

Deliver a ServiceEvent.

Parameters:

event - The ServiceEvent to deliver.

notifyHooksPrivileged

public void notifyHooksPrivileged(HookContext hookContext)

Calls all hook services of the type specified by the hook context.

Parameters:

hookContext - Context to use when calling the hook services.