@ThreadSafe public interface HttpTextFormat
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.
Specific concern values (traces, correlations, etc) will be read from the specified Context, and resulting values will be stored in a new Context upon extraction. It is
recommended to use a single Context.Key to store the entire concern data:
public static final Context.Key CONCERN_KEY = Context.key("my-concern-key");
public MyConcernPropagator implements HttpTextFormat {
public <C> void inject(Context context, C carrier, Setter<C> setter) {
Object concern = CONCERN_KEY.get(context);
// Use concern in the specified context to propagate data.
}
public <C> Context extract(Context context, C carrier, Getter<C> setter) {
// Use setter to get the data from the carrier.
return context.withValue(CONCERN_KEY, concern);
}
}
| Modifier and Type | Interface and Description |
|---|---|
static interface |
HttpTextFormat.Getter<C>
Interface that allows a
HttpTextFormat to read propagated fields from a carrier. |
static interface |
HttpTextFormat.Setter<C>
Class that allows a
HttpTextFormat to set propagated fields into a carrier. |
| Modifier and Type | Method and Description |
|---|---|
<C> io.grpc.Context |
extract(io.grpc.Context context,
C carrier,
HttpTextFormat.Getter<C> getter)
Extracts the value from upstream.
|
List<String> |
fields()
The propagation fields defined.
|
<C> void |
inject(io.grpc.Context context,
C carrier,
HttpTextFormat.Setter<C> setter)
Injects the value downstream, for example as HTTP headers.
|
List<String> fields()
inject(Context, 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.
<C> void inject(io.grpc.Context context,
@Nullable
C carrier,
HttpTextFormat.Setter<C> setter)
HttpTextFormat.Setter, in which case that null
will be passed to the HttpTextFormat.Setter implementation.C - carrier of propagation fields, such as an http requestcontext - the Context containing 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.<C> io.grpc.Context extract(io.grpc.Context context,
C carrier,
HttpTextFormat.Getter<C> getter)
If the value could not be parsed, the underlying implementation will decide to set an object
representing either an empty value, an invalid value, or a valid value. Implementation must not
set null.
C - carrier of propagation fields, such as an http request.context - the Context used to store the extracted value.carrier - holds propagation fields. For example, an outgoing message or http request.getter - invoked for each propagation key to get.Context containing the extracted value.