org.ops4j.pax.servicemanager
Class ServiceManagerImpl

java.lang.Object
  org.ops4j.pax.servicemanager.ServiceManagerImpl

All Implemented Interfaces:

ServiceManager

public class ServiceManagerImpl
extends java.lang.Object
implements ServiceManager

The ServiceManager simplifies the management of the OSGi service discovery process.

It is intended that this class is used internally in bundles in the following manner;

The BundleActivator instantiates a single ServiceManager in the start() method, and pass it to all parts of the bundle that require any external service.

 private ServiceManager m_serviceManager;
 

 public void start( BundleContext bundleContext )
     throws Exception
 {
     m_serviceManager = new ServiceManagerImpl( bundleContext );
     SomeWorker worker = new SomeWorker( m_serviceManager );
     worker.start();
 }
 

The user of the ServiceManager must remember to NOT cache the returned service for a very long time. It should either be released after each use, or at a maximum of a few seconds. This will ensure that reload of services are properly removing the old classes and replacing them with the new ones.

 public class SomeWorker
 {
     private ServiceManager m_serviceManager;
 

     public SomeWorker( ServiceManager serviceManager )
     {
         m_serviceManager = serviceManager;
     }
 

     public void someMethod()
     {
         SomeService service = (SomeService) m_serviceManager.getService( SomeService.class );
         service.doSomething();
     }
 

Well behaving bundle activators should also dispose the ServiceManager in the stop() method.

 public void stop( BundleContext bundleContext )
     throws Exception
 {
     m_serviceManager.dispose();
 }
 

NOTE! If the ServiceManager is used during the start() method, there is no point of waiting unless a separate thread is started for the bundle, since the framework starts bundles in sequential order, and therefor it is very likely that no services will appear while waiting. It is also bad practice for bundles to occupy the thread for lengthy operations in the start() and stop() methods, and should create their own threads of execution if this is necessary, such as await the arrival of other services.

Since:

1.0.0

Field Summary

Fields inherited from interface org.ops4j.pax.servicemanager.ServiceManager

DEFAULT_SERVICE_TIMEOUT

Constructor Summary

ServiceManagerImpl(org.osgi.framework.BundleContext context)
Construct an instance of ServiceManagerImpl with default service timeout.

ServiceManagerImpl(org.osgi.framework.BundleContext context, long serviceTimeOut)
Construct an instance of ServiceManagerImpl with the specified context and serviceTimeOut.

Method Summary

void	dispose() Dispose all the services cached by this ServiceManager.
java.lang.Object	getService(java.lang.Class serviceClass) Returns service of the specified serviceClass.
java.lang.Object	getService(java.lang.Class serviceClass, java.lang.String search, boolean waitAWhileIfNotAvailable) Returns service of the specified serviceClass.

Methods inherited from class java.lang.Object

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

Constructor Detail

ServiceManagerImpl

public ServiceManagerImpl(org.osgi.framework.BundleContext context)

Construct an instance of ServiceManagerImpl with default service timeout.

Parameters:

context - The bundle context. This argument must not be null.

Since:

1.0.0

See Also:

ServiceManager.DEFAULT_SERVICE_TIMEOUT

ServiceManagerImpl

public ServiceManagerImpl(org.osgi.framework.BundleContext context,
                          long serviceTimeOut)

Construct an instance of ServiceManagerImpl with the specified context and serviceTimeOut.

Parameters:

context - The bundle context. This argument must not be null.

serviceTimeOut - A time out value in milliseconds. Negative value is treated as 0.

Since:

1.0.0

Method Detail

dispose

public void dispose()

Dispose all the services cached by this ServiceManager.

Specified by:

dispose in interface ServiceManager

Since:

1.0.0

getService

public java.lang.Object getService(java.lang.Class serviceClass)
                            throws java.lang.IllegalArgumentException

Returns service of the specified serviceClass. Returns null if the service is not available at the time of invocation. This method is equivalent to:

serviceManager.getService( Class, String, false );

Specified by:

getService in interface ServiceManager

Parameters:

serviceClass - The service class object to be returned. This argument must not be null.

Returns:

The service object of the specified serviceClass.

Throws:

java.lang.IllegalArgumentException

Since:

1.0.0

See Also:

ServiceManager.getService(Class, String, boolean)

getService

public java.lang.Object getService(java.lang.Class serviceClass,
                                   java.lang.String search,
                                   boolean waitAWhileIfNotAvailable)
                            throws java.lang.IllegalArgumentException

Returns service of the specified serviceClass. Returns null if the service is not available.

Specified by:

getService in interface ServiceManager

Parameters:

serviceClass - The service class object to be returned. This argument must not be null.

search - The service class name.

waitAWhileIfNotAvailable - A boolean indicator whether this service manager should wait until time-out if the queried service is not available.

Returns:

The service object of the specified serviceClass.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified serviceClass is null.

Since:

1.0.0