Package software.amazon.disco.agent.reflect.concurrent

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

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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