org.eclipse.microprofile.reactive.messaging.Acknowledgment Maven / Gradle / Ivy
/*
* Copyright (c) 2018, 2019 Contributors to the Eclipse Foundation
*
* See the NOTICE file(s) distributed with this work for additional
* information regarding copyright ownership.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* You may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.eclipse.microprofile.reactive.messaging;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* Configure the acknowledgement policy for the given {@code @Incoming}.
*
* Reactive Messaging proposes four acknowledgement strategies:
*
* MANUAL: the acknowledgement (positive or negative) is up to the user. This is the default strategy
* for methods ingesting or producing {@link Message}.POST_PROCESSING: acknowledges the incoming message once the produced message is acknowledged. This
* is the default strategy for methods ingesting or producing single payloads.PRE_PROCESSING: acknowledges the incoming messages before calling the method.NONE: do not apply any acknowledgement.
*
* The set of supported acknowledgment policies depends on the method signature. The following list gives the supported
* strategies for some common use cases.
*
*
* @Incoming("channel") void method(I payload): Post-processing (default), Pre-processing, None @Incoming("channel") CompletionStage<?> method(I payload): Post-processing (default),
* Pre-processing, None @Incoming("in") @Outgoing("out") Message<O> method(Message<I> msg): , Manual (default),
* Pre-processing, None @Incoming("in") @Outgoing("out") O method(I payload): Post-Processing (default), Pre-processing,
* None
*
* Note that all messages must be acknowledged. An absence of acknowledgment is considered as a failure.
*
* The following table lists the supported strategies (and the default) for each supported signature:
*
*
*
*
* Signature
* Default Acknowledgement
* Strategy
* Supported Strategies
*
*
*
*
*
*
* @Incoming("channel")
* Subscriber<Message<I>> method()
*
*
*
*
*
* Manual
*
*
*
*
* None, Pre-Processing, Post-Processing (when the onNext method returns), Manual
*
*
*
*
*
*
*
* @Incoming("channel")
* Subscriber<I> method()
*
*
*
*
*
* Post-Processing
*
*
*
*
* None, Pre-Processing, Post-Processing (when the onNext method returns)
*
*
*
*
*
*
*
* @Incoming("channel")
* SubscriberBuilder<Message<I>, Void> method()
*
*
*
*
*
* Manual
*
*
*
*
* None, Pre-Processing, Post-Processing (when the onNext method returns), Manual
*
*
*
*
*
*
*
* @Incoming("channel")
* SubscriberBuilder<I, Void> method()
*
*
*
*
*
* Post-Processing
*
*
*
*
* None, Pre-Processing, Post-Processing (when the onNext method returns)
*
*
*
*
*
*
*
* @Incoming("channel")
* void method(I payload)
*
*
*
*
*
* Post-Processing
*
*
*
*
* None, Pre-Processing, Post-Processing (when the method returns)
*
*
*
*
*
*
*
* @Incoming("channel")
* CompletionStage<?> method(Message<I> msg)
*
*
*
*
*
* Manual
*
*
*
*
* None, Pre-Processing, Post-Processing (when the returned CompletionStage is completed), Manual
*
*
*
*
*
*
*
* @Incoming("channel")
* CompletionStage<?> method(I payload)
*
*
*
*
*
* Post-Processing
*
*
*
*
* None, Pre-Processing, Post-Processing (when the returned CompletionStage is completed)
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* Processor<Message<I>, Message<O>> method()
*
*
*
*
*
* Manual
*
*
*
*
* None, Pre-Processing, Manual
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* Processor<I, O> method();
*
*
*
*
*
* Pre-Processing
*
*
*
*
* None, Pre-Processing Post-Processing can be optionally supported by implementations, however it requires a 1:1
* mapping between the incoming element and the outgoing element.
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* ProcessorBuilder<Message<I>, Message<O>> method();
*
*
*
*
*
* Manual
*
*
*
*
* None, Pre-Processing, Manual
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* ProcessorBuilder<I, O> method();
*
*
*
*
*
* Pre-Processing
*
*
*
*
* None, Pre-Processing Post-Processing can be optionally supported by implementations, however it requires a 1:1
* mapping the incoming element and the outgoing element.
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* Publisher<Message<O>> method(Message<I> msg)
*
*
*
*
*
* Manual
*
*
*
*
* None, Manual, Pre-Processing
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* Publisher<O> method(I payload)
*
*
*
*
*
* Pre-Processing
*
*
*
*
* None, Pre-Processing
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* PublisherBuilder<Message<O>> method(Message<I> msg)
*
*
*
*
*
* Manual
*
*
*
*
* None, Manual, Pre-Processing
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* PublisherBuilder<O> method(I payload)
*
*
*
*
*
* Pre-Processing
*
*
*
*
* None, Pre-Processing
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* Message<O> method(Message<I> msg)
*
*
*
*
*
* Manual
*
*
*
*
* None, Manual, Pre-Processing
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* O method(I payload)
*
*
*
*
*
* Post-Processing
*
*
*
*
* None, Pre-Processing, Post-Processing (when the message wrapping the produced payload is acknowledged)
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* CompletionStage<Message<O>> method(Message<I> msg)
*
*
*
*
*
* Manual
*
*
*
*
* None, Manual, Pre-Processing
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* CompletionStage<O> method(I payload)
*
*
*
*
*
* Post-Processing
*
*
*
*
* None, Pre-Processing, Post-Processing (when the message wrapping the produced payload is acknowledged)
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* Publisher<Message<O>> method(Publisher<Message<I>> pub)
*
*
*
*
*
* Manual
*
*
*
*
* None, Manual, Pre-Processing
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* PublisherBuilder<Message<O>> method(PublisherBuilder<Message<I>> pub)
*
*
*
*
*
* Manual
*
*
*
*
* None, Manual, Pre-Processing
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* Publisher<O> method(Publisher<I> pub)
*
*
*
*
*
* Pre-Processing
*
*
*
*
* None, Pre-Processing
*
*
*
*
*
*
*
* @Incoming("in")
* @Outgoing("out")
* PublisherBuilder<O> method(PublisherBuilder<I> pub)
*
*
*
*
*
* Pre-Processing
*
*
*
*
* None, Pre-Processing
*
*
*
*
*
*
*
*/
@Retention(RetentionPolicy.RUNTIME)
public @interface Acknowledgment {
enum Strategy {
/**
* Acknowledgment managed by the user code. No automatic acknowledgment is performed. This strategy is only
* supported by methods consuming {@link Message} instances.
*/
MANUAL,
/**
* Acknowledgment performed automatically before the processing of the message by the user code.
*/
PRE_PROCESSING,
/**
* Acknowledgment performed automatically once the message has been processed. When {@code POST_PROCESSING} is
* used, the incoming message is acknowledged when the produced message is acknowledged.
*
* Notice that this mode is not supported for all signatures. When supported, it's the default policy.
*
*/
POST_PROCESSING,
/**
* No acknowledgment is performed, neither implicitly or explicitly. It means that the incoming messages are
* going to be acknowledged in a different location or using a different mechanism.
*/
NONE
}
/**
* @return the acknowledgement policy.
*/
Strategy value();
}