org.eclipse.osgi.framework.internal.core
Class ServiceUse

java.lang.Object
  extended by org.eclipse.osgi.framework.internal.core.ServiceUse

public class ServiceUse
extends java.lang.Object

This class represents the use of a service by a bundle. One is created for each service acquired by a bundle. This class manages the calls to ServiceFactory and the bundle's use count.


Field Summary
protected  BundleContextImpl context
          BundleContext associated with this service use
protected  ServiceFactory factory
          ServiceFactory object if the service instance represents a factory, null otherwise
protected  ServiceRegistrationImpl registration
          ServiceDescription of the registered service
protected  java.lang.Object service
          Service object either registered or that returned by ServiceFactory.getService()
protected  int useCount
          bundle's use count for this service
 
Constructor Summary
protected ServiceUse(BundleContextImpl context, ServiceRegistrationImpl registration)
          Constructs a service use encapsulating the service object.
 
Method Summary
protected  java.lang.Object getService()
          Get a service's service object.
protected  void releaseService()
          Release a service's service object.
protected  boolean ungetService()
          Unget a service's service object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

factory

protected ServiceFactory factory
ServiceFactory object if the service instance represents a factory, null otherwise


service

protected java.lang.Object service
Service object either registered or that returned by ServiceFactory.getService()


context

protected BundleContextImpl context
BundleContext associated with this service use


registration

protected ServiceRegistrationImpl registration
ServiceDescription of the registered service


useCount

protected int useCount
bundle's use count for this service

Constructor Detail

ServiceUse

protected ServiceUse(BundleContextImpl context,
                     ServiceRegistrationImpl registration)
Constructs a service use encapsulating the service object. Objects of this class should be constrcuted while holding the registrations lock.

Parameters:
context - bundle getting the service
registration - ServiceRegistration of the service
Method Detail

getService

protected java.lang.Object getService()
Get a service's service object. Retrieves the service object for a service. A bundle's use of a service is tracked by a use count. Each time a service's service object is returned by getService(), the context bundle's use count for the service is incremented by one. Each time the service is release by ungetService(), the context bundle's use count for the service is decremented by one. When a bundle's use count for a service drops to zero, the bundle should no longer use the service.

The following steps are followed to get the service object:

  1. The context bundle's use count for this service is incremented by one.
  2. If the context bundle's use count for the service is now one and the service was registered with a ServiceFactory, the ServiceFactory.getService 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 is not an instanceof all the classes named when the service was registered or the ServiceFactory throws an exception, null is returned and a FrameworkEvent of type FrameworkEvent.ERROR is broadcast.
  3. The service object for the service is returned.

Returns:
A service object for the service associated with this reference.

ungetService

protected boolean ungetService()
Unget a service's service object. Releases the service object for a service. 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 followed 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 now zero and the service was registered with a ServiceFactory, the ServiceFactory.ungetService method is called to release the service object for the context bundle.
  4. true is returned.

Returns:
true if the context bundle's use count for the service is zero otherwise false.

releaseService

protected void releaseService()
Release a service's service object.
  1. The bundle's use count for this service is set to zero.
  2. If the service was registered with a ServiceFactory, the ServiceFactory.ungetService method is called to release the service object for the bundle.