openconsensus.context.propagation

Interface TextFormat<V>

public interface TextFormat<V>

Injects and extracts a value as text into carriers that travel in-band across process boundaries. Values are often encoded as RPC/HTTP request headers.

When using http, the carrier of propagated data on both the client (injector) and server (extractor) side is usually an http request. Propagation is usually implemented via library- specific request interceptors, where the client-side injects values and the server-side extracts them.

Since:

0.1.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	TextFormat.Getter<C> Interface that allows a TextFormat to read propagated fields from a carrier.
static interface	TextFormat.Setter<C> Class that allows a TextFormat to set propagated fields into a carrier.

Method Summary

Modifier and Type	Method and Description
<C> V	extract(C carrier, TextFormat.Getter<C> getter) Extracts the value from upstream.
List<String>	fields() The propagation fields defined.
<C> void	inject(V value, C carrier, TextFormat.Setter<C> setter) Injects the value downstream.

Method Detail

fields

List<String> fields()

The propagation fields defined. If your carrier is reused, you should delete the fields here before calling inject(Object, Object, Setter) )}.

For example, if the carrier is a single-use or immutable request object, you don't need to clear fields as they couldn't have been set before. If it is a mutable, retryable object, successive calls should clear these fields first.

Returns:

list of fields that will be used by this formatter.

Since:

0.1.0

inject

<C> void inject(V value,
                C carrier,
                TextFormat.Setter<C> setter)

Injects the value downstream. For example, as http headers.

Type Parameters:

C - carrier of propagation fields, such as an http request

Parameters:

value - the value to be injected.

carrier - holds propagation fields. For example, an outgoing message or http request.

setter - invoked for each propagation key to add or remove.

Since:

0.1.0

extract

<C> V extract(C carrier,
              TextFormat.Getter<C> getter)

Extracts the value from upstream. For example, as http headers.

If the value could not be parsed, the underlying implementation will decide to return ether an empty value, an invalid value, or a valid value.

Type Parameters:

C - carrier of propagation fields, such as an http request.

Parameters:

carrier - holds propagation fields. For example, an outgoing message or http request.

getter - invoked for each propagation key to get.

Returns:

the extracted value.

Since:

0.1.0