Interface Message<T>

Type Parameters:
T - payload type
All Known Subinterfaces:
DeadLetterMessage<T>
public interface Message<T>
Message envelope with a payload, portable headers, and optional local metadata.

Ordinary messages expose a non-null payload. A connector-specific immutable metadata envelope created after transport mapping fails may instead throw MessagingException from entity(); such an envelope is only valid in the batch passed to ConnectorDeliveryReservation.startFailed(MessageBatch, RuntimeException) or ConnectorDeliveryReservation.tryStartFailed(MessageBatch, RuntimeException). Portable headers retain global order, duplicate exact case-sensitive names, and immutable typed values. Implementations must be immutable snapshots. Accessors may be invoked repeatedly and concurrently; implementations must expose stable values without consuming one-shot state. localMetadata() follows the same in-process envelope but is never part of portable headers or generic connector mapping. Connector-specific message subtypes may expose richer native metadata separately.

See Also:

  • Method Details

    • builder

      static <T> MessageConfig.Builder<T> builder()
      Create a message builder.
      Type Parameters:
      T - payload type
      Returns:
      builder

    • builder

      static <T> MessageConfig.Builder<T> builder(T entity)
      Create a message builder.
      Type Parameters:
      T - payload type
      Parameters:
      entity - non-null payload
      Returns:
      builder
      Throws:
      NullPointerException - if entity is null

    • create

      static <T> Message<T> create(T entity)
      Create a payload-only message.
      Type Parameters:
      T - payload type
      Parameters:
      entity - non-null payload
      Returns:
      message
      Throws:
      NullPointerException - if entity is null

    • entity

      T entity()
      Payload.

      Repeated and concurrent invocations must be safe, and successful invocations must return the same stable payload value. A connector metadata envelope whose transport payload could not be mapped must instead consistently throw MessagingException.

      Returns:
      non-null payload
      Throws:
      MessagingException - if this is a connector metadata envelope whose transport payload could not be mapped

    • headers

      MessageHeaders headers()
      Ordered portable headers.

      Connectors preserve exact names, global order, duplicates, and value kinds when supported by their transport. An unsupported outbound value must be explicitly translated or rejected, never silently stringified, reordered, or dropped.

      Returns:
      immutable headers

    • localMetadata

      default MessageMetadata localMetadata()
      Metadata local to this message envelope.

      Local metadata follows the same envelope while it is used in-process. Connectors and generic message mappers must never serialize or map it to a transport. A local value must be explicitly promoted to a portable header before it can be sent, including any necessary redaction and size limit.

      Returns:
      immutable local metadata

    • headerValue

      default Optional<MessageHeaderValue> headerValue(String name)
      Last portable header value with an exact name.
      Parameters:
      name - header name
      Returns:
      header value, or empty when the exact name is absent

    • header

      default Optional<String> header(String name)
      Last portable text header value with an exact name.

      This convenience method preserves the original text-header API. It throws when the last value exists but is not a MessageHeaderValue.TextValue; it never stringifies typed values or skips past a later non-text value.

      Parameters:
      name - header name
      Returns:
      header value, or empty only when the exact name is absent
      Throws:
      IllegalStateException - if the last value is present but is not text