org.scijava

Class Context

java.lang.Object

org.scijava.Context

All Implemented Interfaces:

AutoCloseable, Disposable

public class Context
extends Object
implements Disposable, AutoCloseable

Top-level SciJava application context, which initializes and maintains a list of services.

Author:

Curtis Rueden

See Also:

Service

Field Summary

Fields

Modifier and Type	Field and Description
static String	STRICT_PROPERTY System property indicating whether the context should fail fast when attempting to instantiate a required service which is invalid or missing.

Constructor Summary

Constructors

Constructor and Description
Context() Creates a new SciJava application context with all available services.
Context(boolean empty) Creates a new SciJava application context.
Context(boolean noServices, boolean noPlugins) Creates a new SciJava application context.
Context(Class... serviceClasses) Creates a new SciJava application context with the specified services (and any required service dependencies).
Context(Collection<Class<? extends Service>> serviceClasses) Creates a new SciJava application context with the specified services (and any required service dependencies).
Context(Collection<Class<? extends Service>> serviceClasses, boolean strict) Creates a new SciJava application context with the specified services (and any required service dependencies).
Context(Collection<Class<? extends Service>> serviceClasses, PluginIndex pluginIndex) Creates a new SciJava application context with the specified services (and any required service dependencies).
Context(Collection<Class<? extends Service>> serviceClasses, PluginIndex pluginIndex, boolean strict) Creates a new SciJava application context with the specified services (and any required service dependencies).
Context(PluginIndex pluginIndex) Creates a new SciJava application context with all available services from the specified PluginIndex.

Method Summary

Modifier and Type	Method and Description
void	close()
void	dispose() Performs any needed cleanup of the object's services, in preparation for the object being retired (e.g., to make garbage collection possible).
static ClassLoader	getClassLoader() Gets the class loader to use.
PluginIndex	getPluginIndex()
<S extends Service> S	getService(Class<S> c) Gets the service of the given class, or null if there is no matching service.
Service	getService(String className) Gets the service of the given class name (useful for scripts).
ServiceIndex	getServiceIndex()
void	inject(Object o) Injects the application context into the given object.
boolean	isInjectable(Class<?> type) Reports whether a parameter of the given type would be assigned a value as a consequence of calling inject(Object).
boolean	isStrict()
<S extends Service> S	service(Class<S> c) Gets the service of the given class.
Service	service(String className) Gets the service of the given class name (useful for scripts).
static List<Class<? extends Service>>	serviceClassList(Class... serviceClasses) Utility method for converting a varargs list of service classes to a List of those classes.
void	setStrict(boolean strict)

Methods inherited from class java.lang.Object

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

Field Detail

STRICT_PROPERTY

public static final String STRICT_PROPERTY

System property indicating whether the context should fail fast when attempting to instantiate a required service which is invalid or missing. If this property is set to "false" then the context creation will attempt to continue even when a required service cannot be instantiated. Otherwise, the constructor will throw an IllegalArgumentException in that situation.

See Also:

Constant Field Values

Constructor Detail

Context

public Context()

Creates a new SciJava application context with all available services.

See Also:

Context(Collection, PluginIndex, boolean)

Context

public Context(boolean empty)

Creates a new SciJava application context.

Parameters:

empty - If true, the context will be empty of services; otherwise, it will be initialized with all available services.

See Also:

Context(boolean, boolean)

Context

public Context(boolean noServices,
               boolean noPlugins)

Creates a new SciJava application context.

Parameters:

noServices - If true, the context will contain no services; otherwise, it will be initialized with all available services.

noPlugins - If true, the context will contain no plugins; otherwise, it will be initialized with all available plugins.

See Also:

Context(Collection, PluginIndex, boolean)

Context

public Context(Class... serviceClasses)

Creates a new SciJava application context with the specified services (and any required service dependencies).

Developer's note: This constructor's argument is raw (i.e., Class... instead of Class<? extends Service>...) because otherwise, downstream invocations (e.g., new Context(DisplayService.class)) yield the potentially confusing warning:

Type safety: A generic array of Class<? extends Service> is created for a varargs parameter

To avoid this, we have opted to use raw types and suppress the relevant warnings here instead.

Parameters:

serviceClasses - A list of types that implement the Service interface (e.g., DisplayService.class). Compatible services will be loaded in the order given, regardless of their relative priorities.

Throws:

ClassCastException - If any of the given arguments do not implement the Service interface.

See Also:

Context(Collection, PluginIndex, boolean)

Context

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

Creates a new SciJava application context with the specified services (and any required service dependencies).

Parameters:

serviceClasses - A collection of types that implement the Service interface (e.g., DisplayService.class). Compatible services will be loaded according to the order of the collection, regardless of their relative priorities.

See Also:

Context(Collection, PluginIndex, boolean)

Context

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

Creates a new SciJava application context with the specified services (and any required service dependencies).

Parameters:

serviceClasses - A collection of types that implement the Service interface (e.g., DisplayService.class). Compatible services will be loaded according to the order of the collection, regardless of their relative priorities.

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

See Also:

Context(Collection, PluginIndex, boolean)

Context

public Context(PluginIndex pluginIndex)

Creates a new SciJava application context with all available services from the specified PluginIndex. This allows a base set of available plugins to be defined, and is useful when plugins that would not be returned by the PluginIndex's PluginFinder are desired.

Parameters:

pluginIndex - The plugin index to use when discovering and indexing plugins. If you wish to completely control how services are discovered (i.e., use your own PluginFinder implementation), then you can pass a custom PluginIndex here. Passing null will result in a default plugin index being constructed and used.

See Also:

Context(Collection, PluginIndex, boolean)

Context

public Context(Collection<Class<? extends Service>> serviceClasses,
               PluginIndex pluginIndex)

Creates a new SciJava application context with the specified services (and any required service dependencies). Service dependency candidates are selected from those discovered by the given PluginIndex's associated PluginFinder.

Parameters:

serviceClasses - A collection of types that implement the Service interface (e.g., DisplayService.class). Compatible services will be loaded according to the order of the collection, regardless of their relative priorities.

pluginIndex - The plugin index to use when discovering and indexing plugins. If you wish to completely control how services are discovered (i.e., use your own PluginFinder implementation), then you can pass a custom PluginIndex here. Passing null will result in a default plugin index being constructed and used.

See Also:

Context(Collection, PluginIndex, boolean)

Context

public Context(Collection<Class<? extends Service>> serviceClasses,
               PluginIndex pluginIndex,
               boolean strict)

Creates a new SciJava application context with the specified services (and any required service dependencies). Service dependency candidates are selected from those discovered by the given PluginIndex's associated PluginFinder.

NB: Context creation is an important step of a SciJava application's lifecycle. Particularly in environments where more than one implementation exists for various services, careful consideration should be exercised regarding what classes and plugins are provided to the Context, and what needs to occur during the initialization of these services (especially those of lower priority). See ServiceHelper.loadServices() for more information.

NB: Instiantiation of a Context has an implied requirement of a corresponding call to dispose() at the end of the SciJava applicaton's lifecycle. This cleans up any remaining resources and allows the JVM to exit gracefully. This is called automatically when constructed as an AutoCloseable.

Parameters:

serviceClasses - A collection of types that implement the Service interface (e.g., DisplayService.class). Compatible services will be loaded according to the order of the collection, regardless of their relative priorities.

pluginIndex - The plugin index to use when discovering and indexing plugins. If you wish to completely control how services are discovered (i.e., use your own PluginFinder implementation), then you can pass a custom PluginIndex here. Passing null will result in a default plugin index being constructed and used.

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

Method Detail

getServiceIndex

public ServiceIndex getServiceIndex()

getPluginIndex

public PluginIndex getPluginIndex()

isStrict

public boolean isStrict()

setStrict

public void setStrict(boolean strict)

service

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

Gets the service of the given class.

Throws:

NoSuchServiceException - if the context does not have the requested service.

service

public Service service(String className)

Gets the service of the given class name (useful for scripts).

Throws:

IllegalArgumentException - if the class does not exist, or is not a service class.

NoSuchServiceException - if the context does not have the requested service.

getService

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

Gets the service of the given class, or null if there is no matching service.

getService

public Service getService(String className)

Gets the service of the given class name (useful for scripts).

inject

public void inject(Object o)

Injects the application context into the given object. This does three distinct things:

1. If the given object has any non-final Context fields annotated with @Parameter, sets the value of those fields to this context.
2. If the given object has any non-final Service fields annotated with @Parameter, sets the value of those fields to the corresponding service available from this context.
3. Calls EventService.subscribe(Object) with the object to register any @EventHandler annotated methods as event subscribers.

Parameters:

o - The object to which the context should be assigned.

Throws:

IllegalStateException - If the object already has a context.

IllegalArgumentException - If the object has a required Service parameter (see Parameter.required()) which is not available from this context.

isInjectable

public boolean isInjectable(Class<?> type)

Reports whether a parameter of the given type would be assigned a value as a consequence of calling inject(Object).

This method is notably useful for downstream code to discern between Parameter fields whose values would be injected, versus those whose values would not, without needing to hardcode type comparison checks against the Service and Context types.

Parameters:

type - The type of the @Parameter-annotated field.

Returns:

True iff a member field of the given type would have its value assigned.

dispose

public void dispose()

Description copied from interface: Disposable

Performs any needed cleanup of the object's services, in preparation for the object being retired (e.g., to make garbage collection possible).

Specified by:

dispose in interface Disposable

close

public void close()

Specified by:

close in interface AutoCloseable

serviceClassList

public static List<Class<? extends Service>> serviceClassList(Class... serviceClasses)

Utility method for converting a varargs list of service classes to a List of those classes.

getClassLoader

public static ClassLoader getClassLoader()

Gets the class loader to use. This will be the current thread's context class loader if non-null; otherwise it will be the system class loader.

See Also:

Thread.getContextClassLoader(), ClassLoader.getSystemClassLoader()