sirius.kernel.async

Class CallContext

java.lang.Object

sirius.kernel.async.CallContext

@ParametersAreNonnullByDefault
public class CallContext
extends Object

A CallContext is attached to each thread managed by sirius.

It provides access to different sub-contexts via get(Class). Also, it provides acces to the mapped diagnostic context (MDC). This can be filled by various parts of the framework (like which request-uri is currently being processed, which user is currently active etc.) and will be attached to each error. Also, each context comes with a new "flow-id". This can be used to trace an execution across different threads and even across different cluster nodes.

Tasks which fork async subtasks will automatically pass on their current context. Therefore essential information can be passed along, without having to provide a method parameter for each value. Since sub-contexts can be of any type, this concept can be enhanced by additional frameworks or application programs.

Field Summary

Fields

Modifier and Type	Field and Description
static String	MDC_FLOW Name of the flow variable in the MDC.
static String	MDC_PARENT Name of the parent context in the MDC

Constructor Summary

Constructors

Constructor and Description
CallContext()

Method Summary

Modifier and Type	Method and Description
void	addToMDC(String key, String value) Adds a value to the mapped diagnostic context.
void	addToMDC(String key, Supplier<String> value) Adds a value to the mapped diagnostic context.
static void	detach() Detaches this CallContext from the current thread
void	detachContext() Detaches this context from the current thread.
CallContext	fork() Forks and creates a sub context.
<C extends SubContext> C	get(Class<C> contextType) Returns or creates the sub context of the given type.
static Optional<CallContext>	getContext(long threadId) Returns the CallContext for the given thread or an empty optional if none is present.
static CallContext	getCurrent() Returns the context for the current thread.
static CallContext	getCurrentIfAvailable() Returns the context for the current thread.
String	getFallbackLang() Returns the current fallback language determined for the current thread.
static Counter	getInteractionCounter() Provides access to the interaction counter.
String	getLang() Returns the current language determined for the current thread.
List<Tuple<String,String>>	getMDC() Returns the current mapped diagnostic context (MDC).
Value	getMDCValue(String key) Returns the value of the named variable in the mdc.
static String	getNodeName() Returns the name of this computation node.
Watch	getWatch() Returns the Watch representing the execution time.
static CallContext	initialize() Creates a new CallContext for the given thread.
void	removeFromMDC(String key) Removes the value of the mdc for key.
<C extends SubContext> void	set(Class<C> contextType, C instance) Installs the given sub context.
static void	setCurrent(CallContext context) Sets the CallContext for the current thread.
void	setFallbackLang(String fallbackLang) Sets the current fallback language for the current thread.
void	setLang(String lang) Sets the current language for the current thread.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MDC_FLOW

public static final String MDC_FLOW

Name of the flow variable in the MDC.

See Also:

Constant Field Values

MDC_PARENT

public static final String MDC_PARENT

Name of the parent context in the MDC

See Also:

Constant Field Values

Constructor Detail

CallContext

public CallContext()

Method Detail

getNodeName

public static String getNodeName()

Returns the name of this computation node.

This is either the current host name or can be set via sirius.nodeName.

Returns:

the name of this computation node.

getContext

@Nonnull
public static Optional<CallContext> getContext(long threadId)

Returns the CallContext for the given thread or an empty optional if none is present.

Parameters:

threadId - the id of the thread to fetch the CallContext for

Returns:

the CallContext for the given thread wrapped as optional

getCurrentIfAvailable

@Nullable
public static CallContext getCurrentIfAvailable()

Returns the context for the current thread.

Returns:

the current context or null if none is present yet

getCurrent

@Nonnull
public static CallContext getCurrent()

Returns the context for the current thread.

If no context is available, a new one will be initialized.

Returns:

the CallContext of the current thread.

getInteractionCounter

public static Counter getInteractionCounter()

Provides access to the interaction counter.

This counts all CallContexts which have been created and is used to provide rough system utilization metrics.

Returns:

the Counter, which contains the total number of CallContexts created

initialize

public static CallContext initialize()

Creates a new CallContext for the given thread.

Discards the current CallContext, if there was already one.

Returns:

the newly created CallContext, which is already attached to the current thread.

fork

public CallContext fork()

Forks and creates a sub context.

All instantiated sub contexts are forked, the MDC is re-initialized.

Returns:

a copy of the current call context including a fork of all available sub contexts.

See Also:

SubContext.fork()

setCurrent

public static void setCurrent(CallContext context)

Sets the CallContext for the current thread.

Parameters:

context - the context to use for the current thread.

detach

public static void detach()

Detaches this CallContext from the current thread

detachContext

public void detachContext()

Detaches this context from the current thread.

This will notify all sub contexts (SubContext) that this context essentially ended.

getMDC

public List<Tuple<String,String>> getMDC()

Returns the current mapped diagnostic context (MDC).

Returns:

a list of name-value pair representing the current mdc.

getMDCValue

public Value getMDCValue(String key)

Returns the value of the named variable in the mdc.

Parameters:

key - the name of the variable to read.

Returns:

the value of the mapped diagnostic context.

getWatch

public Watch getWatch()

Returns the Watch representing the execution time.

Returns:

a Watch, representing the duration since the creation of the CallContext. Due to CallContexts being passed to forked sub tasks, the returned duration can be longer than the execution time within the current thread.

addToMDC

public void addToMDC(String key,
                     @Nullable
                     String value)

Adds a value to the mapped diagnostic context.

Parameters:

key - the name of the value to add

value - the value to add to the mdc.

addToMDC

public void addToMDC(String key,
                     @Nullable
                     Supplier<String> value)

Adds a value to the mapped diagnostic context.

Parameters:

key - the name of the value to add

value - the supplier to add to the mdc. Will be evaluated one the MDC is used elsewhere.

removeFromMDC

public void removeFromMDC(String key)

Removes the value of the mdc for key.

Parameters:

key - the name of the value to remove.

get

@Nonnull
public <C extends SubContext> C get(Class<C> contextType)

Returns or creates the sub context of the given type.

The class of the sub context must provide a no-args constructor, as it will be instantiated if non existed.

Type Parameters:

C - the type of the sub-context

Parameters:

contextType - the type of the sub-context to be returned.

Returns:

an instance of the given type. If no instance was available, a new one is created

set

public <C extends SubContext> void set(Class<C> contextType,
                                       C instance)

Installs the given sub context.

This should only be used if required (e.g. in test environments to replace/mock objects). Otherwise a call to get(Class) will initialize the requested sub context.

Type Parameters:

C - the type of the sub-context

Parameters:

contextType - the type of the context to set

instance - the instance to set

getLang

public String getLang()

Returns the current language determined for the current thread.

Returns:

a two-letter language code used for the current thread.

getFallbackLang

@Nullable
public String getFallbackLang()

Returns the current fallback language determined for the current thread.

Returns:

a two-letter language code used for the current thread.

setLang

public void setLang(@Nullable
                    String lang)

Sets the current language for the current thread.

If null or an empty string is passed in, the language will not be changed.

Parameters:

lang - the two-letter language code for this thread.

setFallbackLang

public void setFallbackLang(@Nullable
                            String fallbackLang)

Sets the current fallback language for the current thread.

Parameters:

fallbackLang - the two-letter language code for this thread.

toString

public String toString()

Overrides:

toString in class Object