Package org.scijava

Class Context

    • Field Summary

      Fields 
      Modifier and Type Field 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 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.

    • 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​(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

      • 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.

      • 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

      • 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.