org.glassfish.diagnostics.context

Interface Context

All Known Implementing Classes:

ContextImpl

public interface Context

The diagnostics Context is the object through which diagnostics data relevant to the current task are read and written. A task is a unit of work being executed by the java process. Examples include

• responding to an external stimulus such as a simple http request or web-service request
• executing a scheduled job

A parent task can create sub-tasks the completion of which may or may not affect the execution of the parent task. The diagnostics Context of the parent task will propagate to the child sub-tasks. Diagnostics data include:

• Location: Location provides correlation between a task and its sub-task(s)
• Name-value pairs: Arbitrary name-value pairs that may be reported in diagnostics features such as logging, flight recordings, request sampling and tracing and so on.
  • Name: The name should use the standard java naming convention including package name. The name should be sufficiently clear that consumers of the data (e.g. the readers of log files, i.e. developers!) have some good starting point when interpreting the diagnostics data.
  • Value: The value should be as concise as possible.
  Only those name-value pairs marked for propagation will propagate to the diagnostics Contexts of sub-tasks. It is generally the case that data associated with a particular name will either always propagate or always not propagate - i.e. it is either usefully shared with child Contexts or only makes sense if kept private to one Context.

The diagnostics Context of the currently executing task can be obtained from the ContextManager.

See Also:

Location

Method Summary

Modifier and Type	Method and Description
<T> T	get(String name) Get a named value from this Context.
Location	getLocation() Get the Location of this Context.
<T> T	put(String name, Number value, boolean propagates) Put a named value in this Context.
<T> T	put(String name, String value, boolean propagates) Put a named value in this Context.
<T> T	remove(String name) Remove the named value from this Context.

Method Detail

getLocation

Location getLocation()

Get the Location of this Context.

put

<T> T put(String name,
          String value,
          boolean propagates)

Put a named value in this Context.

Parameters:

name - The name of the item of data.

value - The value of item of data.

propagates - If true then the data item will be propagated.

Returns:

The previous value associated with this name (if there is one).

put

<T> T put(String name,
          Number value,
          boolean propagates)

Put a named value in this Context.

Parameters:

name - The name of the item of data.

value - The value of item of data.

propagates - If true then the data item will be propagated.

Returns:

The previous value associated with this name (if there is one).

remove

<T> T remove(String name)

Remove the named value from this Context.

Parameters:

name - The name of the item of data.

Returns:

The value being removed if there is one, otherwise null.

get

<T> T get(String name)

Get a named value from this Context.

Parameters:

name - The name of the item of data.

Returns:

The value associated with this name if there is one, otherwise null.