Package io.grpc

Class Metadata.Key<T>

java.lang.Object
io.grpc.Metadata.Key<T>
Direct Known Subclasses:
Metadata.AsciiKey, Metadata.BinaryKey, Metadata.LazyStreamBinaryKey, Metadata.TrustedAsciiKey
Enclosing class:
Metadata

@Immutable public abstract static class Metadata.Key<T> extends Object
Key for metadata entries. Allows for parsing and serialization of metadata.

Valid characters in key names

Only the following ASCII characters are allowed in the names of keys:

  • digits: 0-9
  • uppercase letters: A-Z (normalized to lower)
  • lowercase letters: a-z
  • special characters: -_.

This is a strict subset of the HTTP field-name rules. Applications may not send or receive metadata with invalid key names. However, the gRPC library may preserve any metadata received even if it does not conform to the above limitations. Additionally, if metadata contains non conforming field names, they will still be sent. In this way, unknown metadata fields are parsed, serialized and preserved, but never interpreted. They are similar to protobuf unknown fields.

Note this has to be the subset of valid HTTP/2 token characters as defined in RFC7230 Section 3.2.6 and RFC5234 Section B.1

Note that a key is immutable but it may not be deeply immutable, because the key depends on its marshaller, and the marshaller can be mutable though not recommended.

See Also:
  • Field Details

    • VALID_T_CHARS

      private static final BitSet VALID_T_CHARS
      Valid characters for field names as defined in RFC7230 and RFC5234.
    • originalName

      private final String originalName
    • name

      private final String name
    • nameBytes

      private final byte[] nameBytes
    • marshaller

      private final Object marshaller
  • Constructor Details

    • Key

      private Key(String name, boolean pseudo, Object marshaller)
  • Method Details

    • of

      public static <T> Metadata.Key<T> of(String name, Metadata.BinaryMarshaller<T> marshaller)
      Creates a key for a binary header.
      Parameters:
      name - Must contain only the valid key characters as defined in the class comment. Must end with Metadata.BINARY_HEADER_SUFFIX.
    • of

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/6575") public static <T> Metadata.Key<T> of(String name, Metadata.BinaryStreamMarshaller<T> marshaller)
      Creates a key for a binary header, serializing to input streams.
      Parameters:
      name - Must contain only the valid key characters as defined in the class comment. Must end with Metadata.BINARY_HEADER_SUFFIX.
    • of

      public static <T> Metadata.Key<T> of(String name, Metadata.AsciiMarshaller<T> marshaller)
      Creates a key for an ASCII header.
      Parameters:
      name - Must contain only the valid key characters as defined in the class comment. Must not end with Metadata.BINARY_HEADER_SUFFIX
    • of

      static <T> Metadata.Key<T> of(String name, boolean pseudo, Metadata.AsciiMarshaller<T> marshaller)
    • of

      static <T> Metadata.Key<T> of(String name, boolean pseudo, Metadata.TrustedAsciiMarshaller<T> marshaller)
    • generateValidTChars

      private static BitSet generateValidTChars()
    • validateName

      private static String validateName(String n, boolean pseudo)
    • originalName

      public final String originalName()
      Returns the original name used to create this key.
    • name

      public final String name()
      Returns the normalized name for this key.
    • asciiName

      byte[] asciiName()
      Get the name as bytes using ASCII-encoding.

      The returned byte arrays must not be modified.

      This method is intended for transport use only.

    • equals

      public final boolean equals(Object o)
      Returns true if the two objects are both Keys, and their names match (case insensitive).
      Overrides:
      equals in class Object
    • hashCode

      public final int hashCode()
      Overrides:
      hashCode in class Object
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • toBytes

      abstract byte[] toBytes(T value)
      Serialize a metadata value to bytes.
      Parameters:
      value - to serialize
      Returns:
      serialized version of value
    • parseBytes

      abstract T parseBytes(byte[] serialized)
      Parse a serialized metadata value from bytes.
      Parameters:
      serialized - value of metadata to parse
      Returns:
      a parsed instance of type T
    • serializesToStreams

      boolean serializesToStreams()
      Returns whether this key will be serialized to bytes lazily.
    • getMarshaller

      @Nullable final <M> M getMarshaller(Class<M> marshallerClass)
      Gets this keys (implementation-specific) marshaller, or null if the marshaller is not of the given type.
      Parameters:
      marshallerClass - The type we expect the marshaller to be.
      Returns:
      the marshaller object for this key, or null.