Class Metadata

java.lang.Object
io.fluxzero.common.api.Metadata
public class Metadata extends Object
Represents immutable metadata associated with a Message in the Fluxzero Runtime.

Metadata is a type-safe, JSON-serializable key–value store where all values are encoded as strings. It supports fluent creation, transformation, and querying, and is designed to be passed along with messages to provide context such as routing keys, user identity, correlation IDs, HTTP headers, and custom tracing information.

Key Features

  • Immutable, fluent API (e.g. metadata.with("key", value))
  • Auto-serializes arbitrary objects to JSON strings using Jackson
  • Supports optional, lazy deserialization via get(key, Class)
  • Includes built-in support for trace propagation via withTrace()
  • Provides entrySet(), containsKey(Object)}, getOrDefault(Object, String) ()}, etc.

Usage Example

Metadata metadata = Metadata.of("correlationId", "1234")
                            .with("userId", currentUser.getId())
                            .withTrace("workflow", "CreateOrder");

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static com.fasterxml.jackson.databind.json.JsonMapper
    objectMapper
     

  • Method Summary

    Modifier and Type
    Method
    Description
    Metadata
    addIfAbsent(Object key, Object value)
    Adds the specified key-value pair to the metadata if the key is not already present.
    Metadata
    addIfAbsent(Map<?,?> map)
    Adds all entries from the specified map to the current Metadata, ignoring keys that already exist.
    boolean
    contains(@NonNull Metadata metadata)
    Checks whether the current metadata contains all entries of the specified metadata.
    boolean
    contains(@NonNull Object key, @NonNull Object value)
    Determines if the specified key-value pair exists within the data structure.
    boolean
    containsAnyKey(Object... keys)
    Checks if the given keys are present in the internal entries.
    boolean
    containsKey(Object key)
    Checks if the specified key is present in the entries map.
    static Metadata
    empty()
    Creates an empty instance of the Metadata class with no entries.
    Set<Map.Entry<String,String>>
    entrySet()
    Returns a set view of the mappings contained in this metadata object.
    String
    get(Object key)
    Retrieves the value associated with the given key from the entries map.
    <T> T
    get(Object key, com.fasterxml.jackson.core.type.TypeReference<T> type)
    Retrieves a value associated with the given key, deserializes it to the specified type, and returns it.
    <T> T
    get(Object key, Class<T> type)
    Retrieves the value associated with the given key and attempts to deserialize it into the specified type.
    Map<String,String>
    getEntries()
    Retrieves a map of entries where the keys and values are strings.
    Optional<String>
    getOptionally(Object key)
    Retrieves the value associated with the provided key, if it exists, wrapped in an Optional.
    <T> Optional<T>
    getOptionally(Object key, com.fasterxml.jackson.core.type.TypeReference<T> type)
    Retrieves an object associated with the given key, deserializes it to the specified type, and returns it wrapped in an Optional.
    <T> Optional<T>
    getOptionally(Object key, Class<T> type)
    Retrieves an object associated with the given key, attempts to deserialize it to the specified type, and returns it wrapped in an Optional.
    String
    getOrDefault(Object key, String defaultValue)
    Retrieves the value mapped to the specified key in the entries map.
    <X extends Throwable>
    String
    getOrThrow(Object key, Supplier<? extends X> errorSupplier)
    Retrieves the value associated with the specified key or throws an exception provided by the given error supplier if the key does not exist or has a null value.
    Map<String,String>
    getTraceEntries()
    Retrieves a map containing only the entries from the metadata whose keys start with the prefix "$trace.".
    static Metadata
    of(Object... keyValues)
    Creates a new Metadata instance with the provided key-value pairs.
    static Metadata
    of(Object key, Object value)
    Creates a new Metadata instance with a single key-value pair.
    static Metadata
    of(Map<?,?> map)
    Creates a new instance of Metadata populated with the given map.
    String
    toString()
    Returns the string representation of this object, which is the string representation of the underlying entries map.
    Metadata
    with(Metadata metadata)
    Creates a new instance of Metadata by combining the current metadata with the given metadata.
    Metadata
    with(Object... keyValues)
    Creates a new Metadata instance by adding the specified key-value pairs.
    Metadata
    with(Object key, Object value)
    Returns a new Metadata instance with the specified key-value pair added or updated in the current entries.
    Metadata
    with(Map<?,?> values)
    Returns a new Metadata instance that includes all the current entries and the mappings provided in the given map.
    Metadata
    withNull(Object key)
    Returns a new Metadata instance with an explicit null value associated with the given key.
    Metadata
    without(Object key)
    Returns a new Metadata instance without the specified key.
    Metadata
    withoutIf(Predicate<String> check)
    Returns a new instance of Metadata, excluding all entries where the provided predicate evaluates to true for the entry keys.
    Metadata
    withTrace(Object key, Object value)
    Adds a trace entry with the specified key and value to the metadata.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • objectMapper

      public static com.fasterxml.jackson.databind.json.JsonMapper objectMapper

  • Method Details

    • getEntries

      public Map<String,String> getEntries()
      Retrieves a map of entries where the keys and values are strings.
      Returns:
      a map containing the entries with string keys and values

    • of

      public static Metadata of(Object... keyValues)
      Creates a new Metadata instance with the provided key-value pairs. This method generates a non-empty metadata object by associating the specified keys with their corresponding values.
      Parameters:
      keyValues - an alternating sequence of keys and values. The number of elements must be even, where keys are instances of Object and corresponding values follow them.
      Returns:
      a Metadata instance containing the specified key-value pairs.
      Throws:
      IllegalArgumentException - if the number of key-value arguments is not even.

    • empty

      public static Metadata empty()
      Creates an empty instance of the Metadata class with no entries.
      Returns:
      a Metadata instance with no key-value pairs.

    • of

      public static Metadata of(Object key, Object value)
      Creates a new Metadata instance with a single key-value pair.
      Parameters:
      key - the key to be included in the metadata, not null
      value - the value associated with the key, can be null
      Returns:
      a new Metadata instance containing the provided key-value pair

    • of

      public static Metadata of(Map<?,?> map)
      Creates a new instance of Metadata populated with the given map.
      Parameters:
      map - the map containing key-value pairs to populate the metadata. The keys and values are expected to be convertible to strings.
      Returns:
      a new Metadata instance containing the key-value pairs from the provided map.

    • toString

      public String toString()
      Returns the string representation of this object, which is the string representation of the underlying entries map.
      Overrides:
      toString in class Object
      Returns:
      the string representation of the entries map

    • with

      public Metadata with(Map<?,?> values)
      Returns a new Metadata instance that includes all the current entries and the mappings provided in the given map. If a key in the given map already exists in the current entries, its value will be overwritten.
      Parameters:
      values - a map containing the key-value pairs to be added or updated in the metadata
      Returns:
      a new Metadata instance with the updated entries

    • with

      public Metadata with(Metadata metadata)
      Creates a new instance of Metadata by combining the current metadata with the given metadata.
      Parameters:
      metadata - the Metadata containing entries to be added to the current instance
      Returns:
      a new Metadata instance that includes all entries from the current instance and the provided metadata

    • with

      public Metadata with(Object... keyValues)
      Creates a new Metadata instance by adding the specified key-value pairs. For each pair of values provided, the first value is used as the key (converted to a string), and the second value is used as the value. If an odd number of arguments is provided, an IllegalArgumentException is thrown.
      Parameters:
      keyValues - an alternating sequence of keys and values. Each key is converted to a string, and each value is added as a corresponding value in the metadata. The number of arguments must be even, with each key followed by its value.
      Returns:
      a new Metadata instance containing the updated entries.
      Throws:
      IllegalArgumentException - if the number of provided arguments is not even.

    • with

      public Metadata with(Object key, Object value)
      Returns a new Metadata instance with the specified key-value pair added or updated in the current entries.

      If the value is null, the key is removed. If the value is an Optional that is empty, no changes are made.

      Parameters:
      key - the key to add or update in the metadata entries
      value - the value associated with the key; if null, the key will be removed; if an Optional is empty, no change occurs
      Returns:
      a new Metadata instance with the updated entries

    • withNull

      public Metadata withNull(Object key)
      Returns a new Metadata instance with an explicit null value associated with the given key.
      Parameters:
      key - the key to add or update in the metadata entries
      Returns:
      a new Metadata instance with the updated entries

    • addIfAbsent

      public Metadata addIfAbsent(Object key, Object value)
      Adds the specified key-value pair to the metadata if the key is not already present.
      Parameters:
      key - the key to check and potentially add to the metadata
      value - the value to associate with the key if the key is absent
      Returns:
      the current metadata instance if the key is already present, or a new metadata instance with the key-value pair added if the key was absent

    • addIfAbsent

      public Metadata addIfAbsent(Map<?,?> map)
      Adds all entries from the specified map to the current Metadata, ignoring keys that already exist. If a key in the provided map already exists in this Metadata, it will be excluded from the operation.
      Parameters:
      map - the map containing entries to be added, unless the keys already exist in this Metadata
      Returns:
      a new Metadata instance with the combined entries from the original and the provided map, excluding entries with duplicate keys

    • withTrace

      public Metadata withTrace(Object key, Object value)
      Adds a trace entry with the specified key and value to the metadata. The trace key is prefixed with "$trace.".
      Parameters:
      key - the key for the trace entry, which will be prefixed with "$trace."
      value - the value associated with the specified key
      Returns:
      a new Metadata instance containing the updated trace entries

    • without

      public Metadata without(Object key)
      Returns a new Metadata instance without the specified key. If the given key exists in the original entries, it will be removed in the resulting Metadata instance. The original Metadata object remains unmodified.
      Parameters:
      key - the key to be removed from the Metadata entries
      Returns:
      a new Metadata instance with the specified key removed

    • withoutIf

      public Metadata withoutIf(Predicate<String> check)
      Returns a new instance of Metadata, excluding all entries where the provided predicate evaluates to true for the entry keys.
      Parameters:
      check - a predicate that determines which keys should be excluded. If the predicate returns true for a key, the key-value pair will be removed.
      Returns:
      a new Metadata object with the specified entries removed.

    • get

      public String get(Object key)
      Retrieves the value associated with the given key from the entries map.
      Parameters:
      key - the key whose associated value is to be returned. It should be an object, and its string representation will be used to query the map.
      Returns:
      the value associated with the specified key, or null if the key is not present in the map.

    • getOptionally

      public Optional<String> getOptionally(Object key)
      Retrieves the value associated with the provided key, if it exists, wrapped in an Optional.
      Parameters:
      key - the key whose associated value is to be returned, must not be null
      Returns:
      an Optional containing the value associated with the key, or an empty Optional if no value is found

    • get

      public <T> T get(Object key, Class<T> type)
      Retrieves the value associated with the given key and attempts to deserialize it into the specified type.
      Type Parameters:
      T - the type into which the value should be deserialized
      Parameters:
      key - the key used to look up the value
      type - the class object representing the type to which the value will be converted
      Returns:
      the deserialized value if the key exists and the conversion is successful; null if the key does not exist or the value is null
      Throws:
      IllegalStateException - if deserialization fails

    • getOptionally

      public <T> Optional<T> getOptionally(Object key, Class<T> type)
      Retrieves an object associated with the given key, attempts to deserialize it to the specified type, and returns it wrapped in an Optional. If the object is not present, an empty Optional is returned.
      Type Parameters:
      T - the type of the object to be retrieved
      Parameters:
      key - the key used to identify the object
      type - the class of the type to cast the retrieved object to
      Returns:
      an Optional containing the object if present and of the specified type, or an empty Optional otherwise

    • get

      public <T> T get(Object key, com.fasterxml.jackson.core.type.TypeReference<T> type)
      Retrieves a value associated with the given key, deserializes it to the specified type, and returns it.
      Type Parameters:
      T - The type of the returned value.
      Parameters:
      key - The key whose associated value is to be retrieved.
      type - The type reference indicating the type to which the retrieved value should be deserialized.
      Returns:
      The deserialized value of the specified type associated with the given key, or null if no value is found.
      Throws:
      IllegalStateException - if an error occurs during deserialization.

    • getOptionally

      public <T> Optional<T> getOptionally(Object key, com.fasterxml.jackson.core.type.TypeReference<T> type)
      Retrieves an object associated with the given key, deserializes it to the specified type, and returns it wrapped in an Optional. If the object is not present, an empty Optional is returned.
      Type Parameters:
      T - the type of the object to be retrieved
      Parameters:
      key - the key associated with the object to retrieve
      type - the type reference indicating the expected type of the object
      Returns:
      an Optional containing the object if found, or an empty Optional if not found

    • getOrThrow

      public <X extends Throwable> String getOrThrow(Object key, Supplier<? extends X> errorSupplier) throws X
      Retrieves the value associated with the specified key or throws an exception provided by the given error supplier if the key does not exist or has a null value.
      Type Parameters:
      X - the type of exception that the error supplier provides
      Parameters:
      key - the key whose associated value is to be returned
      errorSupplier - a supplier that provides the exception to be thrown if the key is not found or the value is null
      Returns:
      the value associated with the specified key
      Throws:
      X - if the key does not exist or the associated value is null

    • getTraceEntries

      public Map<String,String> getTraceEntries()
      Retrieves a map containing only the entries from the metadata whose keys start with the prefix "$trace.".
      Returns:
      a map of trace-specific entries where keys start with "$trace."

    • containsKey

      public boolean containsKey(Object key)
      Checks if the specified key is present in the entries map. The key is first converted to a string and then checked against the map for existence.
      Parameters:
      key - the key to check for presence in the entries map; must not be null
      Returns:
      true if the entries map contains the specified key, false otherwise

    • containsAnyKey

      public boolean containsAnyKey(Object... keys)
      Checks if the given keys are present in the internal entries.
      Parameters:
      keys - the keys to check for presence
      Returns:
      true if at least one of the provided keys exists, otherwise false

    • contains

      public boolean contains(@NonNull @NonNull Object key, @NonNull @NonNull Object value)
      Determines if the specified key-value pair exists within the data structure.
      Parameters:
      key - the key to check, must not be null
      value - the value to check, must not be null
      Returns:
      true if the key-value pair exists, false otherwise

    • contains

      public boolean contains(@NonNull @NonNull Metadata metadata)
      Checks whether the current metadata contains all entries of the specified metadata.
      Parameters:
      metadata - the Metadata object to compare, ensuring to check if all its entries exist within the current metadata.
      Returns:
      true if the current metadata contains all entries from the specified metadata, false otherwise.

    • getOrDefault

      public String getOrDefault(Object key, String defaultValue)
      Retrieves the value mapped to the specified key in the entries map. If the key is not found, returns the provided default value.
      Parameters:
      key - the key whose associated value is to be returned
      defaultValue - the value to return if the key is not found in the map
      Returns:
      the value mapped to the specified key, or the default value if the key is not found

    • entrySet

      public Set<Map.Entry<String,String>> entrySet()
      Returns a set view of the mappings contained in this metadata object.
      Returns:
      a set of entries, where each entry represents a key-value mapping in the metadata.