org.springframework.data.redis.core.ReactiveStreamOperations Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of spring-data-redis Show documentation
Show all versions of spring-data-redis Show documentation
Spring Data module for Redis
/*
* Copyright 2018-2024 the original author or authors.
*
* 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
*
* https://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.springframework.data.redis.core;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import java.time.Duration;
import java.util.Arrays;
import java.util.Map;
import org.reactivestreams.Publisher;
import org.springframework.data.domain.Range;
import org.springframework.data.redis.connection.Limit;
import org.springframework.data.redis.connection.RedisStreamCommands.XClaimOptions;
import org.springframework.data.redis.connection.stream.ByteBufferRecord;
import org.springframework.data.redis.connection.stream.Consumer;
import org.springframework.data.redis.connection.stream.MapRecord;
import org.springframework.data.redis.connection.stream.ObjectRecord;
import org.springframework.data.redis.connection.stream.PendingMessage;
import org.springframework.data.redis.connection.stream.PendingMessages;
import org.springframework.data.redis.connection.stream.PendingMessagesSummary;
import org.springframework.data.redis.connection.stream.ReadOffset;
import org.springframework.data.redis.connection.stream.Record;
import org.springframework.data.redis.connection.stream.RecordId;
import org.springframework.data.redis.connection.stream.StreamInfo.XInfoConsumer;
import org.springframework.data.redis.connection.stream.StreamInfo.XInfoGroup;
import org.springframework.data.redis.connection.stream.StreamInfo.XInfoStream;
import org.springframework.data.redis.connection.stream.StreamOffset;
import org.springframework.data.redis.connection.stream.StreamReadOptions;
import org.springframework.data.redis.connection.stream.StreamRecords;
import org.springframework.data.redis.hash.HashMapper;
import org.springframework.lang.Nullable;
import org.springframework.util.Assert;
/**
* Reactive Redis operations for Stream Commands.
*
* @author Mark Paluch
* @author Christoph Strobl
* @author Dengliming
* @author Marcin Zielinski
* @author John Blum
* @since 2.2
*/
public interface ReactiveStreamOperations extends HashMapperProvider {
/**
* Acknowledge one or more records as processed.
*
* @param key the stream key.
* @param group name of the consumer group.
* @param recordIds record Id's to acknowledge.
* @return the {@link Mono} emitting the length of acknowledged records.
* @see Redis Documentation: XACK
*/
default Mono acknowledge(K key, String group, String... recordIds) {
return acknowledge(key, group, Arrays.stream(recordIds).map(RecordId::of).toArray(RecordId[]::new));
}
/**
* Acknowledge one or more records as processed.
*
* @param key the stream key.
* @param group name of the consumer group.
* @param recordIds record Id's to acknowledge.
* @return the {@link Mono} emitting the length of acknowledged records.
* @see Redis Documentation: XACK
*/
Mono acknowledge(K key, String group, RecordId... recordIds);
/**
* Acknowledge the given record as processed.
*
* @param group name of the consumer group.
* @param record the {@link Record} to acknowledge.
* @return the {@link Mono} emitting the length of acknowledged records.
* @see Redis Documentation: XACK
*/
default Mono acknowledge(String group, Record record) {
return acknowledge(record.getRequiredStream(), group, record.getId());
}
/**
* Append one or more records to the stream {@code key}.
*
* @param key the stream key.
* @param bodyPublisher record body {@link Publisher}.
* @return the record Ids.
* @see Redis Documentation: XADD
*/
default Flux add(K key, Publisher> bodyPublisher) {
return Flux.from(bodyPublisher).flatMap(it -> add(key, it));
}
/**
* Append a record to the stream {@code key}.
*
* @param key the stream key.
* @param content record content as Map.
* @return the {@link Mono} emitting the {@link RecordId}.
* @see Redis Documentation: XADD
*/
default Mono add(K key, Map content) {
return add(StreamRecords.newRecord().in(key).ofMap(content));
}
/**
* Append a record, backed by a {@link Map} holding the field/value pairs, to the stream.
*
* @param record the record to append.
* @return the {@link Mono} emitting the {@link RecordId}.
* @see Redis Documentation: XADD
*/
@SuppressWarnings("unchecked")
default Mono add(MapRecord record) {
return add((Record) record);
}
/**
* Append the record, backed by the given value, to the stream. The value will be hashed and serialized.
*
* @param record must not be {@literal null}.
* @return the {@link Mono} emitting the {@link RecordId}.
* @see MapRecord
* @see ObjectRecord
*/
Mono add(Record record);
/**
* Changes the ownership of a pending message so that the new owner is the consumer specified as
* the command argument.
*
* The message is claimed only if its idle time (ms) is greater than the {@link Duration minimum idle time}
* specified when calling {@literal XCLAIM}.
*
* @param key {@link K key} to the steam.
* @param consumerGroup {@link String name} of the consumer group.
* @param newOwner {@link String name} of the consumer claiming the message.
* @param minIdleTime {@link Duration minimum idle time} required for a message to be claimed.
* @param recordIds {@link RecordId record IDs} to be claimed.
* @return {@link Flux} of claimed {@link MapRecord MapRecords}.
* @see Redis Documentation: XCLAIM
* @see org.springframework.data.redis.connection.stream.MapRecord
* @see org.springframework.data.redis.connection.stream.RecordId
* @see #claim(Object, String, String, XClaimOptions)
* @see reactor.core.publisher.Flux
*/
default Flux> claim(K key, String consumerGroup, String newOwner, Duration minIdleTime,
RecordId... recordIds) {
return claim(key, consumerGroup, newOwner, XClaimOptions.minIdle(minIdleTime).ids(recordIds));
}
/**
* Changes the ownership of a pending message so that the new owner is the consumer specified as
* the command argument.
* The message is claimed only if its idle time (ms) is greater than the given {@link Duration minimum idle time}
* specified when calling {@literal XCLAIM}.
*
* @param key {@link K key} to the steam.
* @param consumerGroup {@link String name} of the consumer group.
* @param newOwner {@link String name} of the consumer claiming the message.
* @param xClaimOptions additional parameters for the {@literal CLAIM} call.
* @return a {@link Flux} of claimed {@link MapRecord MapRecords}.
* @see Redis Documentation: XCLAIM
* @see org.springframework.data.redis.connection.RedisStreamCommands.XClaimOptions
* @see org.springframework.data.redis.connection.stream.MapRecord
* @see reactor.core.publisher.Flux
*/
Flux> claim(K key, String consumerGroup, String newOwner, XClaimOptions xClaimOptions);
/**
* Removes the specified records from the stream. Returns the number of records deleted, that may be different from
* the number of IDs passed in case certain IDs do not exist.
*
* @param key the stream key.
* @param recordIds stream record Id's.
* @return the {@link Mono} emitting the number of removed records.
* @see Redis Documentation: XDEL
*/
default Mono delete(K key, String... recordIds) {
return delete(key, Arrays.stream(recordIds).map(RecordId::of).toArray(RecordId[]::new));
}
/**
* Removes a given {@link Record} from the stream.
*
* @param record must not be {@literal null}.
* @return he {@link Mono} emitting the number of removed records.
*/
default Mono delete(Record record) {
return delete(record.getStream(), record.getId());
}
/**
* Removes the specified records from the stream. Returns the number of records deleted, that may be different from
* the number of IDs passed in case certain IDs do not exist.
*
* @param key the stream key.
* @param recordIds stream record Id's.
* @return the {@link Mono} emitting the number of removed records.
* @see Redis Documentation: XDEL
*/
Mono delete(K key, RecordId... recordIds);
/**
* Create a consumer group at the {@link ReadOffset#latest() latest offset}. This command creates the stream if it
* does not already exist.
*
* @param key the {@literal key} the stream is stored at.
* @param group name of the consumer group.
* @return the {@link Mono} emitting {@literal OK} if successful.. {@literal null} when used in pipeline /
* transaction.
*/
default Mono createGroup(K key, String group) {
return createGroup(key, ReadOffset.latest(), group);
}
/**
* Create a consumer group. This command creates the stream if it does not already exist.
*
* @param key the {@literal key} the stream is stored at.
* @param readOffset the {@link ReadOffset} to apply.
* @param group name of the consumer group.
* @return the {@link Mono} emitting {@literal OK} if successful.
*/
Mono createGroup(K key, ReadOffset readOffset, String group);
/**
* Delete a consumer from a consumer group.
*
* @param key the stream key.
* @param consumer consumer identified by group name and consumer key.
* @return the {@link Mono} {@literal OK} if successful. {@literal null} when used in pipeline / transaction.
*/
Mono deleteConsumer(K key, Consumer consumer);
/**
* Destroy a consumer group.
*
* @param key the stream key.
* @param group name of the consumer group.
* @return the {@link Mono} {@literal OK} if successful. {@literal null} when used in pipeline / transaction.
*/
Mono destroyGroup(K key, String group);
/**
* Obtain information about every consumer in a specific {@literal consumer group} for the stream stored at the
* specified {@literal key}.
*
* @param key the {@literal key} the stream is stored at.
* @param group name of the {@literal consumer group}.
* @return {@literal null} when used in pipeline / transaction.
* @since 2.3
*/
Flux consumers(K key, String group);
/**
* Obtain information about {@literal consumer groups} associated with the stream stored at the specified
* {@literal key}.
*
* @param key the {@literal key} the stream is stored at.
* @return {@literal null} when used in pipeline / transaction.
* @since 2.3
*/
Flux groups(K key);
/**
* Obtain general information about the stream stored at the specified {@literal key}.
*
* @param key the {@literal key} the stream is stored at.
* @return {@literal null} when used in pipeline / transaction.
* @since 2.3
*/
Mono info(K key);
/**
* Obtain the {@link PendingMessagesSummary} for a given {@literal consumer group}.
*
* @param key the {@literal key} the stream is stored at. Must not be {@literal null}.
* @param group the name of the {@literal consumer group}. Must not be {@literal null}.
* @return a summary of pending messages within the given {@literal consumer group} or {@literal null} when used in
* pipeline / transaction.
* @see Redis Documentation: xpending
* @since 2.3
*/
@Nullable
Mono pending(K key, String group);
/**
* Obtained detailed information about all pending messages for a given {@link Consumer}.
*
* @param key the {@literal key} the stream is stored at. Must not be {@literal null}.
* @param consumer the consumer to fetch {@link PendingMessages} for. Must not be {@literal null}.
* @return pending messages for the given {@link Consumer} or {@literal null} when used in pipeline / transaction.
* @see Redis Documentation: xpending
* @since 2.3
*/
default Mono pending(K key, Consumer consumer) {
return pending(key, consumer, Range.unbounded(), -1L);
}
/**
* Obtain detailed information about pending {@link PendingMessage messages} for a given {@link Range} within a
* {@literal consumer group}.
*
* @param key the {@literal key} the stream is stored at. Must not be {@literal null}.
* @param group the name of the {@literal consumer group}. Must not be {@literal null}.
* @param range the range of messages ids to search within. Must not be {@literal null}.
* @param count limit the number of results.
* @return pending messages for the given {@literal consumer group} or {@literal null} when used in pipeline /
* transaction.
* @see Redis Documentation: xpending
* @since 2.3
*/
Mono pending(K key, String group, Range range, long count);
/**
* Obtain detailed information about pending {@link PendingMessage messages} for a given {@link Range} and
* {@link Consumer} within a {@literal consumer group}.
*
* @param key the {@literal key} the stream is stored at. Must not be {@literal null}.
* @param consumer the name of the {@link Consumer}. Must not be {@literal null}.
* @param range the range of messages ids to search within. Must not be {@literal null}.
* @param count limit the number of results.
* @return pending messages for the given {@link Consumer} or {@literal null} when used in pipeline / transaction.
* @see Redis Documentation: xpending
* @since 2.3
*/
Mono pending(K key, Consumer consumer, Range range, long count);
/**
* Get the length of a stream.
*
* @param key the stream key.
* @return the {@link Mono} emitting the length of the stream.
* @see Redis Documentation: XLEN
*/
Mono size(K key);
/**
* Read records from a stream within a specific {@link Range}.
*
* @param key the stream key.
* @param range must not be {@literal null}.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XRANGE
*/
default Flux> range(K key, Range range) {
return range(key, range, Limit.unlimited());
}
/**
* Read records from a stream within a specific {@link Range} applying a {@link Limit}.
*
* @param key the stream key.
* @param range must not be {@literal null}.
* @param limit must not be {@literal null}.
* @return lthe {@link Flux} emitting records one by one.
* @see Redis Documentation: XRANGE
*/
Flux> range(K key, Range range, Limit limit);
/**
* Read all records from a stream within a specific {@link Range}.
*
* @param targetType the target type of the payload.
* @param key the stream key.
* @param range must not be {@literal null}.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XRANGE
*/
default Flux> range(Class targetType, K key, Range range) {
return range(targetType, key, range, Limit.unlimited());
}
/**
* Read records from a stream within a specific {@link Range} applying a {@link Limit}.
*
* @param targetType the target type of the payload.
* @param key the stream key.
* @param range must not be {@literal null}.
* @param limit must not be {@literal null}.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XRANGE
*/
default Flux> range(Class targetType, K key, Range range, Limit limit) {
Assert.notNull(targetType, "Target type must not be null");
return range(key, range, limit).map(it -> map(it, targetType));
}
/**
* Read records from a {@link StreamOffset} as {@link ObjectRecord}.
*
* @param stream the stream to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREAD
*/
@SuppressWarnings("unchecked")
default Flux> read(StreamOffset stream) {
Assert.notNull(stream, "StreamOffset must not be null");
return read(StreamReadOptions.empty(), new StreamOffset[] { stream });
}
/**
* Read records from a {@link StreamOffset} as {@link ObjectRecord}.
*
* @param targetType the target type of the payload.
* @param stream the stream to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREAD
*/
@SuppressWarnings("unchecked")
default Flux> read(Class targetType, StreamOffset stream) {
Assert.notNull(stream, "StreamOffset must not be null");
return read(targetType, StreamReadOptions.empty(), new StreamOffset[] { stream });
}
/**
* Read records from one or more {@link StreamOffset}s.
*
* @param streams the streams to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREAD
*/
default Flux> read(StreamOffset... streams) {
return read(StreamReadOptions.empty(), streams);
}
/**
* Read records from one or more {@link StreamOffset}s as {@link ObjectRecord}.
*
* @param targetType the target type of the payload.
* @param streams the streams to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREAD
*/
default Flux> read(Class targetType, StreamOffset... streams) {
return read(targetType, StreamReadOptions.empty(), streams);
}
/**
* Read records from one or more {@link StreamOffset}s.
*
* @param readOptions read arguments.
* @param streams the streams to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREAD
*/
Flux> read(StreamReadOptions readOptions, StreamOffset... streams);
/**
* Read records from one or more {@link StreamOffset}s as {@link ObjectRecord}.
*
* @param targetType the target type of the payload.
* @param readOptions read arguments.
* @param streams the streams to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREAD
*/
default Flux> read(Class targetType, StreamReadOptions readOptions,
StreamOffset... streams) {
Assert.notNull(targetType, "Target type must not be null");
return read(readOptions, streams).map(it -> map(it, targetType));
}
/**
* Read records from one or more {@link StreamOffset}s using a consumer group.
*
* @param consumer consumer/group.
* @param streams the streams to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREADGROUP
*/
default Flux> read(Consumer consumer, StreamOffset... streams) {
return read(consumer, StreamReadOptions.empty(), streams);
}
/**
* Read records from one or more {@link StreamOffset}s using a consumer group as {@link ObjectRecord}.
*
* @param targetType the target type of the payload.
* @param consumer consumer/group.
* @param streams the streams to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREADGROUP
*/
default Flux> read(Class targetType, Consumer consumer, StreamOffset... streams) {
return read(targetType, consumer, StreamReadOptions.empty(), streams);
}
/**
* Read records from one or more {@link StreamOffset}s using a consumer group.
*
* @param consumer consumer/group.
* @param readOptions read arguments.
* @param streams the streams to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREADGROUP
*/
Flux> read(Consumer consumer, StreamReadOptions readOptions, StreamOffset... streams);
/**
* Read records from one or more {@link StreamOffset}s using a consumer group as {@link ObjectRecord}.
*
* @param targetType the target type of the payload.
* @param consumer consumer/group.
* @param readOptions read arguments.
* @param streams the streams to read from.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREADGROUP
*/
default Flux> read(Class targetType, Consumer consumer, StreamReadOptions readOptions,
StreamOffset... streams) {
Assert.notNull(targetType, "Target type must not be null");
return read(consumer, readOptions, streams).map(it -> map(it, targetType));
}
/**
* Read records from a stream within a specific {@link Range} in reverse order.
*
* @param key the stream key.
* @param range must not be {@literal null}.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREVRANGE
*/
default Flux> reverseRange(K key, Range range) {
return reverseRange(key, range, Limit.unlimited());
}
/**
* Read records from a stream within a specific {@link Range} applying a {@link Limit} in reverse order.
*
* @param key the stream key.
* @param range must not be {@literal null}.
* @param limit must not be {@literal null}.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREVRANGE
*/
Flux> reverseRange(K key, Range range, Limit limit);
/**
* Read records from a stream within a specific {@link Range} in reverse order as {@link ObjectRecord}.
*
* @param targetType the target type of the payload.
* @param key the stream key.
* @param range must not be {@literal null}.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREVRANGE
*/
default Flux> reverseRange(Class targetType, K key, Range range) {
return reverseRange(targetType, key, range, Limit.unlimited());
}
/**
* Read records from a stream within a specific {@link Range} applying a {@link Limit} in reverse order as
* {@link ObjectRecord}.
*
* @param targetType the target type of the payload.
* @param key the stream key.
* @param range must not be {@literal null}.
* @param limit must not be {@literal null}.
* @return the {@link Flux} emitting records one by one.
* @see Redis Documentation: XREVRANGE
*/
default Flux> reverseRange(Class targetType, K key, Range range, Limit limit) {
Assert.notNull(targetType, "Target type must not be null");
return reverseRange(key, range, limit).map(it -> map(it, targetType));
}
/**
* Trims the stream to {@code count} elements.
*
* @param key the stream key.
* @param count length of the stream.
* @return number of removed entries.
* @see Redis Documentation: XTRIM
*/
Mono trim(K key, long count);
/**
* Trims the stream to {@code count} elements.
*
* @param key the stream key.
* @param count length of the stream.
* @param approximateTrimming the trimming must be performed in a approximated way in order to maximize performances.
* @return number of removed entries.
* @since 2.4
* @see Redis Documentation: XTRIM
*/
Mono trim(K key, long count, boolean approximateTrimming);
/**
* Get the {@link HashMapper} for a specific type.
*
* @param targetType must not be {@literal null}.
* @param
* @return the {@link HashMapper} suitable for a given type;
*/
@Override
HashMapper getHashMapper(Class targetType);
/**
* Map records from {@link MapRecord} to {@link ObjectRecord}.
*
* @param record the stream records to map.
* @param targetType the target type of the payload.
* @return the mapped {@link ObjectRecord}.
* @since 2.x
*/
default ObjectRecord map(MapRecord record, Class targetType) {
Assert.notNull(record, "Records must not be null");
Assert.notNull(targetType, "Target type must not be null");
return StreamObjectMapper.toObjectRecord(record, this, targetType);
}
/**
* Deserialize a {@link ByteBufferRecord} using the configured serialization context into a {@link MapRecord}.
*
* @param record the stream record to map.
* @return deserialized {@link MapRecord}.
* @since 2.x
*/
MapRecord deserializeRecord(ByteBufferRecord record);
}