org.eclipse.microprofile.reactive.messaging

Interface Message<T>

Type Parameters:

T - The type of the message payload.

All Known Subinterfaces:

KafkaMessage<K,T>, KafkaRecord<K,T>, MqttMessage<T>

All Known Implementing Classes:

AmqpMessage, CamelMessage, IncomingJmsMessage, IncomingKafkaRecord, OutgoingAmqpMessage, OutgoingKafkaRecord, ReceivingMqttMessage, SendingMqttMessage

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 Summary

Fields

Modifier and Type	Field and Description
static Logger	LOGGER

Method Summary

Modifier and Type	Method and Description
default CompletionStage<Void>	ack() Acknowledge this message.
default Message<T>	addMetadata(Object metadata) Creates a new instance of Message with the current metadata, plus the given one.
default Supplier<CompletionStage<Void>>	getAck()
default Metadata	getMetadata()
default <M> Optional<M>	getMetadata(Class<? extends M> clazz) Retrieves the metadata associated with the given class.
default Function<Throwable,CompletionStage<Void>>	getNack()
T	getPayload()
default CompletionStage<Void>	nack(Throwable reason) Acknowledge negatively this message.
default CompletionStage<Void>	nack(Throwable reason, Metadata metadata) Acknowledge negatively this message.
static <T> Message<T>	of(T payload) Create a message with the given payload.
static <T> Message<T>	of(T payload, Iterable<Object> metadata) Create a message with the given payload and metadata.
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.
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.
static <T> Message<T>	of(T payload, Metadata metadata) Create a message with the given payload and metadata.
static <T> Message<T>	of(T payload, Metadata metadata, Supplier<CompletionStage<Void>> ack) Create a message with the given payload, metadata and ack function.
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.
static <T> Message<T>	of(T payload, Supplier<CompletionStage<Void>> ack) Create a message with the given payload and ack function.
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.
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.
default Message<T>	withAck(Supplier<CompletionStage<Void>> supplier) Creates a new instance of Message with the given acknowledgement supplier.
default Message<T>	withMetadata(Iterable<Object> metadata) Creates a new instance of Message with the specified metadata.
default Message<T>	withMetadata(Metadata metadata) Creates a new instance of Message with the specified metadata.
default Message<T>	withNack(Function<Throwable,CompletionStage<Void>> nack) Creates a new instance of Message with the given negative-acknowledgement function.
default <P> Message<P>	withPayload(P payload) Creates a new instance of Message with the specified payload.

Field Detail

LOGGER

static final Logger LOGGER

Method Detail

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, must not be null.

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, must not be null

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, must not be null.

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, must not be null.

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(value="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(value="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(value="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(value="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(value="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(value="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(value="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