Module io.helidon.common.context
Package io.helidon.common.context

Interface Context

public interface Context
A registry for context objects. Enables instance localization between several services / components / ... integrated in a particular known scope. ContextualRegistry instance is intended to be associated with a scope aware object such as WebServer, ServerRequest or ClientRequest.

Context contains also a notion of classifiers. Classifier is any object defining additional key for registered objects. To obtain such registered object, the same classifier (precisely, any equal object) has to be used.

Classifiers can be used as follows:

  1. As an additional identifier for registered objects of common types, like a String, ...
    
 // User detail provider service
 registry.register("NAME_PARAM_ID", "Smith");
 registry.register("GENDER_PARAM_ID", "male");
 ...
 // User consumer service
 String name = registry.get("name", String.class);
  2. As an access control mechanism where only owners of the classifier can retrieve such contextual instance.
    
 // In some central security service.
 registry.register(securityFrameworkInternalInstance, new AuthenticatedInternalIdentity(...));
 ...
 // In some authorization filter known by a central security service
 AuthenticatedInternalIdentity auth = registry.get(securityFrameworkInternalInstance, AuthenticatedInternalIdentity.class);

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Context.Builder
    Fluent API builder for Context.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Context.Builder
    builder()
    Fluent API builder for advanced configuration.
    static Context
    create()
    Creates a new empty instance.
    static Context
    create(Context parent)
    Creates a new empty instance backed by its parent read-through Context.
    <T> Optional<T>
    get(Class<T> type)
    Optionally gets registered instance by its type.
    <T> Optional<T>
    get(Object classifier, Class<T> type)
    Optionally gets a registered instance by its type.
    String
    id()
    A unique id of this context within this runtime.
    <T> void
    register(Object classifier, T instance)
    Register a new instance with specified classifier.
    <T> void
    register(T instance)
    Register a new instance.
    <T> void
    supply(Class<T> type, Supplier<T> supplier)
    Register a new instance using a provided supplier.
    <T> void
    supply(Object classifier, Class<T> type, Supplier<T> supplier)
    Registers a new instance using a provided supplier.

  • Method Details

    • create

      static Context create()
      Creates a new empty instance.
      Returns:
      new instance

    • create

      static Context create(Context parent)
      Creates a new empty instance backed by its parent read-through Context.

      Parent registry is used only for get methods and only if this registry doesn't have registered required type.

      Parameters:
      parent - a parent registry
      Returns:
      new instance

    • builder

      static Context.Builder builder()
      Fluent API builder for advanced configuration.
      Returns:
      a new builder

    • register

      <T> void register(T instance)
      Register a new instance.
      Type Parameters:
      T - a type of the registered instance
      Parameters:
      instance - an instance to register
      Throws:
      NullPointerException - if the registered object is null

    • supply

      <T> void supply(Class<T> type, Supplier<T> supplier)
      Register a new instance using a provided supplier. The supplier is guaranteed to be called at most once when it's requested by the get(Class) method. The returned value is then registered and the supplier is never used again.
      Type Parameters:
      T - a type of supplied object
      Parameters:
      type - a type of supplied instance
      supplier - a supplier of the instance to register
      Throws:
      NullPointerException - if the type or the supplier is null

    • get

      <T> Optional<T> get(Class<T> type)
      Optionally gets registered instance by its type.

      More specifically, it returns the last registered instance without specified classifier which can be cast to the requested type.

      Type Parameters:
      T - a type of requested instance
      Parameters:
      type - a type of requested instance
      Returns:
      The last registered instance compatible with the specified type

    • register

      <T> void register(Object classifier, T instance)
      Register a new instance with specified classifier.

      Registered instance can be obtained only using get(Object, Class) method with a classifier equal with the one used during registration.

      Type Parameters:
      T - a type of the registered instance
      Parameters:
      classifier - an additional registered instance classifier
      instance - an instance to register
      Throws:
      NullPointerException - if classifier or registered object is null

    • supply

      <T> void supply(Object classifier, Class<T> type, Supplier<T> supplier)
      Registers a new instance using a provided supplier. The supplier is guarantied to be called at most once when it's requested by the get(Object, Class) method. The returned value gets registered and the supplier is never called again.

      Registered instance can be obtained only using get(Object, Class) method with a classifier equal with the one used during registration.

      Type Parameters:
      T - a type of supplied object
      Parameters:
      classifier - an additional registered instance classifier
      type - a type of requested instance
      supplier - a supplier of the instance to register
      Throws:
      NullPointerException - If any parameter is null.

    • get

      <T> Optional<T> get(Object classifier, Class<T> type)
      Optionally gets a registered instance by its type.

      More specifically, it returns the last registered instance with equal classifier which can be cast to the requested type.

      Type Parameters:
      T - a type of requested instance
      Parameters:
      classifier - an additional registered instance classifier
      type - a type of requested instance
      Returns:
      the last registered instance compatible with the specified type
      Throws:
      NullPointerException - If classifier is null.

    • id

      String id()
      A unique id of this context within this runtime.
      Returns:
      id of this context