Class Context

java.lang.Object
com.azure.core.util.Context

public class Context extends Object
Context offers a means of passing arbitrary data (key-value pairs) to pipeline policies. Most applications do not need to pass arbitrary data to the pipeline and can pass Context.NONE or null.

Each context object is immutable. The addData(Object, Object) method creates a new Context object that refers to its parent, forming a linked list.

  • Field Details

    • NONE

      public static final Context NONE
      Signifies that no data needs to be passed to the pipeline.
  • Constructor Details

    • Context

      public Context(Object key, Object value)
      Constructs a new Context object.

      Code samples

       // Create an empty context having no data
       Context emptyContext = Context.NONE;
      
       // Tracing spans or other properties defined by users can be passed
       // to calling methods in sdk clients using Context object.
       Context keyValueContext = new Context(USER_SPAN_NAME_KEY, "span-name");
      
       // OpenTelemetry context can be optionally passed using PARENT_TRACE_CONTEXT_KEY
       // when OpenTelemetry context is not provided explicitly, ambient
       // io.opentelemetry.context.Context.current() is used
      
       // Context contextWithSpan = new Context(PARENT_TRACE_CONTEXT_KEY, openTelemetryContext);
       
      Parameters:
      key - The key with which the specified value should be associated.
      value - The value to be associated with the specified key.
      Throws:
      IllegalArgumentException - If key is null.
  • Method Details

    • addData

      public Context addData(Object key, Object value)
      Adds a new immutable Context object with the specified key-value pair to the existing Context chain.

      Code samples

       // Users can pass parent trace context information and additional metadata to attach to spans created by SDKs
       // using the com.azure.core.util.Context object.
       final String hostNameValue = "host-name-value";
       final String entityPathValue = "entity-path-value";
      
       // TraceContext represents a tracing solution context type - io.opentelemetry.context.Context for OpenTelemetry.
       final TraceContext parentContext = TraceContext.root();
       Context parentSpanContext = new Context(PARENT_TRACE_CONTEXT_KEY, parentContext);
      
       // Add a new key value pair to the existing context object.
       Context updatedContext = parentSpanContext.addData(HOST_NAME_KEY, hostNameValue)
           .addData(ENTITY_PATH_KEY, entityPathValue);
      
       // Both key values found on the same updated context object
       System.out.printf("Hostname value: %s%n", updatedContext.getData(HOST_NAME_KEY).get());
       System.out.printf("Entity Path value: %s%n", updatedContext.getData(ENTITY_PATH_KEY).get());
       
      Parameters:
      key - The key with which the specified value should be associated.
      value - The value to be associated with the specified key.
      Returns:
      the new Context object containing the specified pair added to the set of pairs.
      Throws:
      IllegalArgumentException - If key is null.
    • of

      public static Context of(Map<Object,Object> keyValues)
      Creates a new immutable Context object with all the keys and values provided by the input Map.

      Code samples

       final String key1 = "Key1";
       final String value1 = "first-value";
       Map<Object, Object> keyValueMap = new HashMap<>();
       keyValueMap.put(key1, value1);
      
       // Create a context using the provided key value pair map
       Context keyValueContext = Context.of(keyValueMap);
       System.out.printf("Key1 value %s%n", keyValueContext.getData(key1).get());
       
      Parameters:
      keyValues - The input key value pairs that will be added to this context.
      Returns:
      Context object containing all the key-value pairs in the input map.
      Throws:
      IllegalArgumentException - If keyValues is null or empty
    • getData

      public Optional<Object> getData(Object key)
      Scans the linked-list of Context objects looking for one with the specified key. Note that the first key found, i.e. the most recently added, will be returned.

      Code samples

       final String key1 = "Key1";
       final String value1 = "first-value";
      
       // Create a context object with given key and value
       Context context = new Context(key1, value1);
      
       // Look for the specified key in the returned context object
       Optional<Object> optionalObject = context.getData(key1);
       if (optionalObject.isPresent()) {
           System.out.printf("Key1 value: %s%n", optionalObject.get());
       } else {
           System.out.println("Key1 does not exist or have data.");
       }
       
      Parameters:
      key - The key to search for.
      Returns:
      The value of the specified key if it exists.
      Throws:
      IllegalArgumentException - If key is null.
    • getValues

      public Map<Object,Object> getValues()
      Scans the linked-list of Context objects populating a Map with the values of the context.

      Code samples

       final String key1 = "Key1";
       final String value1 = "first-value";
       final String key2 = "Key2";
       final String value2 = "second-value";
      
       Context context = new Context(key1, value1)
           .addData(key2, value2);
      
       Map<Object, Object> contextValues = context.getValues();
       if (contextValues.containsKey(key1)) {
           System.out.printf("Key1 value: %s%n", contextValues.get(key1));
       } else {
           System.out.println("Key1 does not exist.");
       }
      
       if (contextValues.containsKey(key2)) {
           System.out.printf("Key2 value: %s%n", contextValues.get(key2));
       } else {
           System.out.println("Key2 does not exist.");
       }
       
      Returns:
      A map containing all values of the context linked-list.