Package io.grpc

Class 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 java.lang.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:
    Wire Spec, RFC7230, RFC5234
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.Object marshaller  
      private java.lang.String name  
      private byte[] nameBytes  
      private java.lang.String originalName  
      private static java.util.BitSet VALID_T_CHARS
      Valid characters for field names as defined in RFC7230 and RFC5234.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Key​(java.lang.String name, boolean pseudo, java.lang.Object marshaller)  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) byte[] asciiName()
      Get the name as bytes using ASCII-encoding.
      boolean equals​(java.lang.Object o)
      Returns true if the two objects are both Keys, and their names match (case insensitive).
      private static java.util.BitSet generateValidTChars()  
      (package private) <M> M getMarshaller​(java.lang.Class<M> marshallerClass)
      Gets this keys (implementation-specific) marshaller, or null if the marshaller is not of the given type.
      int hashCode()  
      java.lang.String name()
      Returns the normalized name for this key.
      (package private) static <T> Metadata.Key<T> of​(java.lang.String name, boolean pseudo, Metadata.AsciiMarshaller<T> marshaller)  
      (package private) static <T> Metadata.Key<T> of​(java.lang.String name, boolean pseudo, Metadata.TrustedAsciiMarshaller<T> marshaller)  
      static <T> Metadata.Key<T> of​(java.lang.String name, Metadata.AsciiMarshaller<T> marshaller)
      Creates a key for an ASCII header.
      static <T> Metadata.Key<T> of​(java.lang.String name, Metadata.BinaryMarshaller<T> marshaller)
      Creates a key for a binary header.
      static <T> Metadata.Key<T> of​(java.lang.String name, Metadata.BinaryStreamMarshaller<T> marshaller)
      Creates a key for a binary header, serializing to input streams.
      java.lang.String originalName()
      Returns the original name used to create this key.
      (package private) abstract T parseBytes​(byte[] serialized)
      Parse a serialized metadata value from bytes.
      (package private) boolean serializesToStreams()
      Returns whether this key will be serialized to bytes lazily.
      (package private) abstract byte[] toBytes​(T value)
      Serialize a metadata value to bytes.
      java.lang.String toString()  
      private static java.lang.String validateName​(java.lang.String n, boolean pseudo)  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • VALID_T_CHARS

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

        private final java.lang.String originalName
      • name

        private final java.lang.String name
      • nameBytes

        private final byte[] nameBytes
      • marshaller

        private final java.lang.Object marshaller
    • Constructor Detail

      • Key

        private Key​(java.lang.String name,
                    boolean pseudo,
                    java.lang.Object marshaller)
    • Method Detail

      • generateValidTChars

        private static java.util.BitSet generateValidTChars()
      • validateName

        private static java.lang.String validateName​(java.lang.String n,
                                                     boolean pseudo)
      • originalName

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

        public final java.lang.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​(java.lang.Object o)
        Returns true if the two objects are both Keys, and their names match (case insensitive).
        Overrides:
        equals in class java.lang.Object
      • hashCode

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

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.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​(java.lang.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.