org.eclipse.microprofile.reactive.messaging

## Annotation Type Incoming

    @Target(value=METHOD)
     @Retention(value=RUNTIME)
    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.

See Also:
  `org.eclipse.microprofile.reactive.messaging`

### Required Element Summary

Required Elements
`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.