com.holonplatform.core

## Interface ContextScope

-     public interface ContextScope

  A `Context` scope to hold, manage and access context resources. Every resource is identified by a `String` key.

  Each scope is identified by a name which must be unique among all registered context scopes and may implement a specific strategy to store and provide resources.

  Every concrete scope must provide the `get(String, Class)` operation. Resource management operations (put/remove) are optional and may not be available, throwing an `UnsupportedOperationException`.

  A ContextScope must be registered in `ContextManager` to be accessibile from `Context` façade and join generic context resource retrieval chain. Scope registration can be performed using default Java extension through `ServiceLoader` or directly using `ContextManager.registerScope(ClassLoader, ContextScope)`.

  The `getOrder()` method can be used to assign a order to the scope within the scopes chain for context resource resolution. Lower order values mean highest precedence.

  Since:
    5.0.0

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T> Optional<T>` | `get(String resourceKey, Class<T> resourceType)` Try to obtain the resource identified by given `resourceKey` and with expected `resourceType`.
    `String` | `getName()` Gets the scope name.
    `int` | `getOrder()` Gets the scope order.
    `<T> Optional<T>` | `put(String resourceKey, T value)` Stores a resource reference identified by given `resourceKey`.
    `<T> Optional<T>` | `putIfAbsent(String resourceKey, T value)` Stores a resource reference identified by given `resourceKey`, only if there is not a resource instance already bound to given key.
    `boolean` | `remove(String resourceKey)` Removes the resource reference bound to the given `resourceKey` from scope, if any.

- - ### Method Detail

    - #### getName

          String getName()

      Gets the scope name. Scope name must be unique among all registered context scopes.
      Returns:
        the scope name

    - #### getOrder

          int getOrder()

      Gets the scope order. Lower order values mean highest precedence.
      Returns:
        the scope order

    - #### get

          <T> Optional<T> get(String resourceKey,
                              Class<T> resourceType)
                       throws TypeMismatchException

      Try to obtain the resource identified by given `resourceKey` and with expected `resourceType`.
      Type Parameters:
        `T` - Resource type
      Parameters:
        `resourceKey` - Resource key (not null)
        `resourceType` - Expected resource type (not null)
      Returns:
        Optional resource instance, an empty Optional if resource is not available from scope according to scope resource provisioning strategy
      Throws:
        `TypeMismatchException` - If a resource is available but the expected type is not compatible with the resource type

    - #### put

          <T> Optional<T> put(String resourceKey,
                              T value)
                       throws UnsupportedOperationException

      Stores a resource reference identified by given `resourceKey`.
      Type Parameters:
        `T` - Resource instance type
      Parameters:
        `resourceKey` - Resource key (not null)
        `value` - Resource instance. If `null`, if a previous resource was bound to given resource key, it will be removed from scope.
      Returns:
        Optional previous resource instance bound to given key
      Throws:
        `UnsupportedOperationException` - If the concrete scope implementation does not support this operation

    - #### putIfAbsent

          <T> Optional<T> putIfAbsent(String resourceKey,
                                      T value)
                               throws UnsupportedOperationException

      Stores a resource reference identified by given `resourceKey`, only if there is not a resource instance already bound to given key.
      Type Parameters:
        `T` - Resource instance type
      Parameters:
        `resourceKey` - Resource key (not null)
        `value` - Resource instance, if `null`, this method should do nothing.
      Returns:
        Optional previous resource instance bound to given key. If there was no resource already bound to the key, an empty Optional is returned, meaning the given `value` has been associated to the resource key.
      Throws:
        `UnsupportedOperationException` - If the concrete scope implementation does not support this operation

    - #### remove

          boolean remove(String resourceKey)
                  throws UnsupportedOperationException

      Removes the resource reference bound to the given `resourceKey` from scope, if any.
      Parameters:
        `resourceKey` - Resource key (not null)
      Returns:
        `true` if a resource instance was bound to the given key and it's been removed, `false` otherwise.
      Throws:
        `UnsupportedOperationException` - If the concrete scope implementation does not support this operation

Copyright © 2019 The Holon Platform. All rights reserved.