Package io.helidon.common.http

Interface ContextualRegistry

public interface ContextualRegistry

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 Summary

Modifier and Type	Method and Description
static ContextualRegistry	create() Creates a new empty instance.
static ContextualRegistry	create(ContextualRegistry parent) Creates a new empty instance backed by its parent read-through ContextualRegistry.
<T> java.util.Optional<T>	get(java.lang.Class<T> type) Optionally gets registered instance by its type.
<T> java.util.Optional<T>	get(java.lang.Object classifier, java.lang.Class<T> type) Optionally gets a registered instance by its type.
<T> void	register(java.lang.Object classifier, T instance) Register a new instance with specified classifier.
<T> void	register(T instance) Register a new instance.
<T> void	supply(java.lang.Class<T> type, java.util.function.Supplier<T> supplier) Register a new instance using a provided supplier.
<T> void	supply(java.lang.Object classifier, java.lang.Class<T> type, java.util.function.Supplier<T> supplier) Registers a new instance using a provided supplier.

Method Detail

create

static ContextualRegistry create()

Creates a new empty instance.

Returns:

new instance

create

static ContextualRegistry create(ContextualRegistry parent)

Creates a new empty instance backed by its parent read-through ContextualRegistry.

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

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:

java.lang.NullPointerException - if the registered object is null

supply

<T> void supply(java.lang.Class<T> type,
                java.util.function.Supplier<T> supplier)

Register a new instance using a provided supplier. The supplier is guarantied 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:

java.lang.NullPointerException - if the type or the supplier is null

get

<T> java.util.Optional<T> get(java.lang.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(java.lang.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:

java.lang.NullPointerException - if classifier or registered object is null

supply

<T> void supply(java.lang.Object classifier,
                java.lang.Class<T> type,
                java.util.function.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:

java.lang.NullPointerException - If any parameter is null.

get

<T> java.util.Optional<T> get(java.lang.Object classifier,
                              java.lang.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:

java.lang.NullPointerException - If classifier is null.