Package kalix.javasdk

Interface Metadata

All Superinterfaces:
Iterable<Metadata.MetadataEntry>
public interface Metadata extends 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.

  • Field Details

    • EMPTY

      static final Metadata EMPTY
      An empty Metadata object.

  • Method Details

    • get

      Optional<String> get(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

      List<String> getAll(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

      Optional<ByteBuffer> getBinary(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

      List<ByteBuffer> getBinaryAll(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(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

      List<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(String key, 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(String key, 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(String key, 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(String key, 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(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:
      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(String id, URI source, 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.

    • jwtClaims

      JwtClaims jwtClaims()
      Get the JWT claims present in this metadata.
      Returns:
      The JWT claims.

    • principals

      Principals principals()
      Get the principals associated with this request metadata.
      Returns:
      The principals associated with this request metadata.

    • traceContext

      TraceContext traceContext()
      Get the trace context associated with this request metadata.
      Returns:
      The trace context.

    • withStatusCode

      Metadata withStatusCode(StatusCode.Success httpStatusCode)
      Add an HTTP response code to this metadata. This will only take effect when HTTP transcoding is in use. It will be ignored for gRPC requests.
      Parameters:
      httpStatusCode - The success status code to add.
      Returns:
      a copy of this metadata with the HTTP response code set.

    • withStatusCode

      Metadata withStatusCode(StatusCode.Redirect httpStatusCode)
      Add an HTTP response code to this metadata. This will only take effect when HTTP transcoding is in use. It will be ignored for gRPC requests.
      Parameters:
      httpStatusCode - The redirect status code to add.
      Returns:
      a copy of this metadata with the HTTP response code set.