Package org.eclipse.microprofile.reactive.messaging

Interface Message<T>

Type Parameters:
T - The type of the message payload.
public interface Message<T>
A message envelope.

A message contains a non-null payload, an acknowledgement function and a set of metadata. Metadata are indexed using the class name of the values.

  • Field Details

    • LOGGER

      static final Logger LOGGER

  • Method Details

    • of

      static <T> Message<T> of(T payload)
      Create a message with the given payload. No metadata are associated with the message, the acknowledgement and negative acknowledgement are immediate.
      Type Parameters:
      T - The type of payload
      Parameters:
      payload - The payload.
      Returns:
      A message with the given payload, no metadata, and no-op ack and nack functions.

    • of

      static <T> Message<T> of(T payload, Metadata metadata)
      Create a message with the given payload and metadata. The acknowledgement and negative-acknowledgement are immediate.
      Type Parameters:
      T - The type of payload
      Parameters:
      payload - The payload.
      metadata - The metadata, if null an empty set of metadata is used.
      Returns:
      A message with the given payload, metadata and no-op ack and nack functions.

    • of

      static <T> Message<T> of(T payload, Iterable<Object> metadata)
      Create a message with the given payload and metadata. The acknowledgement and negative-acknowledgement are immediate.
      Type Parameters:
      T - The type of payload
      Parameters:
      payload - The payload.
      metadata - The metadata, must not be null, must not contain null values, can be empty
      Returns:
      A message with the given payload, metadata and no-op ack and nack functions.

    • of

      static <T> Message<T> of(T payload, Supplier<CompletionStage<Void>> ack)
      Create a message with the given payload and ack function. No metadata are associated with the message. Negative-acknowledgement is immediate.
      Type Parameters:
      T - the type of payload
      Parameters:
      payload - The payload.
      ack - The ack function, this will be invoked when the returned messages ack() method is invoked.
      Returns:
      A message with the given payload, no metadata and ack function.

    • of

      static <T> Message<T> of(T payload, Metadata metadata, Supplier<CompletionStage<Void>> ack)
      Create a message with the given payload, metadata and ack function. Negative-acknowledgement is immediate.
      Type Parameters:
      T - the type of payload
      Parameters:
      payload - The payload.
      metadata - the metadata, if null, empty metadata are used.
      ack - The ack function, this will be invoked when the returned messages ack() method is invoked.
      Returns:
      A message with the given payload and ack function.

    • of

      static <T> Message<T> of(T payload, Iterable<Object> metadata, Supplier<CompletionStage<Void>> ack)
      Create a message with the given payload, metadata and ack function. Negative-acknowledgement is immediate.
      Type Parameters:
      T - the type of payload
      Parameters:
      payload - The payload.
      metadata - the metadata, must not be null, must not contain null values.
      ack - The ack function, this will be invoked when the returned messages ack() method is invoked.
      Returns:
      A message with the given payload and ack function.

    • of

      @Experimental("nack support is a SmallRye-only feature") static <T> Message<T> of(T payload, Supplier<CompletionStage<Void>> ack, Function<Throwable,CompletionStage<Void>> nack)
      Create a message with the given payload, ack and nack functions.
      Type Parameters:
      T - the type of payload
      Parameters:
      payload - The payload.
      ack - The ack function, this will be invoked when the returned messages ack() method is invoked.
      nack - The negative-ack function, this will be invoked when the returned messages nack(Throwable) method is invoked.
      Returns:
      A message with the given payload, metadata, ack and nack functions.

    • of

      @Experimental("nack support is a SmallRye-only feature") static <T> Message<T> of(T payload, Iterable<Object> metadata, Supplier<CompletionStage<Void>> ack, Function<Throwable,CompletionStage<Void>> nack)
      Create a message with the given payload, metadata and ack and nack functions.
      Type Parameters:
      T - the type of payload
      Parameters:
      payload - The payload.
      metadata - the metadata, must not be null, must not contain null values.
      ack - The ack function, this will be invoked when the returned messages ack() method is invoked.
      nack - The negative-ack function, this will be invoked when the returned messages nack(Throwable) method is invoked.
      Returns:
      A message with the given payload, metadata, ack and nack functions.

    • of

      @Experimental("nack support is a SmallRye-only feature") static <T> Message<T> of(T payload, Metadata metadata, Supplier<CompletionStage<Void>> ack, Function<Throwable,CompletionStage<Void>> nack)
      Create a message with the given payload, metadata and ack and nack functions.
      Type Parameters:
      T - the type of payload
      Parameters:
      payload - The payload.
      metadata - the metadata, must not be null, must not contain null values.
      ack - The ack function, this will be invoked when the returned messages ack() method is invoked.
      nack - The negative-ack function, this will be invoked when the returned messages nack(Throwable) method is invoked.
      Returns:
      A message with the given payload, metadata, ack and nack functions.

    • withPayload

      default <P> Message<P> withPayload(P payload)
      Creates a new instance of Message with the specified payload. The metadata and ack/nack functions are taken from the current Message.
      Type Parameters:
      P - the type of the new payload
      Parameters:
      payload - the new payload.
      Returns:
      the new instance of Message

    • withMetadata

      default Message<T> withMetadata(Iterable<Object> metadata)
      Creates a new instance of Message with the specified metadata. The payload and ack/nack functions are taken from the current Message.
      Parameters:
      metadata - the metadata, must not be null, must not contains null.
      Returns:
      the new instance of Message

    • withMetadata

      default Message<T> withMetadata(Metadata metadata)
      Creates a new instance of Message with the specified metadata. The payload and ack/nack functions are taken from the current Message.
      Parameters:
      metadata - the metadata, must not be null.
      Returns:
      the new instance of Message

    • withAck

      default Message<T> withAck(Supplier<CompletionStage<Void>> supplier)
      Creates a new instance of Message with the given acknowledgement supplier. The payload, metadata and nack function are taken from the current Message.
      Parameters:
      supplier - the acknowledgement supplier
      Returns:
      the new instance of Message

    • withNack

      @Experimental("nack support is a SmallRye-only feature") default Message<T> withNack(Function<Throwable,CompletionStage<Void>> nack)
      Creates a new instance of Message with the given negative-acknowledgement function. The payload, metadata and acknowledgment are taken from the current Message.
      Parameters:
      nack - the negative-acknowledgement function
      Returns:
      the new instance of Message

    • getPayload

      T getPayload()
      Returns:
      The payload for this message.

    • getMetadata

      default Metadata getMetadata()
      Returns:
      The set of metadata attached to this message, potentially empty.

    • getMetadata

      default <M> Optional<M> getMetadata(Class<? extends M> clazz)
      Retrieves the metadata associated with the given class.
      Parameters:
      clazz - the class of the metadata to retrieve, must not be null
      Returns:
      an Optional containing the associated metadata, empty if none.

    • getAck

      default Supplier<CompletionStage<Void>> getAck()
      Returns:
      the supplier used to retrieve the acknowledgement CompletionStage.

    • getNack

      @Experimental("nack support is a SmallRye-only feature") default Function<Throwable,CompletionStage<Void>> getNack()
      Returns:
      the function used to retrieve the negative-acknowledgement asynchronous function.

    • ack

      default CompletionStage<Void> ack()
      Acknowledge this message.
      Returns:
      a completion stage completed when the message is acknowledged. If the acknowledgement fails, the completion stage propagates the failure.

    • nack

      @Experimental("nack support is a SmallRye-only feature") default CompletionStage<Void> nack(Throwable reason)
      Acknowledge negatively this message. nack is used to indicate that the processing of a message failed. The reason is passed as parameter.
      Parameters:
      reason - the reason of the nack, must not be null
      Returns:
      a completion stage completed when the message is negative-acknowledgement has completed. If the negative acknowledgement fails, the completion stage propagates the failure.

    • nack

      @Experimental("nack support is a SmallRye-only feature; metadata propagation is a SmallRye-specific feature") default CompletionStage<Void> nack(Throwable reason, Metadata metadata)
      Acknowledge negatively this message. nack is used to indicate that the processing of a message failed. The reason is passed as parameter. Additional metadata may be provided that the connector can use when nacking the message. The interpretation of metadata is connector-specific.
      Parameters:
      reason - the reason of the nack, must not be null
      metadata - additional nack metadata the connector may use, may be null
      Returns:
      a completion stage completed when the message is negative-acknowledgement has completed. If the negative acknowledgement fails, the completion stage propagates the failure.

    • unwrap

      default <C> C unwrap(Class<C> unwrapType)
      Returns an object of the specified type to allow access to the connector-specific Message implementation, and other classes. For example, a Kafka connector could implement this method to allow unwrapping to a specific Kafka message implementation, or to ConsumerRecord and ProducerRecord. If the Message implementation does not support the target class, an IllegalArgumentException should be raised.

      The default implementation tries to cast the current Message instance to the target class. When a connector provides its own Message implementation, it should override this method to support specific types.

      Type Parameters:
      C - the target type
      Parameters:
      unwrapType - the class of the object to be returned, must not be null
      Returns:
      an instance of the specified class
      Throws:
      IllegalArgumentException - if the current Message instance does not support the call

    • addMetadata

      default Message<T> addMetadata(Object metadata)
      Creates a new instance of Message with the current metadata, plus the given one. The payload and ack/nack functions are taken from the current Message.
      Parameters:
      metadata - the metadata, must not be null.
      Returns:
      the new instance of Message