org.springframework.data.redis.stream

Interface StreamMessageListenerContainer<K,V extends Record<K,?>>

Type Parameters:

K - Stream key and Stream field type.

V - Stream value type.

All Superinterfaces:

Lifecycle, Phased, SmartLifecycle

public interface StreamMessageListenerContainer<K,V extends Record<K,?>>
extends SmartLifecycle

Abstraction used by the framework representing a message listener container. Not meant to be implemented externally.

Once created, a StreamMessageListenerContainer can subscribe to a Redis Stream and consume incoming messages. StreamMessageListenerContainer allows multiple stream read requests and returns a Subscription handle per read request. Cancelling the Subscription terminates eventually background polling. Messages are converted using key and value serializers to support various serialization strategies.
StreamMessageListenerContainer supports multiple modes of stream consumption:

• Standalone
• Using a Consumer with external StreamOperations.acknowledge(Object, String, String...) acknowledge}
• Using a Consumer with auto-acknowledge

Reading from a stream requires polling and a strategy to advance stream offsets. Depending on the initial ReadOffset, StreamMessageListenerContainer applies an individual strategy to obtain the next ReadOffset:
Standalone

• ReadOffset.from(String) Offset using a particular message Id: Start with the given offset and use the last seen message Id.
• ReadOffset.lastConsumed() Last consumed: Start with the latest offset ($) and use the last seen message Id.
• ReadOffset.latest() Last consumed: Start with the latest offset ($) and use latest offset ($) for subsequent reads.

Using Consumer

• ReadOffset.from(String) Offset using a particular message Id: Start with the given offset and use the last seen message Id.
• ReadOffset.lastConsumed() Last consumed: Start with the last consumed message by the consumer (>) and use the last consumed message by the consumer (>) for subsequent reads.
• ReadOffset.latest() Last consumed: Start with the latest offset ($) and use latest offset ($) for subsequent reads.

Note: Using ReadOffset.latest() bears the chance of dropped messages as messages can arrive in the time during polling is suspended. Use messagedId's as offset or ReadOffset.lastConsumed() to minimize the chance of message loss.

StreamMessageListenerContainer requires a Executor to fork long-running polling tasks on a different Thread. This thread is used as event loop to poll for stream messages and invoke the listener callback.

StreamMessageListenerContainer tasks propagate errors during stream reads and listener notification to a configurable ErrorHandler. Errors stop a Subscription by default. Configuring a Predicate for a StreamMessageListenerContainer.StreamReadRequest allows conditional subscription cancelling or continuing on all errors.

See the following example code how to use StreamMessageListenerContainer:

 RedisConnectionFactory factory = …;

 StreamMessageListenerContainer> container = StreamMessageListenerContainer.create(factory);
 Subscription subscription = container.receive(StreamOffset.fromStart("my-stream"), message -> …);

 container.start();

 // later
 container.stop();
 

Since:

2.2

Author:

Mark Paluch

See Also:

StreamMessageListenerContainer.StreamMessageListenerContainerOptions.builder(), StreamListener, StreamMessageListenerContainer.StreamReadRequest, StreamMessageListenerContainer.ConsumerStreamReadRequest, StreamMessageListenerContainer.StreamMessageListenerContainerOptionsBuilder.executor(Executor), ErrorHandler, StreamOperations, RedisConnectionFactory, StreamReceiver

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	StreamMessageListenerContainer.ConsumerStreamReadRequest<K> Request to read a Redis Stream with a Consumer.
static class	StreamMessageListenerContainer.ConsumerStreamReadRequestBuilder<K> Builder to build a StreamMessageListenerContainer.ConsumerStreamReadRequest.
static class	StreamMessageListenerContainer.StreamMessageListenerContainerOptions<K,V extends Record<K,?>> Options for StreamMessageListenerContainer.
static class	StreamMessageListenerContainer.StreamMessageListenerContainerOptionsBuilder<K,V extends Record<K,?>> Builder for StreamMessageListenerContainer.StreamMessageListenerContainerOptions.
static class	StreamMessageListenerContainer.StreamReadRequest<K> Request to read a Redis Stream.
static class	StreamMessageListenerContainer.StreamReadRequestBuilder<K> Builder to build a StreamMessageListenerContainer.StreamReadRequest.

Field Summary

Fields inherited from interface org.springframework.context.SmartLifecycle

DEFAULT_PHASE

Method Summary

Modifier and Type	Method and Description
static StreamMessageListenerContainer<String,MapRecord<String,String,String>>	create(RedisConnectionFactory connectionFactory) Create a new StreamMessageListenerContainer using string serializers given RedisConnectionFactory.
static <K,V extends Record<K,?>> StreamMessageListenerContainer<K,V>	create(RedisConnectionFactory connectionFactory, StreamMessageListenerContainer.StreamMessageListenerContainerOptions<K,V> options) Create a new StreamMessageListenerContainer given RedisConnectionFactory and StreamMessageListenerContainer.StreamMessageListenerContainerOptions.
default Subscription	receive(Consumer consumer, StreamOffset<K> streamOffset, StreamListener<K,V> listener) Register a new subscription for a Redis Stream.
default Subscription	receive(StreamOffset<K> streamOffset, StreamListener<K,V> listener) Register a new subscription for a Redis Stream.
default Subscription	receiveAutoAck(Consumer consumer, StreamOffset<K> streamOffset, StreamListener<K,V> listener) Register a new subscription for a Redis Stream.
Subscription	register(StreamMessageListenerContainer.StreamReadRequest<K> streamRequest, StreamListener<K,V> listener) Register a new subscription for a Redis Stream.
void	remove(Subscription subscription) Unregister a given Subscription from the container.

Methods inherited from interface org.springframework.context.SmartLifecycle

getPhase, isAutoStartup, stop

Methods inherited from interface org.springframework.context.Lifecycle

isRunning, start, stop

Method Detail

create

static StreamMessageListenerContainer<String,MapRecord<String,String,String>> create(RedisConnectionFactory connectionFactory)

Create a new StreamMessageListenerContainer using string serializers given RedisConnectionFactory.

Parameters:

connectionFactory - must not be null.

Returns:

the new StreamMessageListenerContainer.

create

static <K,V extends Record<K,?>> StreamMessageListenerContainer<K,V> create(RedisConnectionFactory connectionFactory,
                                                                            StreamMessageListenerContainer.StreamMessageListenerContainerOptions<K,V> options)

Create a new StreamMessageListenerContainer given RedisConnectionFactory and StreamMessageListenerContainer.StreamMessageListenerContainerOptions.

Parameters:

connectionFactory - must not be null.

options - must not be null.

Returns:

the new StreamMessageListenerContainer.

receive

default Subscription receive(StreamOffset<K> streamOffset,
                             StreamListener<K,V> listener)

Register a new subscription for a Redis Stream. If the is already running the Subscription will be added and run immediately, otherwise it'll be scheduled and started once the container is actually started.

Errors during org.springframework.data.redis.connection.RedisStreamCommands.StreamMessage retrieval lead to cancellation of the underlying task.

On Lifecycle.stop() all subscriptions are cancelled prior to shutting down the container itself.

Parameters:

streamOffset - the stream along its offset.

listener - must not be null.

Returns:

the subscription handle.

See Also:

StreamOffset.create(Object, ReadOffset)

receive

default Subscription receive(Consumer consumer,
                             StreamOffset<K> streamOffset,
                             StreamListener<K,V> listener)

Register a new subscription for a Redis Stream. If the is already running the Subscription will be added and run immediately, otherwise it'll be scheduled and started once the container is actually started.

Every message must be acknowledged using StreamOperations.acknowledge(Object, String, String...) after processing.

Errors during org.springframework.data.redis.connection.RedisStreamCommands.StreamMessage retrieval lead to cancellation of the underlying task.

On Lifecycle.stop() all subscriptions are cancelled prior to shutting down the container itself.

Parameters:

consumer - consumer group, must not be null.

streamOffset - the stream along its offset.

listener - must not be null.

Returns:

the subscription handle.

See Also:

StreamOffset.create(Object, ReadOffset), ReadOffset.lastConsumed()

receiveAutoAck

default Subscription receiveAutoAck(Consumer consumer,
                                    StreamOffset<K> streamOffset,
                                    StreamListener<K,V> listener)

Register a new subscription for a Redis Stream. If the is already running the Subscription will be added and run immediately, otherwise it'll be scheduled and started once the container is actually started.

Every message is acknowledged when received.

Errors during org.springframework.data.redis.connection.RedisStreamCommands.StreamMessage retrieval lead to cancellation of the underlying task.

On Lifecycle.stop() all subscriptions are cancelled prior to shutting down the container itself.

Parameters:

consumer - consumer group, must not be null.

streamOffset - the stream along its offset.

listener - must not be null.

Returns:

the subscription handle.

See Also:

StreamOffset.create(Object, ReadOffset), ReadOffset.lastConsumed()

register

Subscription register(StreamMessageListenerContainer.StreamReadRequest<K> streamRequest,
                      StreamListener<K,V> listener)

Register a new subscription for a Redis Stream. If the is already running the Subscription will be added and run immediately, otherwise it'll be scheduled and started once the container is actually started.

Errors during org.springframework.data.redis.connection.RedisStreamCommands.StreamMessage are tested against test cancellation predicate whether to cancel the underlying task.

On Lifecycle.stop() all subscriptions are cancelled prior to shutting down the container itself.

Errors during org.springframework.data.redis.connection.RedisStreamCommands.StreamMessage retrieval are delegated to the given StreamMessageListenerContainer.StreamReadRequest.getErrorHandler().

Parameters:

streamRequest - must not be null.

listener - must not be null.

Returns:

the subscription handle.

See Also:

StreamMessageListenerContainer.StreamReadRequest, StreamMessageListenerContainer.ConsumerStreamReadRequest

remove

void remove(Subscription subscription)

Unregister a given Subscription from the container. This prevents the Subscription to be restarted in a potential stop/start scenario.
An active subcription is cancelled prior to removal.

Parameters:

subscription - must not be null.