com.azure.core.util

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 Context.addData(Object, Object) method creates a new Context object that refers to its parent, forming a linked list.

Field Summary

Fields

Modifier and Type	Field and Description
static Context	NONE Signifies that no data needs to be passed to the pipeline.

Constructor Summary

Constructors

Constructor and Description
Context(Object key, Object value) Constructs a new Context object.

Method Summary

Modifier and Type	Method and Description
Context	addData(Object key, Object value) Adds a new immutable Context object with the specified key-value pair to the existing Context chain.
Optional<Object>	getData(Object key) Scans the linked-list of Context objects looking for one with the specified key.
Map<Object,Object>	getValues() Scans the linked-list of Context objects populating a Map with the values of the context.
static Context	of(Map<Object,Object> keyValues) Creates a new immutable Context object with all the keys and values provided by the input Map.

Methods inherited from class java.lang.Object

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

Field Detail

NONE

public static final Context NONE

Signifies that no data needs to be passed to the pipeline.

Constructor Detail

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 created by users can be passed to calling methods in sdk clients using Context object
 final String userParentSpan = "user-parent-span";
 
 // Create a context using the provided key and user parent span
 Context keyValueContext = new Context(PARENT_SPAN_KEY, userParentSpan);
 

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 Detail

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 send parent span information and pass additional metadata to attach to spans of the calling methods
 // using the Context object
 final String hostNameValue = "host-name-value";
 final String entityPathValue = "entity-path-value";
 final String userParentSpan = "user-parent-span";
 Context parentSpanContext = new Context(PARENT_SPAN_KEY, userParentSpan);
 
 // 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.