Package io.grpc

Class 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.

    • 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 when namesAndValues 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 the key, value pair.
      <T> boolean remove​(Metadata.Key<T> key, T value)
      Removes the first occurrence of value for key.
      <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 as InputStreams.
      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)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • 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) and Metadata.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 names
        namesAndValues - 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 by InternalMetadata.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 when namesAndValues is null or has no elements.
      • headerCount

        int headerCount()
        Returns the total number of key-value headers in this metadata, including duplicates.
      • 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 the key, value pair. If key 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 of value for key.
        Parameters:
        key - key for value
        value - value
        Returns:
        true if value removed; false if value was not present
        Throws:
        java.lang.NullPointerException - if key or value 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 of Metadata.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 as InputStreams.

        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 or InputStreams.

        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 class java.lang.Object
      • bytesEqual

        private boolean bytesEqual​(byte[] left,
                                   byte[] right)
      • streamToBytes

        private static byte[] streamToBytes​(java.io.InputStream stream)