Package org.scijava.service

Class ServiceHelper

java.lang.Object

org.scijava.AbstractContextual

org.scijava.service.ServiceHelper

All Implemented Interfaces:

Contextual

public class ServiceHelper
extends AbstractContextual

Helper class for discovering and instantiating available services.

Author:

Curtis Rueden

Constructor Summary

Constructors

Constructor	Description
ServiceHelper(Context context)	Creates a new service helper for discovering and instantiating services.
ServiceHelper(Context context, Collection<Class<? extends Service>> serviceClasses)	Creates a new service helper for discovering and instantiating services.
ServiceHelper(Context context, Collection<Class<? extends Service>> serviceClasses, boolean strict)	Creates a new service helper for discovering and instantiating services.

Method Summary

Modifier and Type	Method	Description
<S extends Service> S	createExactService(Class<S> c)	Instantiates a service of the given class, registering it in the index.
<S extends Service> S	loadService(Class<S> c)	Obtains a service compatible with the given class, instantiating it (and registering it in the index) if necessary.
void	loadServices()	Ensures all candidate service classes are registered in the index, locating and instantiating compatible services as needed.

Methods inherited from class org.scijava.AbstractContextual

context, getContext

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.scijava.Contextual

setContext

Constructor Detail

ServiceHelper

public ServiceHelper(Context context)

Creates a new service helper for discovering and instantiating services.

Parameters:

context - The application context for which services should be instantiated.

ServiceHelper

public ServiceHelper(Context context,
                     Collection<Class<? extends Service>> serviceClasses)

Creates a new service helper for discovering and instantiating services.

Parameters:

context - The application context to which services should be added.

serviceClasses - The service classes to instantiate.

ServiceHelper

public ServiceHelper(Context context,
                     Collection<Class<? extends Service>> serviceClasses,
                     boolean strict)

Creates a new service helper for discovering and instantiating services.

Parameters:

context - The application context to which services should be added.

serviceClasses - The service classes to instantiate.

strict - Whether service loading will fail fast when there is an error instantiating a required service.

Method Detail

loadServices

public void loadServices()

Ensures all candidate service classes are registered in the index, locating and instantiating compatible services as needed.

This is a NxM operation, where N is the number of service classes attached to this ServiceHelper, and M is the number of discovered plugins. Multiple implementations of a given service subclass can be loaded. For example, if FooService, a subclass of Service (whether abstract, concrete, or an interface), appears on the service list, all subclasses of FooService in the plugin class pool will be loaded.

NB: In typical use, a Context will only return the highest priority implementation for a loaded service. To retrieve the lower priority service(s), they must be requested directly (or through a superclass not shared with the higher priority implementation). Thus, as these lower priority services will go unused in many cases, it is critical that service loading (initialization) is as lightweight as possible.

Throws:

IllegalArgumentException - if one of the requested services is required (i.e., not marked Optional) but cannot be filled.

loadService

public <S extends Service> S loadService(Class<S> c)

Obtains a service compatible with the given class, instantiating it (and registering it in the index) if necessary.

Returns:

an existing compatible service if one is already registered; or else a newly created instance of the service with highest priority; or null if no suitable service can be created

Throws:

IllegalArgumentException - if no suitable service can be created and the class is required (i.e., not marked Optional)

createExactService

public <S extends Service> S createExactService(Class<S> c)

Instantiates a service of the given class, registering it in the index.

Returns:

the newly created service, or null if the given class cannot be instantiated