Interface Context

  • All Known Subinterfaces:
    ContextualRegistry

    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);
       
    • Method Detail

      • 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