sirius.kernel.async

Class TaskContext

java.lang.Object

sirius.kernel.async.TaskContext

All Implemented Interfaces:

SubContext

public class TaskContext
extends Object
implements SubContext

Provides an interface between a running task and a monitoring system.

Any task or background job can access its TaskContext using either get() or CallContext.get(Class). This provides an interface to a monitoring system which might be present (by calling setAdapter(TaskContextAdapter). If no monitoring is available, the default mechanisms of the platform are used.

Field Summary

Fields

Modifier and Type	Field and Description
static String	MDC_SYSTEM One the system string is changed, it will be updated in the mapped diagnostic context (MDC) using this name.

Constructor Summary

Constructors

Constructor and Description
TaskContext() Generates a new TaskContext.

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancels the execution of this task.
void	detach() Gets notified if the associated CallContext is detached.
SubContext	fork() Returns an instance which is used in a forked CallContext.
static TaskContext	get() Provides access to the TaskContext for the current thread.
TaskContextAdapter	getAdapter() Returns the monitoring adapter which is currently active.
String	getJob() Returns the Job component of the System String
String	getSubSystem() Returns the Sub-System component of the System String
String	getSystem() Returns the System component of the System String
String	getSystemString() Returns the System String.
boolean	isActive() Determines if the execution of this task is still active.
<T> void	iterateWhileActive(Iterable<T> iterable, Consumer<T> consumer) Utility to iterate through a collection while checking the cancelled flag.
void	log(String message, Object... args) Writes a log message to the monitor.
void	logAsCurrentState(String message, Object... args) Logs the given message and sets it as current state.
void	markErroneous() Signals the monitor that the execution had an error.
void	setAdapter(TaskContextAdapter adapter) Installs the given adapter as monitoring adapter.
TaskContext	setJob(String job) Sets the Job component of the System String
void	setState(String newState, Object... args) Sets the new state of the current task.
TaskContext	setSubSystem(String subSystem) Sets the Sub-System component of the System String
TaskContext	setSystem(String system) Sets the System component of the System String
RateLimit	shouldUpdateState() Can be used to determine if the state should be refreshed.
String	toString()
void	trace(String message, Object... args) Writes a debug message to the monitor.

Methods inherited from class java.lang.Object

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

Field Detail

MDC_SYSTEM

public static final String MDC_SYSTEM

One the system string is changed, it will be updated in the mapped diagnostic context (MDC) using this name.

See Also:

setSystem(String), setSubSystem(String), setJob(String), Constant Field Values

Constructor Detail

TaskContext

public TaskContext()

Generates a new TaskContext.

Normally this is should only be invoked by CallContext. Use CallContext.get(Class) to obtain an instance.

Method Detail

get

public static TaskContext get()

Provides access to the TaskContext for the current thread.

This is boilerplate for CallContext.getCurrent().get(TaskContext.class)

Returns:

the task context for the current thread

log

public void log(String message,
                Object... args)

Writes a log message to the monitor.

If no monitor is available, the async logger will be used.

Parameters:

message - the message to log

args - the parameters used to format the message (see Strings.apply(String, Object...))

trace

public void trace(String message,
                  Object... args)

Writes a debug message to the monitor.

If no monitor is available, the async logger will be used.

Parameters:

message - the message to log

args - the parameters used to format the message (see Strings.apply(String, Object...))

logAsCurrentState

public void logAsCurrentState(String message,
                              Object... args)

Logs the given message and sets it as current state.

Parameters:

message - the message to log

args - the parameters used to format the message (see Strings.apply(String, Object...))

setState

public void setState(String newState,
                     Object... args)

Sets the new state of the current task.

Parameters:

newState - the message to set as state

args - the parameters used to format the state message (see Strings.apply(String, Object...))

shouldUpdateState

public RateLimit shouldUpdateState()

Can be used to determine if the state should be refreshed.

By calling shouldUpdateState().check() an inner loop can detect if a state update should be performed. This will limit the number of updates to a reasonable value.

Returns:

a rate limit which limits the number of updates to a reasonable value

markErroneous

public void markErroneous()

Signals the monitor that the execution had an error.

Although an error is signaled, this will not cancel or interrupt the execution of the task. This is merely a signal for an user or administrator that an unexpected or non-anticipated event occurred.

isActive

public boolean isActive()

Determines if the execution of this task is still active.

A task can be either stopped via the cancel() method or due to a system shutdown. In any case it is wise for a task to check this flag every once in a while to keep the overall app responsive.

Returns:

true as long as the task is expected to be executed, false otherwise

cancel

public void cancel()

Cancels the execution of this task.

Note that this will not kill the underlying thread. This will merely toggle the canceled flag. It is however the task programmers job to check this flag and interrupt / terminate all computations.

iterateWhileActive

public <T> void iterateWhileActive(Iterable<T> iterable,
                                   Consumer<T> consumer)

Utility to iterate through a collection while checking the cancelled flag.

Type Parameters:

T - the type of elements being processed

Parameters:

iterable - the collection to iterate through

consumer - the processor invoked for each element

getSystemString

public String getSystemString()

Returns the System String.

This will consist of three parts: System, Sub-System and Job. It is used to provide information which module is currently active. Therefore the System will provide a raw information which module is active. This might be HTTP for the web server or the category of an executor in Tasks.

The Sub-System will provide a more detailed information, like the class name or the name of a component which is currently active.

Finally the Job will provide a detailed information what's being currently processed. This might be the effective URI of the request being processed by the web server or the name of a file currently being imported.

Returns:

the System String with a format like System::Sub-System::Job

getSystem

public String getSystem()

Returns the System component of the System String

Returns:

the system component of the system string

See Also:

getSystemString()

setSystem

public TaskContext setSystem(String system)

Sets the System component of the System String

Parameters:

system - the new system component to set

Returns:

the task context itself for fluent method calls

See Also:

getSystemString()

getSubSystem

public String getSubSystem()

Returns the Sub-System component of the System String

Returns:

the sub system component of the system string

See Also:

getSystemString()

setSubSystem

public TaskContext setSubSystem(String subSystem)

Sets the Sub-System component of the System String

Parameters:

subSystem - the new sub system component to set

Returns:

the task context itself for fluent method calls

See Also:

getSystemString()

getJob

public String getJob()

Returns the Job component of the System String

Returns:

the job component of the system string

See Also:

getSystemString()

setJob

public TaskContext setJob(String job)

Sets the Job component of the System String

Parameters:

job - the new job component to set

Returns:

the task context itself for fluent method calls

See Also:

getSystemString()

toString

public String toString()

Overrides:

toString in class Object

getAdapter

public TaskContextAdapter getAdapter()

Returns the monitoring adapter which is currently active.

Returns:

the monitoring adapter or null if no adapter is active

setAdapter

public void setAdapter(TaskContextAdapter adapter)

Installs the given adapter as monitoring adapter.

Parameters:

adapter - the adapter to install

fork

public SubContext fork()

Description copied from interface: SubContext

Returns an instance which is used in a forked CallContext.

Specified by:

fork in interface SubContext

Returns:

either the instance itself - if can or has to be used in both threads - or clone or copy of the instance which replicates the current state

detach

public void detach()

Description copied from interface: SubContext

Gets notified if the associated CallContext is detached.

Specified by:

detach in interface SubContext