org.ops4j.pax.servicemanager
Interface ServiceManager

All Known Implementing Classes:

ServiceManagerImpl

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

Author:

Niclas Hedhman

Field Summary

static long

DEFAULT_SERVICE_TIMEOUT The default service timeout is 10000 milliseconds.

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.

Field Detail

DEFAULT_SERVICE_TIMEOUT

static final long DEFAULT_SERVICE_TIMEOUT

The default service timeout is 10000 milliseconds.

Since:

1.0.0

See Also:

Constant Field Values

Method Detail

dispose

void dispose()

Dispose all the services cached by this ServiceManager.

Since:

1.0.0

getService

java.lang.Object getService(java.lang.Class serviceClass)

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 );

Parameters:

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

Returns:

The service object of the specified serviceClass.

Since:

1.0.0

See Also:

getService(Class, String, boolean)

getService

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

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

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