software.amazon.disco.agent.reflect.concurrent

Class TransactionContext

java.lang.Object

software.amazon.disco.agent.reflect.concurrent.TransactionContext

public class TransactionContext
extends java.lang.Object

Manipulation/overriding of the current TransactionContext, which identifies the current service interaction i.e. the entire enclosure of operations between the service Request and Response. By default, DiSCo chooses a GUID for this, but services consuming DiSCo may elect a different strategy for calculating this value, perhaps to give it semantics more nuanced than just 'random'. The idea is that at the earliest opportunity during the service's Activity this TransactionContext should be set. This must be before ANY downstream dependency interactions have occurred.

Constructor Summary

Constructors

Constructor and Description
TransactionContext()

Method Summary

Modifier and Type	Method and Description
static void	clear() Clear the DiSCo TransactionContext to revert to its default value, or a no-op if Agent not loaded
static int	create() Create a default UUID transaction ID
static void	destroy() Destroys the Transaction Context for this thread.
static java.lang.String	get() Get the DiSCo Transaction ID, or null if the agent is not loaded
static java.lang.Object	getMetadata(java.lang.String key) Get a value from the DiSCo metadata map, or null if the agent is not loaded
static java.util.Map<java.lang.String,java.lang.Object>	getMetadataWithTag(java.lang.String tag) Get data from the metadata map which contains the specified tag, or return null if the agent is not loaded
static java.lang.String	getUninitializedTransactionContextValue() Get the default uninitialized Transaction Context value
static boolean	isWithinCreatedContext() Test if we are currently considered to be inside a created Transaction Context or not.
static void	putMetadata(java.lang.String key, java.lang.Object value) Set a value in the DiSCo metadata map, or do nothing if the agent is not loaded
static void	removeMetadata(java.lang.String key) Remove a value in the DiSCo metadata map, or do nothing if the agent is not loaded
static void	set(java.lang.String value) Set the DiSCo Transaction ID to a specific value.
static void	setMetadataTag(java.lang.String key, java.lang.String tag) Set a tag on data from the metadata map with a tag, or do nothing if the agent is not loaded

Methods inherited from class java.lang.Object

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

Constructor Detail

TransactionContext

public TransactionContext()

Method Detail

create

public static int create()

Create a default UUID transaction ID

Returns:

the tx stack depth.

destroy

public static void destroy()

Destroys the Transaction Context for this thread. If multiple create methods were called, the same number of destroy methods should be called to clear the Transaction Context. If there are more destroy() calls than create(), this will do nothing.

set

public static void set(java.lang.String value)

Set the DiSCo Transaction ID to a specific value.

Parameters:

value - - the value to set

get

public static java.lang.String get()

Get the DiSCo Transaction ID, or null if the agent is not loaded

Returns:

- the TransactionContext value

putMetadata

public static void putMetadata(java.lang.String key,
                               java.lang.Object value)

Set a value in the DiSCo metadata map, or do nothing if the agent is not loaded

Parameters:

key - the key of the metadata

value - the metadata value

removeMetadata

public static void removeMetadata(java.lang.String key)

Remove a value in the DiSCo metadata map, or do nothing if the agent is not loaded

Parameters:

key - the key of the metadata

getMetadata

public static java.lang.Object getMetadata(java.lang.String key)

Get a value from the DiSCo metadata map, or null if the agent is not loaded

Parameters:

key - the key of the metadata

Returns:

the metadata value

setMetadataTag

public static void setMetadataTag(java.lang.String key,
                                  java.lang.String tag)

Set a tag on data from the metadata map with a tag, or do nothing if the agent is not loaded

Parameters:

key - a String to identify the data.

tag - a String that will be added to label/tag the data.

getMetadataWithTag

public static java.util.Map<java.lang.String,java.lang.Object> getMetadataWithTag(java.lang.String tag)

Get data from the metadata map which contains the specified tag, or return null if the agent is not loaded

Parameters:

tag - a String to identify the metadata objects to be returned.

Returns:

a map of metadata objects that contained the tag

clear

public static void clear()

Clear the DiSCo TransactionContext to revert to its default value, or a no-op if Agent not loaded

getUninitializedTransactionContextValue

public static java.lang.String getUninitializedTransactionContextValue()

Get the default uninitialized Transaction Context value

Returns:

- "disco_null_id"

isWithinCreatedContext

public static boolean isWithinCreatedContext()

Test if we are currently considered to be inside a created Transaction Context or not. This is a fairly coarse test just against an uninitialized Transaction Context value. Mainly this is designed to test for so-called 'steady-state', which means program behaviors which fall outside of a service activity e.g. bean initialization, and background workers which poll for rarely-changing cacheable state. This is only a heuristic though, and requires two conditions to be satisfied: 1) The service framework thread pool is not reused for non-activity tasks. The interceptors do take care to clear the transactionId after processing, but if that logic were to fail, the thread lingers with the identity previously assigned to it. 2) Service activities do not lazily initialize background workers. We assume that these are created during service startup or bean initialization. If a service activity lazily begins a background task, the identity will be propagated into the new thread, and will then resemble the activity. TODO - design a better mechanism than this. We may wish to track a pool of 'active' transaction ids for example, and extend this check. We may want to make the create()/clear() pair of operations around every activity more reliable, instead of Support package authors having to remember to do it

Returns:

true if we think we're currently inside a created Transaction Context, else false