de.otto.synapse.endpoint.receiver.MessageLogReceiverEndpoint Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of synapse-core Show documentation
A library used at otto.de to implement Spring Boot based event-sourcing microservices.
The newest version!
package de.otto.synapse.endpoint.receiver;

import de.otto.synapse.channel.ChannelPosition;
import de.otto.synapse.channel.ShardResponse;
import de.otto.synapse.consumer.MessageConsumer;
import de.otto.synapse.consumer.MessageDispatcher;
import de.otto.synapse.message.Message;
import de.otto.synapse.message.TextMessage;
import jakarta.annotation.Nonnull;

import java.util.concurrent.CompletableFuture;
import java.util.function.Predicate;

import static de.otto.synapse.channel.StopCondition.shutdown;

/**
 * Receiver-side {@code MessageEndpoint endpoint} of a Message Channel that matches random-access like reading of
 * messages using {@link ChannelPosition ChannelPositions}.
 *
 * 
 *     
 * 
 * 
 *     MessageLogReceiverEndpoints are endpoints for Publish-Subscribe Channels:
 * 
 * 
 *     
 * 
 * @see EIP: Publish-Subscribe Channel
 */
public interface MessageLogReceiverEndpoint extends MessageReceiverEndpoint {
    /**
     * Beginning at the {@code startFrom} position, messages are consumed from the message log, until the
     * {@code stopCondition} is true.
     *
     * Takes zero or more messages from the channel, calls {@link #intercept(TextMessage)} for every message,
     *     and notifies the registered consumers with the intercepted message, or drops the message, if
     *     {@code intercept} returns null.
     *
     * Consumption starts with the first message after {@code startFrom} and finishes when either the
     *     {@code stopCondition} is met, or the application is shutting down.
     *
     * The returned {@code ChannelPosition} is the position of the last message that was processed by the
     *     {@code MessageLogReceiverEndpoint} - whether it was dropped or consumed.
     *
     * The {@link #register(MessageConsumer) registered} {@link MessageConsumer consumers} are used as a
     *     callback for consumed messages.
     *
     * @param startFrom the start position used to proceed message consumption
     * @return ChannelPosition
     */
    @Nonnull
    default CompletableFuture consume(@Nonnull ChannelPosition startFrom) {
        return consumeUntil(startFrom, shutdown());
    }

    /**
     * Beginning at the {@code startFrom} position, messages are consumed from the message log, until the
     * {@link de.otto.synapse.channel.StopCondition stopCondition} is true.
     *
     * 
     *     If the message-log is sharded, the predicate must be true for every shard: otherwise, message consumption
     *     would continue on other shards.
     * 
     * 
     *     Takes zero or more messages from the channel, calls {@link #intercept(TextMessage)} for every message,
     *     and notifies the registered consumers with the intercepted message, or drops the message, if
     *     {@code intercept} returns null.
     *
     *
     * 
     *     Consumption starts with the first message after {@code startFrom} and finishes when either the
     *     {@code stopCondition} is met, or the application is shutting down.
     * 
     * 
     *     The returned {@code ChannelPosition} is the position of the last message that was processed by the
     *     {@code MessageLogReceiverEndpoint} - whether it was dropped or consumed.
     * 
     * 
     *     The {@link #register(MessageConsumer) registered} {@link MessageConsumer consumers} are used as a
     *     callback for consumed messages. A {@link MessageDispatcher} can be used as a consumer, if multiple
     *     consumers, or consumers with {@link Message#getPayload() message payloads} other than {@code String} are
     *     required.
     * 
     *
     * @param startFrom the start position used to proceed message consumption
     * @param stopCondition the predicate used to test if message consumption should be stopped. In most cases, the
     *                      predicates defined in {@link de.otto.synapse.channel.StopCondition} should be sufficient.
     * @return ChannelPosition
     */
    @Nonnull
    CompletableFuture consumeUntil(@Nonnull ChannelPosition startFrom,
                                                    @Nonnull Predicate stopCondition);

    /**
     * Stops consumption of messages and shuts down the {@code MessageLogReceiverEndpoint}.
     */
    void stop();
}