Interface CorrelationDataProvider

All Known Implementing Classes:
DefaultCorrelationDataProvider
public interface CorrelationDataProvider
Strategy interface for extracting correlation metadata from the current context.

Correlation metadata is used to propagate contextual information (e.g. trace IDs, user info, client IDs) across messages within the same logical execution chain.

When a message is dispatched, the active CorrelationDataProvider is queried to generate key-value pairs that are added to the message's metadata. These entries can then be accessed by downstream handlers to maintain traceability and context awareness.

A CorrelationDataProvider may extract metadata based on:

Standard Metadata Keys

The correlation data map may include the following keys:
  • $applicationId – ID of the application this client belongs to (optional)
  • $clientId – Unique identifier for this Fluxzero client instance
  • $clientName – Logical name of the client (e.g. "service-A")
  • $consumer – Consumer name of the current Tracker, if active
  • $tracker – Unique ID of the current Tracker, if active
  • $correlationId – ID used to correlate this message with the currently handled message (message index or ID if index is unavailable)
  • $traceId – ID representing the trace this message belongs to (usually inherited from the message root)
  • $trigger – Fully qualified class name of the message that triggered this one
  • $triggerType – Type of the triggering message (e.g. COMMAND, QUERY, etc.)
  • $invocation – ID of the current handler Invocation, if any

Multiple providers can be composed using andThen(CorrelationDataProvider) to combine metadata from multiple sources.

See Also:

  • Method Details

    • getCorrelationData

      default Map<String,String> getCorrelationData()
      Returns correlation metadata based on the current message being handled (if any).

      Delegates to getCorrelationData(DeserializingMessage) using the current thread-local DeserializingMessage.

      Returns:
      a map of correlation metadata entries

    • getCorrelationData

      default Map<String,String> getCorrelationData(@Nullable DeserializingMessage currentMessage)
      Returns correlation metadata derived from the current deserializing message.
      Parameters:
      currentMessage - the message currently being handled (can be null)
      Returns:
      a map of correlation metadata entries

    • getCorrelationData

      default Map<String,String> getCorrelationData(@Nullable Client client, @Nullable SerializedMessage currentMessage, @Nullable MessageType messageType)
      Returns correlation metadata derived from a serialized message and optional context.

      This method may be invoked when publishing messages without a DeserializingMessage context, such as in asynchronous dispatch or system-level operations.

      Parameters:
      client - the client instance performing the dispatch (can be null)
      currentMessage - the last serialized message in context (can be null)
      messageType - the type of the outgoing message (e.g. COMMAND, EVENT, etc.)
      Returns:
      a map of correlation metadata entries

    • getApplicationIdKey

      default String getApplicationIdKey()
      Retrieves the key used to identify the application ID in correlation metadata.
      Returns:
      a string representing the application ID key

    • getClientIdKey

      default String getClientIdKey()
      Retrieves the key representing the client identifier in the correlation metadata.
      Returns:
      the key used to identify the client in correlation data

    • getClientNameKey

      default String getClientNameKey()
      Retrieves the key associated with the client's name from the correlation metadata.
      Returns:
      a string representing the key for the client's name

    • getConsumerKey

      default String getConsumerKey()
      Retrieves the consumer key used to identify the consumer of a message.
      Returns:
      a string representing the consumer key

    • getTrackerKey

      default String getTrackerKey()
      Retrieves the key representing the tracker component in correlation metadata.
      Returns:
      the tracker key as a string

    • getCorrelationIdKey

      default String getCorrelationIdKey()
      Returns the key used for identifying the correlation ID within the metadata.
      Returns:
      a string representing the key for the correlation ID

    • getTraceIdKey

      default String getTraceIdKey()
      Returns the key used to identify the trace ID in correlation metadata.
      Returns:
      a string representing the trace ID key.

    • getTriggerKey

      default String getTriggerKey()
      Retrieves the trigger key used to identify the triggering context for correlation metadata.
      Returns:
      the trigger key as a string

    • getTriggerTypeKey

      default String getTriggerTypeKey()
      Returns the key associated with the trigger type in the correlation data.
      Returns:
      a string representing the trigger type key

    • getInvocationKey

      default String getInvocationKey()
      Retrieves the key associated with the invocation context within the correlation metadata.
      Returns:
      the invocation key as a string

    • getDelayKey

      default String getDelayKey()
      Retrieves the key used to identify the delay metadata within correlation data.
      Returns:
      a string representing the delay metadata key

    • andThen

      default CorrelationDataProvider andThen(CorrelationDataProvider next)
      Chains this provider with another, returning a composed provider that merges the metadata from both.

      If keys overlap, the values from the second (next) provider will overwrite those from this provider.

      Parameters:
      next - the provider to apply after this one
      Returns:
      a composed CorrelationDataProvider that merges the results of both