io.grpc

Class Metadata

java.lang.Object

io.grpc.Metadata

@NotThreadSafe
public final class Metadata
extends Object

Provides access to read and write metadata values to be exchanged during a call.

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 and Description
static interface	Metadata.AsciiMarshaller<T> Marshaller for metadata values that are serialized into ASCII strings that contain only following characters: Space: 0x20, but must not be at the beginning or at the end of the value. ASCII visible characters (0x21-0x7E).
static interface	Metadata.BinaryMarshaller<T> Marshaller for metadata values that are serialized into raw binary.
static class	Metadata.Key<T> Key for metadata entries.

Field Summary

Fields

Modifier and Type	Field and Description
static Metadata.AsciiMarshaller<String>	ASCII_STRING_MARSHALLER Simple metadata marshaller that encodes strings as is.
static String	BINARY_HEADER_SUFFIX All binary headers should have this suffix in their names.

Constructor Summary

Constructors

Constructor and 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.

Method Summary

Modifier and Type	Method and Description
boolean	containsKey(Metadata.Key<?> key) Returns true if a value is defined for the given key.
<T> T	get(Metadata.Key<T> key) Returns the last metadata entry added with the name 'name' parsed as T.
<T> 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.
Set<String>	keys() Returns set of all keys in store.
void	merge(Metadata other) Perform a simple merge of two sets of metadata.
void	merge(Metadata other, Set<Metadata.Key<?>> keys) Merge values for the given set of keys into this set of metadata.
<T> void	put(Metadata.Key<T> key, T value) Adds the key, value pair.
<T> boolean	remove(Metadata.Key<T> key, T value) Removes the first occurence of value for key.
<T> Iterable<T>	removeAll(Metadata.Key<T> key) Remove all values for the given key.
byte[][]	serialize() Serialize all the metadata entries.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

BINARY_HEADER_SUFFIX

public static final 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

ASCII_STRING_MARSHALLER

public static final Metadata.AsciiMarshaller<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.

Constructor Detail

Metadata

@Internal
public Metadata(byte[]... binaryValues)

Constructor called by the transport layer when it receives binary metadata.

Metadata

public Metadata()

Constructor called by the application layer when it wants to send metadata.

Method Detail

containsKey

public boolean containsKey(Metadata.Key<?> key)

Returns true if a value is defined for the given key.

get

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

public <T> 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 Set<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 the key, value pair. If key already has values, value is added to the end. Duplicate values for the same key are permitted.

Throws:

NullPointerException - if key or value is null

remove

public <T> boolean remove(Metadata.Key<T> key,
                          T value)

Removes the first occurence of value for key.

Parameters:

key - key for value

value - value

Returns:

true if value removed; false if value was not present

Throws:

NullPointerException - if key or value is null

removeAll

public <T> Iterable<T> removeAll(Metadata.Key<T> key)

Remove all values for the given key. If there were no values, null is returned.

serialize

@Internal
public 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 of Metadata.AsciiMarshaller

The returned byte arrays must not be modified.

This method is intended for transport use only.

merge

public void merge(Metadata other)

Perform a simple merge of two sets of metadata.

merge

public void merge(Metadata other,
                  Set<Metadata.Key<?>> keys)

Merge values for the given set of keys into this set of metadata.

toString

public String toString()

Overrides:

toString in class Object