com.holonplatform.core

## Interface Context

-     public interface Context

  Main interface to access global platform context resources.

  A context resource is an object instance identified by a `String` key.

  Resources are organized in `ContextScope`s, each of them characterized by a resource data source and a resource retrieval strategy. A scope can be manageable, i.e. supporting resource addition and removal, or not.

  Context scope can be registered either by using standard Java extension service loading using `ContextScope` class name files under `META-INF/services`, or by direct registration using `ContextManager.registerScope(ClassLoader, ContextScope)`.

  When asking for a context resource using `resource(String, Class)` and similar methods, all registered context scopes are invoked, in the order defined by `ContextScope.getOrder()` precedence value. The first not null resource instance obtained from a scope is the one returned to caller, if any.

  Every `Context` resource set is bound to a `ClassLoader`. If not specified, the default classloader is obtained from `ClassUtils.getDefaultClassLoader()`.

  Two default context scope are registered by default:
  - A ClassLoader bound scope named `CLASSLOADER_SCOPE_NAME`, registering and providing resources as singleton instances for the reference ClassLoader. This scope is registered with a low precedence order;
  - A thread-bound scope named `THREAD_SCOPE_NAME`, using current Thread local data set to register and provide context resources. This scope is registered with a high precedence order.
  Since:
    5.0.0

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CLASSLOADER_SCOPE_NAME` Default classloader-bound scope name
    `static String` | `THREAD_SCOPE_NAME` Default thread-bound scope name

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default Optional<ContextScope>` | `classLoaderScope()` Shortcut method to obtain the ClassLoader-bound context scope, i.e. the default `ContextScope` named `CLASSLOADER_SCOPE_NAME`, using the default `ClassLoader`.
    `default Optional<ContextScope>` | `classLoaderScope(ClassLoader classLoader)` Shortcut method to obtain the ClassLoader-bound context scope, i.e. the default `ContextScope` named `CLASSLOADER_SCOPE_NAME`.
    `default <V> V` | `executeThreadBound(String resourceKey, Object resource, Callable<V> operation)` Execute given `Callable` `operation`, binding given `Context` resource key and value to current Thread, and removing the binding after operation execution.
    `default void` | `executeThreadBound(String resourceKey, Object resource, Runnable operation)` Execute given `Runnable` `operation`, binding given `Context` resource key and value to current Thread, and removing the binding after operation execution.
    `static Context` | `get()` Obtain the default `Context` implementation instance.
    `default <T> Optional<T>` | `resource(Class<T> resourceType)` Shortcut method to obtain a `Context` resource using the `resourceType` class name as resource key.
    `default <T> Optional<T>` | `resource(Class<T> resourceType, ClassLoader classLoader)` Shortcut method to obtain a `Context` resource using the `resourceType` class name as resource key and given `classLoader`.
    `default <T> Optional<T>` | `resource(String resourceKey, Class<T> resourceType)` Lookup a context resource of `resourceType` class using given `resourceKey` and the default `ClassLoader`.
    `<T> Optional<T>` | `resource(String resourceKey, Class<T> resourceType, ClassLoader classLoader)` Lookup a context resource of `resourceType` class using given `resourceKey`.
    `default Optional<ContextScope>` | `scope(String name)` Gets a registered `ContextScope` with the given `name` and bound to default `ClassLoader`.
    `Optional<ContextScope>` | `scope(String name, ClassLoader classLoader)` Gets a registered `ContextScope` with the given `name` and bound to given `classLoader`.
    `default Optional<ContextScope>` | `threadScope()` Shortcut method to obtain the thread-bound context scope, i.e. the default `ContextScope` named `THREAD_SCOPE_NAME`, using the default `ClassLoader`.
    `default Optional<ContextScope>` | `threadScope(ClassLoader classLoader)` Shortcut method to obtain the thread-bound context scope, i.e. the default `ContextScope` named `THREAD_SCOPE_NAME`.

- - ### Field Detail

    - #### THREAD_SCOPE_NAME

          static final String THREAD_SCOPE_NAME

      Default thread-bound scope name
      See Also:
        Constant Field Values

    - #### CLASSLOADER_SCOPE_NAME

          static final String CLASSLOADER_SCOPE_NAME

      Default classloader-bound scope name
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### resource

          <T> Optional<T> resource(String resourceKey,
                                   Class<T> resourceType,
                                   ClassLoader classLoader)

      Lookup a context resource of `resourceType` class using given `resourceKey`.

      All registered context scopes are invoked, in the order defined by `ContextScope.getOrder()` precedence value. The first not `null` resource instance obtained from a scope is the one returned to caller, if any.

      Type Parameters:
        `T` - Resource type
      Parameters:
        `resourceKey` - Resource key (not null)
        `resourceType` - Required resource type (not null)
        `classLoader` - ClassLoader to use. If `null`, the default ClassLoader is used.
      Returns:
        Optional resource instance, empty if not available from context
      Throws:
        `TypeMismatchException` - If a context resource with given key was found but it is not of required type

    - #### resource

          default <T> Optional<T> resource(String resourceKey,
                                           Class<T> resourceType)

      Lookup a context resource of `resourceType` class using given `resourceKey` and the default `ClassLoader`.

      All registered context scopes are invoked, in the order defined by `ContextScope.getOrder()` precedence value. The first not `null` resource instance obtained from a scope is the one returned to caller, if any.

      Type Parameters:
        `T` - Resource type
      Parameters:
        `resourceKey` - Resource key (not null)
        `resourceType` - Required resource type (not null)
      Returns:
        Optional resource instance, empty if not available from context
      Throws:
        `TypeMismatchException` - If a context resource with given key was found but it is not of required type

    - #### resource

          default <T> Optional<T> resource(Class<T> resourceType)

      Shortcut method to obtain a `Context` resource using the `resourceType` class name as resource key.
      Type Parameters:
        `T` - Resource type
      Parameters:
        `resourceType` - Resource type (not null)
      Returns:
        Optional resource instance, empty if not available from context

    - #### resource

          default <T> Optional<T> resource(Class<T> resourceType,
                                           ClassLoader classLoader)

      Shortcut method to obtain a `Context` resource using the `resourceType` class name as resource key and given `classLoader`.
      Type Parameters:
        `T` - Resource type
      Parameters:
        `resourceType` - Resource type (not null)
        `classLoader` - ClassLoader to use. If `null`, the default ClassLoader is used.
      Returns:
        Optional resource instance, empty if not available from context

    - #### scope

          Optional<ContextScope> scope(String name,
                                       ClassLoader classLoader)

      Gets a registered `ContextScope` with the given `name` and bound to given `classLoader`.
      Parameters:
        `name` - Scope name (not null)
        `classLoader` - ClassLoader, if `null`, the default ClassLoader is used
      Returns:
        The registered `ContextScope` with given name, or an empty Optional if a scope with such name is not registered in context

    - #### scope

          default Optional<ContextScope> scope(String name)

      Gets a registered `ContextScope` with the given `name` and bound to default `ClassLoader`.
      Parameters:
        `name` - Scope name (not null)
      Returns:
        The registered `ContextScope` with given name, or an empty Optional if a scope with such name is not registered in context

    - #### classLoaderScope

          default Optional<ContextScope> classLoaderScope(ClassLoader classLoader)

      Shortcut method to obtain the ClassLoader-bound context scope, i.e. the default `ContextScope` named `CLASSLOADER_SCOPE_NAME`.
      Parameters:
        `classLoader` - ClassLoader, if `null`, the default ClassLoader is used
      Returns:
        The ClassLoader-bound context scope, or an empty Optional if scope is not registered

    - #### classLoaderScope

          default Optional<ContextScope> classLoaderScope()

      Shortcut method to obtain the ClassLoader-bound context scope, i.e. the default `ContextScope` named `CLASSLOADER_SCOPE_NAME`, using the default `ClassLoader`.
      Returns:
        The ClassLoader-bound context scope, or an empty Optional if scope is not registered

    - #### threadScope

          default Optional<ContextScope> threadScope(ClassLoader classLoader)

      Shortcut method to obtain the thread-bound context scope, i.e. the default `ContextScope` named `THREAD_SCOPE_NAME`.
      Parameters:
        `classLoader` - ClassLoader, if `null`, the default ClassLoader is used
      Returns:
        The thread-bound context scope, or an empty Optional if scope is not registered

    - #### threadScope

          default Optional<ContextScope> threadScope()

      Shortcut method to obtain the thread-bound context scope, i.e. the default `ContextScope` named `THREAD_SCOPE_NAME`, using the default `ClassLoader`.
      Returns:
        The thread-bound context scope, or an empty Optional if scope is not registered

    - #### executeThreadBound

          default void executeThreadBound(String resourceKey,
                                          Object resource,
                                          Runnable operation)
                                   throws RuntimeException

      Execute given `Runnable` `operation`, binding given `Context` resource key and value to current Thread, and removing the binding after operation execution.

      The `THREAD_SCOPE_NAME` context scope is used.

      Parameters:
        `resourceKey` - Context resource key (not null)
        `resource` - Context resource value to bind to current Thread (not null)
        `operation` - Operation to execute (not null)
      Throws:
        `RuntimeException` - Exception during operation execution

    - #### executeThreadBound

          default <V> V executeThreadBound(String resourceKey,
                                           Object resource,
                                           Callable<V> operation)
                                    throws RuntimeException

      Execute given `Callable` `operation`, binding given `Context` resource key and value to current Thread, and removing the binding after operation execution.

      The `THREAD_SCOPE_NAME` context scope is used.

      Type Parameters:
        `V` - Operation result type
      Parameters:
        `resourceKey` - Context resource key (not null)
        `resource` - Context resource value to bind to current Thread (not null)
        `operation` - Operation to execute
      Returns:
        Operation result
      Throws:
        `RuntimeException` - Exception during operation execution

    - #### get

          static Context get()

      Obtain the default `Context` implementation instance.
      Returns:
        Default `Context`

Copyright © 2019 The Holon Platform. All rights reserved.