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 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