Interface Metadata

  • All Superinterfaces:
    java.lang.Iterable<Metadata.MetadataEntry>

    public interface Metadata
    extends java.lang.Iterable<Metadata.MetadataEntry>
    Transport specific metadata.

    The exact semantics of how metadata is handled depends on the underlying transport. This API exposes case insensitive lookups on metadata, but maintains the original case of the keys as received or inserted. If case matters, the iterator should be used to access elements.

    Multiple values are also supported per key, if the underlying transport does not support multiple values per key, which value will be used is undefined.

    Metadata can either have a string or a binary value. If the underlying transport doesn't support one or the other, how those values are handled is undefined - eg, text values may be UTF-8 encoded in binary, or binary values may be Base64 encoded, it depends on the transport.

    This API maintains the order of entries, but the underlying transport may not.

    Implementations of this class should be immutable, all update operations should return a copy of the metadata.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  Metadata.MetadataEntry
      A metadata entry.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Metadata EMPTY
      An empty Metadata object.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      Metadata add​(java.lang.String key, java.lang.String value)
      Add the string value for the given key.
      Metadata addBinary​(java.lang.String key, java.nio.ByteBuffer value)
      Add the binary value for the given key.
      CloudEvent asCloudEvent()
      Return a CloudEvent representation of this Metadata.
      CloudEvent asCloudEvent​(java.lang.String id, java.net.URI source, java.lang.String type)
      Convert this metadata to a CloudEvent, adding the given required CloudEvent fields.
      Metadata clear()
      Clear all metadata entries.
      java.util.Optional<java.lang.String> get​(java.lang.String key)
      Get the string value for the given key, if found.
      java.util.List<java.lang.String> getAll​(java.lang.String key)
      Get all the string values for a given key.
      java.util.List<java.lang.String> getAllKeys()
      Get all the keys for all the entries.
      java.util.Optional<java.nio.ByteBuffer> getBinary​(java.lang.String key)
      Get the binary value for the given key, if found.
      java.util.List<java.nio.ByteBuffer> getBinaryAll​(java.lang.String key)
      Get all the binary values for a given key.
      boolean has​(java.lang.String key)
      Check whether this metadata has a entry for the given key.
      boolean isCloudEvent()
      Whether this metadata is also a CloudEvent.
      Metadata remove​(java.lang.String key)
      Remove all metadata entries with the given key.
      Metadata set​(java.lang.String key, java.lang.String value)
      Set the string value for the given key.
      Metadata setBinary​(java.lang.String key, java.nio.ByteBuffer value)
      Set the binary value for the given key.
      • Methods inherited from interface java.lang.Iterable

        forEach, iterator, spliterator
    • Field Detail

      • EMPTY

        static final Metadata EMPTY
        An empty Metadata object.
    • Method Detail

      • get

        java.util.Optional<java.lang.String> get​(java.lang.String key)
        Get the string value for the given key, if found.

        If the entry is a binary entry, nothing will be returned.

        The key lookup is case insensitive. If multiple entries with the same key are present, the first string entry will be returned.

        Parameters:
        key - The key to lookup.
        Returns:
        The value, if found.
      • getAll

        java.util.List<java.lang.String> getAll​(java.lang.String key)
        Get all the string values for a given key.

        Binary values will be ignored. The key lookup is case insensitive.

        Parameters:
        key - The key to lookup.
        Returns:
        A list of all the string values for the given key.
      • getBinary

        java.util.Optional<java.nio.ByteBuffer> getBinary​(java.lang.String key)
        Get the binary value for the given key, if found.

        If the entry is a string entry, nothing will be returned.

        The key lookup is case insensitive. If multiple entries with the same key are present, the first binary entry will be returned.

        Parameters:
        key - The key to lookup.
        Returns:
        The value, if found.
      • getBinaryAll

        java.util.List<java.nio.ByteBuffer> getBinaryAll​(java.lang.String key)
        Get all the binary values for a given key.

        String values will be ignored. The key lookup is case insensitive.

        Parameters:
        key - The key to lookup.
        Returns:
        A list of all the binary values for the given key.
      • has

        boolean has​(java.lang.String key)
        Check whether this metadata has a entry for the given key.

        The key lookup will be case insensitive.

        Parameters:
        key - The key to lookup.
        Returns:
        True if an entry for the given key exists, otherwise false.
      • getAllKeys

        java.util.List<java.lang.String> getAllKeys()
        Get all the keys for all the entries.

        This list may contain duplicate keys if there are multiple entries with the same key.

        The case of the keys will be the case as passed from the proxy or from other APIs.

        Returns:
        A list of all the keys in this metadata.
      • set

        Metadata set​(java.lang.String key,
                     java.lang.String value)
        Set the string value for the given key.

        This will replace any existing entries that case insensitively match the given key.

        This method does not modify this Metadata object, it returns a copy of this Metadata object with the entry set.

        Parameters:
        key - The key to set.
        value - The value to set.
        Returns:
        A copy of this Metadata object with the entry set.
      • setBinary

        Metadata setBinary​(java.lang.String key,
                           java.nio.ByteBuffer value)
        Set the binary value for the given key.

        This will replace any existing entries that case insensitively match the given key.

        This method does not modify this Metadata object, it returns a copy of this Metadata object with the entry set.

        Parameters:
        key - The key to set.
        value - The value to set.
        Returns:
        A copy of this Metadata object with the entry set.
      • add

        Metadata add​(java.lang.String key,
                     java.lang.String value)
        Add the string value for the given key.

        This will not replace any existing entries, it will simply append the entry to the end of the list.

        This method does not modify this Metadata object, it returns a copy of this Metadata object with the entry added.

        Parameters:
        key - The key to add.
        value - The value to add.
        Returns:
        A copy of this Metadata object with the entry added.
      • addBinary

        Metadata addBinary​(java.lang.String key,
                           java.nio.ByteBuffer value)
        Add the binary value for the given key.

        This will not replace any existing entries, it will simply append the entry to the end of the list.

        This method does not modify this Metadata object, it returns a copy of this Metadata object with the entry added.

        Parameters:
        key - The key to add.
        value - The value to add.
        Returns:
        A copy of this Metadata object with the entry added.
      • remove

        Metadata remove​(java.lang.String key)
        Remove all metadata entries with the given key.

        The key will be matched against entries case insensitively.

        This method does not modify this Metadata object, it returns a copy of this Metadata object with the entries removed.

        Parameters:
        key - The key to remove.
        Returns:
        A copy of this Metadata object with the entries removed.
      • clear

        Metadata clear()
        Clear all metadata entries.

        This method does not modify this Metadata object, it returns an empty Metadata object.

        Returns:
        An empty metadata object.
      • isCloudEvent

        boolean isCloudEvent()
        Whether this metadata is also a CloudEvent.

        This will return true if all of the required CloudEvent fields are set, that is, the specversion, id, source and type fields.

        Returns:
        True if the CloudEvent required attributes are set in this Metadata.
      • asCloudEvent

        CloudEvent asCloudEvent()
        Return a CloudEvent representation of this Metadata.

        Note that the CloudEvent representation will retain any non CloudEvent metadata when converted back to Metadata.

        Returns:
        This Metadata expressed as CloudEvent metadata.
        Throws:
        java.lang.IllegalStateException - If this metadata is not a CloudEvent, that is, if it doesn't have any of specversion, id, source or type CloudEvent fields defined.
      • asCloudEvent

        CloudEvent asCloudEvent​(java.lang.String id,
                                java.net.URI source,
                                java.lang.String type)
        Convert this metadata to a CloudEvent, adding the given required CloudEvent fields.

        Any metadata in this Metadata object will be left intact when asMetadata is called

        Parameters:
        id - The id of the CloudEvent.
        source - The source of the CloudEvent.
        type - The type of the CloudEvent.
        Returns:
        This metadata, represented as a CloudEvent with the specified fields.