Class Metadata
- java.lang.Object
-
- io.grpc.Metadata
-
@NotThreadSafe public final class Metadata extends java.lang.Object
Provides access to read and write metadata values to be exchanged during a call.Keys are allowed to be associated with more than one value.
This class is not thread safe, implementations should ensure that header reads and writes do not occur in multiple threads concurrently.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
Metadata.AsciiKey<T>
static interface
Metadata.AsciiMarshaller<T>
Marshaller for metadata values that are serialized into ASCII strings.private static class
Metadata.BinaryKey<T>
static interface
Metadata.BinaryMarshaller<T>
Marshaller for metadata values that are serialized into raw binary.static interface
Metadata.BinaryStreamMarshaller<T>
Marshaller for metadata values that are serialized to an InputStream.private class
Metadata.IterableAt<T>
static class
Metadata.Key<T>
Key for metadata entries.private static class
Metadata.LazyStreamBinaryKey<T>
A binary key for values which should be serialized lazily toInputStream
s.(package private) static class
Metadata.LazyValue<T>
Internal holder for values which are serialized/de-serialized lazily.private static class
Metadata.TrustedAsciiKey<T>
(package private) static interface
Metadata.TrustedAsciiMarshaller<T>
A specialized plain ASCII marshaller.
-
Field Summary
Fields Modifier and Type Field Description static Metadata.AsciiMarshaller<java.lang.String>
ASCII_STRING_MARSHALLER
Simple metadata marshaller that encodes strings as is.(package private) static com.google.common.io.BaseEncoding
BASE64_ENCODING_OMIT_PADDING
static Metadata.BinaryMarshaller<byte[]>
BINARY_BYTE_MARSHALLER
Simple metadata marshaller that encodes bytes as is.static java.lang.String
BINARY_HEADER_SUFFIX
All binary headers should have this suffix in their names.private static java.util.logging.Logger
logger
private java.lang.Object[]
namesAndValues
private int
size
-
Constructor Summary
Constructors Constructor Description Metadata()
Constructor called by the application layer when it wants to send metadata.Metadata(byte[]... binaryValues)
Constructor called by the transport layer when it receives binary metadata.Metadata(int usedNames, byte[]... binaryValues)
Constructor called by the transport layer when it receives binary metadata.Metadata(int usedNames, java.lang.Object[] namesAndValues)
Constructor called by the transport layer when it receives partially-parsed metadata.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private boolean
bytesEqual(byte[] left, byte[] right)
private int
cap()
boolean
containsKey(Metadata.Key<?> key)
Returns true if a value is defined for the given key.<T> void
discardAll(Metadata.Key<T> key)
Remove all values for the given key without returning them.private void
expand(int newCapacity)
<T> T
get(Metadata.Key<T> key)
Returns the last metadata entry added with the name 'name' parsed as T.<T> java.lang.Iterable<T>
getAll(Metadata.Key<T> key)
Returns all the metadata entries named 'name', in the order they were received, parsed as T, or null if there are none.(package private) int
headerCount()
Returns the total number of key-value headers in this metadata, including duplicates.private boolean
isEmpty()
checks whennamesAndValues
is null or has no elements.java.util.Set<java.lang.String>
keys()
Returns set of all keys in store.private int
len()
private void
maybeExpand()
void
merge(Metadata other)
Perform a simple merge of two sets of metadata.void
merge(Metadata other, java.util.Set<Metadata.Key<?>> keys)
Merge values from the given set of keys into this set of metadata.private byte[]
name(int i)
private void
name(int i, byte[] name)
<T> void
put(Metadata.Key<T> key, T value)
Adds thekey, value
pair.<T> boolean
remove(Metadata.Key<T> key, T value)
Removes the first occurrence ofvalue
forkey
.<T> java.lang.Iterable<T>
removeAll(Metadata.Key<T> key)
Remove all values for the given key.(package private) byte[][]
serialize()
Serialize all the metadata entries.(package private) java.lang.Object[]
serializePartial()
Serializes all metadata entries, leaving some values asInputStream
s.private static byte[]
streamToBytes(java.io.InputStream stream)
java.lang.String
toString()
private java.lang.Object
value(int i)
private void
value(int i, byte[] value)
private void
value(int i, java.lang.Object value)
private byte[]
valueAsBytes(int i)
private java.lang.Object
valueAsBytesOrStream(int i)
private <T> T
valueAsT(int i, Metadata.Key<T> key)
-
-
-
Field Detail
-
logger
private static final java.util.logging.Logger logger
-
BINARY_HEADER_SUFFIX
public static final java.lang.String BINARY_HEADER_SUFFIX
All binary headers should have this suffix in their names. Vice versa.Its value is
"-bin"
. An ASCII header's name must not end with this.- See Also:
- Constant Field Values
-
BINARY_BYTE_MARSHALLER
public static final Metadata.BinaryMarshaller<byte[]> BINARY_BYTE_MARSHALLER
Simple metadata marshaller that encodes bytes as is.This should be used when raw bytes are favored over un-serialized version of object. Can be helpful in situations where more processing to bytes is needed on application side, avoids double encoding/decoding.
Both
Metadata.BinaryMarshaller.toBytes(T)
andMetadata.BinaryMarshaller.parseBytes(byte[])
methods do not return a copy of the byte array. Do _not_ modify the byte arrays of either the arguments or return values.
-
ASCII_STRING_MARSHALLER
public static final Metadata.AsciiMarshaller<java.lang.String> ASCII_STRING_MARSHALLER
Simple metadata marshaller that encodes strings as is.This should be used with ASCII strings that only contain the characters listed in the class comment of
Metadata.AsciiMarshaller
. Otherwise the output may be considered invalid and discarded by the transport, or the call may fail.
-
BASE64_ENCODING_OMIT_PADDING
static final com.google.common.io.BaseEncoding BASE64_ENCODING_OMIT_PADDING
-
namesAndValues
private java.lang.Object[] namesAndValues
-
size
private int size
-
-
Constructor Detail
-
Metadata
Metadata(byte[]... binaryValues)
Constructor called by the transport layer when it receives binary metadata. Metadata will mutate the passed in array.
-
Metadata
Metadata(int usedNames, byte[]... binaryValues)
Constructor called by the transport layer when it receives binary metadata. Metadata will mutate the passed in array.- Parameters:
usedNames
- the number of names
-
Metadata
Metadata(int usedNames, java.lang.Object[] namesAndValues)
Constructor called by the transport layer when it receives partially-parsed metadata. Metadata will mutate the passed in array.- Parameters:
usedNames
- the number of namesnamesAndValues
- an array of interleaved names and values, with each name (at even indices) represented by a byte array, and values (at odd indices) as described byInternalMetadata.newMetadataWithParsedValues(int, java.lang.Object[])
.
-
Metadata
public Metadata()
Constructor called by the application layer when it wants to send metadata.
-
-
Method Detail
-
name
private byte[] name(int i)
-
name
private void name(int i, byte[] name)
-
value
private java.lang.Object value(int i)
-
value
private void value(int i, byte[] value)
-
value
private void value(int i, java.lang.Object value)
-
valueAsBytes
private byte[] valueAsBytes(int i)
-
valueAsBytesOrStream
private java.lang.Object valueAsBytesOrStream(int i)
-
valueAsT
private <T> T valueAsT(int i, Metadata.Key<T> key)
-
cap
private int cap()
-
len
private int len()
-
isEmpty
private boolean isEmpty()
checks whennamesAndValues
is null or has no elements.
-
headerCount
int headerCount()
Returns the total number of key-value headers in this metadata, including duplicates.
-
containsKey
public boolean containsKey(Metadata.Key<?> key)
Returns true if a value is defined for the given key.This is done by linear search, so if it is followed by
get(io.grpc.Metadata.Key<T>)
orgetAll(io.grpc.Metadata.Key<T>)
, prefer calling them directly and checking the return value againstnull
.
-
get
@Nullable public <T> T get(Metadata.Key<T> key)
Returns the last metadata entry added with the name 'name' parsed as T.- Returns:
- the parsed metadata entry or null if there are none.
-
getAll
@Nullable public <T> java.lang.Iterable<T> getAll(Metadata.Key<T> key)
Returns all the metadata entries named 'name', in the order they were received, parsed as T, or null if there are none. The iterator is not guaranteed to be "live." It may or may not be accurate if Metadata is mutated.
-
keys
public java.util.Set<java.lang.String> keys()
Returns set of all keys in store.- Returns:
- unmodifiable Set of keys
-
put
public <T> void put(Metadata.Key<T> key, T value)
Adds thekey, value
pair. Ifkey
already has values,value
is added to the end. Duplicate values for the same key are permitted.- Throws:
java.lang.NullPointerException
- if key or value is null
-
maybeExpand
private void maybeExpand()
-
expand
private void expand(int newCapacity)
-
remove
public <T> boolean remove(Metadata.Key<T> key, T value)
Removes the first occurrence ofvalue
forkey
.- Parameters:
key
- key for valuevalue
- value- Returns:
true
ifvalue
removed;false
ifvalue
was not present- Throws:
java.lang.NullPointerException
- ifkey
orvalue
is null
-
removeAll
public <T> java.lang.Iterable<T> removeAll(Metadata.Key<T> key)
Remove all values for the given key. If there were no values,null
is returned.
-
discardAll
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/4691") public <T> void discardAll(Metadata.Key<T> key)
Remove all values for the given key without returning them. This is a minor performance optimization if you do not need the previous values.
-
serialize
@Nullable byte[][] serialize()
Serialize all the metadata entries.It produces serialized names and values interleaved. result[i*2] are names, while result[i*2+1] are values.
Names are ASCII string bytes that contains only the characters listed in the class comment of
Metadata.Key
. If the name ends with"-bin"
, the value can be raw binary. Otherwise, the value must contain only characters listed in the class comments ofMetadata.AsciiMarshaller
The returned individual byte arrays must not be modified. However, the top level array may be modified.
This method is intended for transport use only.
-
serializePartial
@Nullable java.lang.Object[] serializePartial()
Serializes all metadata entries, leaving some values asInputStream
s.Produces serialized names and values interleaved. result[i*2] are names, while result[i*2+1] are values.
Names are byte arrays as described according to the
serialize()
method. Values are either byte arrays orInputStream
s.This method is intended for transport use only.
-
merge
public void merge(Metadata other)
Perform a simple merge of two sets of metadata.This is a purely additive operation, because a single key can be associated with multiple values.
-
merge
public void merge(Metadata other, java.util.Set<Metadata.Key<?>> keys)
Merge values from the given set of keys into this set of metadata. If a key is present in keys, then all of the associated values will be copied over.- Parameters:
other
- The source of the new key values.keys
- The subset of matching key we want to copy, if they exist in the source.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
bytesEqual
private boolean bytesEqual(byte[] left, byte[] right)
-
streamToBytes
private static byte[] streamToBytes(java.io.InputStream stream)
-
-