blob: e07afd12c9ce03ce2885cea5e5971c63321a5bd5 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
/*
* Copyright 2017, OpenCensus Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.opencensus.trace.propagation;
import static com.google.common.base.Preconditions.checkNotNull;
import io.opencensus.trace.SpanContext;
import java.text.ParseException;
/**
* This is a helper class for {@link SpanContext} propagation on the wire using binary encoding.
*
* <p>Example of usage on the client:
*
* <pre>{@code
* private static final Tracer tracer = Tracing.getTracer();
* private static final BinaryFormat binaryFormat =
* Tracing.getPropagationComponent().getBinaryFormat();
* void onSendRequest() {
* try (Scope ss = tracer.spanBuilder("Sent.MyRequest").startScopedSpan()) {
* byte[] binaryValue = binaryFormat.toByteArray(tracer.getCurrentContext().context());
* // Send the request including the binaryValue and wait for the response.
* }
* }
* }</pre>
*
* <p>Example of usage on the server:
*
* <pre>{@code
* private static final Tracer tracer = Tracing.getTracer();
* private static final BinaryFormat binaryFormat =
* Tracing.getPropagationComponent().getBinaryFormat();
* void onRequestReceived() {
* // Get the binaryValue from the request.
* SpanContext spanContext = SpanContext.INVALID;
* try {
* if (binaryValue != null) {
* spanContext = binaryFormat.fromByteArray(binaryValue);
* }
* } catch (SpanContextParseException e) {
* // Maybe log the exception.
* }
* try (Scope ss =
* tracer.spanBuilderWithRemoteParent("Recv.MyRequest", spanContext).startScopedSpan()) {
* // Handle request and send response back.
* }
* }
* }</pre>
*
* @since 0.5
*/
public abstract class BinaryFormat {
static final NoopBinaryFormat NOOP_BINARY_FORMAT = new NoopBinaryFormat();
/**
* @deprecated use {@link #toByteArray(SpanContext)}.
* @param spanContext the {@code SpanContext} to serialize.
* @return the serialized binary value.
* @throws NullPointerException if the {@code spanContext} is {@code null}.
* @since 0.5
*/
@Deprecated
public byte[] toBinaryValue(SpanContext spanContext) {
return toByteArray(spanContext);
}
/**
* Serializes a {@link SpanContext} into a byte array using the binary format.
*
* @param spanContext the {@code SpanContext} to serialize.
* @return the serialized binary value.
* @throws NullPointerException if the {@code spanContext} is {@code null}.
* @since 0.7
*/
public byte[] toByteArray(SpanContext spanContext) {
// Implementation must override this method.
return toBinaryValue(spanContext);
}
/**
* @deprecated use {@link #fromByteArray(byte[])}.
* @param bytes a binary encoded buffer from which the {@code SpanContext} will be parsed.
* @return the parsed {@code SpanContext}.
* @throws NullPointerException if the {@code input} is {@code null}.
* @throws ParseException if the version is not supported or the input is invalid
* @since 0.5
*/
@Deprecated
public SpanContext fromBinaryValue(byte[] bytes) throws ParseException {
try {
return fromByteArray(bytes);
} catch (SpanContextParseException e) {
throw new ParseException(e.toString(), 0);
}
}
/**
* Parses the {@link SpanContext} from a byte array using the binary format.
*
* @param bytes a binary encoded buffer from which the {@code SpanContext} will be parsed.
* @return the parsed {@code SpanContext}.
* @throws NullPointerException if the {@code input} is {@code null}.
* @throws SpanContextParseException if the version is not supported or the input is invalid
* @since 0.7
*/
public SpanContext fromByteArray(byte[] bytes) throws SpanContextParseException {
// Implementation must override this method.
try {
return fromBinaryValue(bytes);
} catch (ParseException e) {
throw new SpanContextParseException("Error while parsing.", e);
}
}
/**
* Returns the no-op implementation of the {@code BinaryFormat}.
*
* @return the no-op implementation of the {@code BinaryFormat}.
*/
static BinaryFormat getNoopBinaryFormat() {
return NOOP_BINARY_FORMAT;
}
private static final class NoopBinaryFormat extends BinaryFormat {
@Override
public byte[] toByteArray(SpanContext spanContext) {
checkNotNull(spanContext, "spanContext");
return new byte[0];
}
@Override
public SpanContext fromByteArray(byte[] bytes) {
checkNotNull(bytes, "bytes");
return SpanContext.INVALID;
}
private NoopBinaryFormat() {}
}
}
|
