org.eclipse.microprofile.reactive.messaging

Annotation Type Incoming

@Target(value=METHOD)
 @Retention(value=RUNTIME)
 @Repeatable(value=Incomings.class)
public @interface Incoming

Used to signify a subscriber to incoming messages.

Methods annotated with this annotation must have one of the following shapes:

• Take zero parameters, and return a SubscriberBuilder or a Subscriber.
• Take zero parameters, and return a ProcessorBuilder or a Processor.
• Accept a single parameter, and return a CompletionStage.
• Accept a single parameter, and return void.
• Accept a single parameter, and return any type.

In addition, implementations of this specification may allow returning additional types, such as implementation specific types for representing Reactive Streams, however taking advantage of these features provided by implementations will result in a non portable application.

The type of the message accepted by the subscriber may be wrapped in Message, or a subclass of it. All messaging providers must support Message, but messaging providers may also provide subclasses of Message in order to expose message transport specific features. Use of these sub classes will result in a non portable application. If the chosen messaging provider does not support the selected message wrapper, a deployment exception will be raised before the container is initialized.

If the incoming message is wrapped in a Message wrapper, then it is the responsibility of the subscriber to acknowledge messages. This can either by done by invoking Message.ack() directly, or if using a method shape that has an output value (such as the processor shapes, or methods that return a value), and if the output value also is also wrapped in a Message, by passing the ack callback to the emitted Message so that the container can ack it.

If the incoming message is not wrapped, then the container is responsible for automatically acknowledging messages. When the ack is done depends on the shape of the method - for subscriber shapes, it may either be done before or after passing a message to the subscriber (note that it doesn't matter which, since compliant Reactive Streams implementations don't allow throwing exceptions directly from the subscriber). For processor shapes, it should be when the processor emits an element. In this case, it is assumed, and the application must ensure, that there is a 1:1 correlation of elements consumed and emitted by the processor, and that ordering is maintained. For shapes that return a CompletionStage, it should be when that completion stage is redeemed. For methods that accept a single parameter and then return void or a value, it should be done after the method is invoked successfully.

If there is an output value, and it is wrapped, then it is the containers responsibility to invoke Message.ack() on each message emitted, except if indicated otherwise with the Acknowledgment annotation.

Incoming annotated methods may also have an Outgoing annotation, in which case, they must have a shape that emits an output value (such as a processor or a return value).

If the method has an output value but no Outgoing annotation, then the actual unwrapped value is ignored, though wrapped messages must still have their ack callback invoked by the container.

NOTE:: experimental - the annotation is marked repeatable.

See Also:

org.eclipse.microprofile.reactive.messaging

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	value The name of the consumed channel.

Element Detail

value

public abstract String value

The name of the consumed channel.

Returns:

the name of the consumed channel, must not be blank.