io.quarkus.redis.datasource.stream.TransactionalStreamCommands Maven / Gradle / Ivy
Show all versions of quarkus-redis-client Show documentation
package io.quarkus.redis.datasource.stream;
import java.time.Duration;
import java.util.Map;
import io.quarkus.redis.datasource.TransactionalRedisCommands;
/**
* Allows executing commands manipulating streams.
* See the stream command list for further information about these
* commands.
*
*
* The messages are represented as {@code Map}.
* This API is intended to be used in a Redis transaction ({@code MULTI}), thus, all command methods return {@code void}.
*
* @param the type of the keys, often {@link String}
* @param the key type of the messages, generally {@link String}
* @param the value type of the messages
*/
public interface TransactionalStreamCommands extends TransactionalRedisCommands {
/**
* Execute the command XACK.
* Summary: Marks a pending message as correctly processed, effectively removing it from the pending entries list
* of the consumer group. Return value of the command is the number of messages successfully acknowledged, that is,
* the IDs we were actually able to resolve in the PEL.
*
* The {@code XACK} command removes one or multiple messages from the Pending Entries List (PEL) of a stream consumer
* group. A message is pending, and as such stored inside the PEL, when it was delivered to some consumer, normally
* as a side effect of calling {@code XREADGROUP}, or when a consumer took ownership of a message
* calling {@code XCLAIM}. The pending message was delivered to some consumer but the server is yet not sure it was
* processed at least once. So new calls to {@code XREADGROUP} to grab the messages history for a consumer
* (for instance using an ID of 0), will return such message. Similarly, the pending message will be listed by the
* {@code XPENDING} command, that inspects the PEL.
*
* Once a consumer successfully processes a message, it should call {@code XACK} so that such message does not get
* processed again, and as a side effect, the PEL entry about this message is also purged, releasing memory from
* the Redis server.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key the key
* @param group the name of the consumer group
* @param ids the message ids to acknowledge
*/
void xack(K key, String group, String... ids);
/**
* Execute the command XADD.
* Summary: Appends the specified stream entry to the stream at the specified key. If the key does not exist, as a
* side effect of running this command the key is created with a stream value. The creation of stream's key can be
* disabled with the {@code NOMKSTREAM} option.
*
* An entry is composed of a list of field-value pairs. The field-value pairs are stored in the same order they are
* given by the user. Commands that read the stream, such as {@code XRANGE} or {@code XREAD}, are guaranteed to
* return the fields and values exactly in the same order they were added by {@code XADD}.
*
* {@code XADD} is the only Redis command that can add data to a stream, but there are other commands, such as
* {@code XDEL} and {@code XTRIM}, that are able to remove data from a stream.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key the key
* @param payload the payload to write to the stream, must not be {@code null}
*/
void xadd(K key, Map payload);
/**
* Execute the command XADD.
* Summary: Appends the specified stream entry to the stream at the specified key. If the key does not exist, as a
* side effect of running this command the key is created with a stream value. The creation of stream's key can be
* disabled with the {@code NOMKSTREAM} option.
*
* An entry is composed of a list of field-value pairs. The field-value pairs are stored in the same order they are
* given by the user. Commands that read the stream, such as {@code XRANGE} or {@code XREAD}, are guaranteed to
* return the fields and values exactly in the same order they were added by {@code XADD}.
*
* {@code XADD} is the only Redis command that can add data to a stream, but there are other commands, such as
* {@code XDEL} and {@code XTRIM}, that are able to remove data from a stream.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key the key
* @param args the extra parameters
* @param payload the payload to write to the stream, must not be {@code null}
*/
void xadd(K key, XAddArgs args, Map payload);
/**
* Execute the command XAUTOCLAIM.
* Summary: Changes (or acquires) ownership of messages in a consumer group, as if the messages were delivered to
* the specified consumer.
*
* This command transfers ownership of pending stream entries that match the specified criteria. Conceptually,
* {@code XAUTOCLAIM} is equivalent to calling {@code XPENDING} and then {@code XCLAIM}, but provides a more
* straightforward way to deal with message delivery failures via {@code SCAN}-like semantics.
*
* Like {@code XCLAIM}, the command operates on the stream entries at {@code key} and in the context of the provided
* {@code group}. It transfers ownership to @{code consumer} of messages pending for more than {@code min-idle-time}
* milliseconds and having an equal or greater ID than {@code start}.
*
* Group: stream
* Requires Redis 6.2.0+
*
*
* @param key key the key
* @param group string the consumer group
* @param consumer string the consumer id
* @param minIdleTime the min pending time of the message to claim
* @param start the min id of the message to claim
*/
void xautoclaim(K key, String group, String consumer, Duration minIdleTime, String start);
/**
* Execute the command XAUTOCLAIM.
* Summary: Changes (or acquires) ownership of messages in a consumer group, as if the messages were delivered to
* the specified consumer.
*
* This command transfers ownership of pending stream entries that match the specified criteria. Conceptually,
* {@code XAUTOCLAIM} is equivalent to calling {@code XPENDING} and then {@code XCLAIM}, but provides a more
* straightforward way to deal with message delivery failures via {@code SCAN}-like semantics.
*
* Like {@code XCLAIM}, the command operates on the stream entries at {@code key} and in the context of the provided
* {@code group}. It transfers ownership to @{code consumer} of messages pending for more than {@code min-idle-time}
* milliseconds and having an equal or greater ID than {@code start}.
*
* Group: stream
* Requires Redis 6.2.0+
*
*
* @param key key the key
* @param group string the consumer group
* @param consumer string the consumer id
* @param minIdleTime the min pending time of the message to claim
* @param start the min id of the message to claim
* @param count the upper limit of the number of entries to claim, default is 100.
*/
void xautoclaim(K key, String group, String consumer, Duration minIdleTime, String start, int count);
/**
* Execute the command XAUTOCLAIM.
* Summary: Changes (or acquires) ownership of messages in a consumer group, as if the messages were delivered to
* the specified consumer.
*
* This command transfers ownership of pending stream entries that match the specified criteria. Conceptually,
* {@code XAUTOCLAIM} is equivalent to calling {@code XPENDING} and then {@code XCLAIM}, but provides a more
* straightforward way to deal with message delivery failures via {@code SCAN}-like semantics.
*
* Like {@code XCLAIM}, the command operates on the stream entries at {@code key} and in the context of the provided
* {@code group}. It transfers ownership to @{code consumer} of messages pending for more than {@code min-idle-time}
* milliseconds and having an equal or greater ID than {@code start}.
*
* Group: stream
* Requires Redis 6.2.0+
*
*
* @param key key the key
* @param group string the consumer group
* @param consumer string the consumer id
* @param minIdleTime the min pending time of the message to claim
* @param start the min id of the message to claim
* @param count the upper limit of the number of entries to claim, default is 100.
* @param justId if {@code true} the returned structure would only contain the id of the messages and not the payloads
*/
void xautoclaim(K key, String group, String consumer, Duration minIdleTime, String start, int count, boolean justId);
/**
* Execute the command XCLAIM.
* Summary: In the context of a stream consumer group, this command changes the ownership of a pending message, so
* that the new owner is the consumer specified as the command argument.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param group string the consumer group
* @param consumer string the consumer id
* @param minIdleTime the min pending time of the message to claim
* @param id the message ids to claim, must not be empty, must not contain {@code null}
*/
void xclaim(K key, String group, String consumer, Duration minIdleTime, String... id);
/**
* Execute the command XCLAIM.
* Summary: In the context of a stream consumer group, this command changes the ownership of a pending message, so
* that the new owner is the consumer specified as the command argument.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param group string the consumer group
* @param consumer string the consumer id
* @param minIdleTime the min pending time of the message to claim
* @param args the extra command parameters
* @param id the message ids to claim, must not be empty, must not contain {@code null}
*/
void xclaim(K key, String group, String consumer, Duration minIdleTime, XClaimArgs args, String... id);
/**
* Execute the command XDEL.
* Summary: Removes the specified entries from a stream, and returns the number of entries deleted. This number may
* be less than the number of IDs passed to the command in the case where some of the specified IDs do not exist in
* the stream.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param id the message ids, must not be empty, must not contain {@code null}
*/
void xdel(K key, String... id);
/**
* Execute the command XGROUP CREATE.
* Summary: Create a new consumer group uniquely identified by {@code groupname} for the stream stored at {@code key}
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param groupname the name of the group, must be unique, and not {@code null}
* @param from the last delivered entry in the stream from the new group's perspective. The special ID {@code $}
* is the ID of the last entry in the stream, but you can substitute it with any valid ID.
*/
void xgroupCreate(K key, String groupname, String from);
/**
* Execute the command XGROUP CREATE.
* Summary: Create a new consumer group uniquely identified by {@code groupname} for the stream stored at {@code key}
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param groupname the name of the group, must be unique, and not {@code null}
* @param from the last delivered entry in the stream from the new group's perspective. The special ID {@code $}
* is the ID of the last entry in the stream, but you can substitute it with any valid ID.
* @param args the extra command parameters
*/
void xgroupCreate(K key, String groupname, String from, XGroupCreateArgs args);
/**
* Execute the command XGROUP CREATECONSUMER.
* Summary: Create a consumer named {@code consumername} in the consumer group {@code groupname} of the stream
* that's stored at {@code key}.
*
* Consumers are also created automatically whenever an operation, such as {@code XREADGROUP}, references a consumer
* that doesn't exist.
*
* Group: stream
* Requires Redis 6.2.0+
*
*
* @param key key the key
* @param groupname the name of the group, must be unique, and not {@code null}
* @param consumername the consumer name
*/
void xgroupCreateConsumer(K key, String groupname, String consumername);
/**
* Execute the command XGROUP DELCONSUMER.
* Summary: Deletes a consumer from the consumer group.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param groupname the name of the group, must be unique, and not {@code null}
* @param consumername the consumer name
*/
void xgroupDelConsumer(K key, String groupname, String consumername);
/**
* Execute the command XGROUP DESTROY.
* Summary: Completely destroys a consumer group. The consumer group will be destroyed even if there are active
* consumers, and pending messages, so make sure to call this command only when really needed.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param groupname the name of the group, must be unique, and not {@code null}
*/
void xgroupDestroy(K key, String groupname);
/**
* Execute the command XGROUP SETID.
* Summary: Set the last delivered ID for a consumer group.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param groupname the name of the group, must be unique, and not {@code null}
* @param from the last delivered entry in the stream from the new group's perspective. The special ID {@code $}
* is the ID of the last entry in the stream, but you can substitute it with any valid ID.
*/
void xgroupSetId(K key, String groupname, String from);
/**
* Execute the command XGROUP SETID.
* Summary: Set the last delivered ID for a consumer group.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param groupname the name of the group, must be unique, and not {@code null}
* @param from the last delivered entry in the stream from the new group's perspective. The special ID {@code $}
* is the ID of the last entry in the stream, but you can substitute it with any valid ID.
* @param args the extra command parameters
*/
void xgroupSetId(K key, String groupname, String from, XGroupSetIdArgs args);
/**
* Execute the command XLEN.
* Summary: Returns the number of entries inside a stream.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
*/
void xlen(K key);
/**
* Execute the command XRANGE.
* Summary: The command returns the stream entries matching a given range of IDs.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param range the range, must not be {@code null}
* @param count the max number of entries to return
*/
void xrange(K key, StreamRange range, int count);
/**
* Execute the command XRANGE.
* Summary: The command returns the stream entries matching a given range of IDs.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param range the range, must not be {@code null}
*/
void xrange(K key, StreamRange range);
/**
* Execute the command XREAD.
* Summary: Read data from one or multiple streams, only returning entries with an ID greater than the last received
* ID reported by the caller. This command has an option to block if items are not available, in a similar fashion
* to {@code BRPOP} or {@code BZPOPMIN} and others.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key of the stream
* @param id the last read id
*/
void xread(K key, String id);
/**
* Execute the command XREAD.
* Summary: Read data from one or multiple streams, only returning entries with an ID greater than the last received
* ID reported by the caller. This command has an option to block if items are not available, in a similar fashion
* to {@code BRPOP} or {@code BZPOPMIN} and others.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param lastIdsPerStream the map of key -> id indicating the last received id per stream to read
*/
void xread(Map lastIdsPerStream);
/**
* Execute the command XREAD.
* Summary: Read data from one or multiple streams, only returning entries with an ID greater than the last received
* ID reported by the caller. This command has an option to block if items are not available, in a similar fashion
* to {@code BRPOP} or {@code BZPOPMIN} and others.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key of the stream
* @param id the last read id
* @param args the extra parameter
*/
void xread(K key, String id, XReadArgs args);
/**
* Execute the command XREAD.
* Summary: Read data from one or multiple streams, only returning entries with an ID greater than the last received
* ID reported by the caller. This command has an option to block if items are not available, in a similar fashion
* to {@code BRPOP} or {@code BZPOPMIN} and others.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param lastIdsPerStream the map of key -> id indicating the last received id per stream to read
* @param args the extra parameter
*/
void xread(Map lastIdsPerStream, XReadArgs args);
/**
* Execute the command XREADGROUP.
* Summary: The {@code XREADGROUP} command is a special version of the {@code XREAD} command with support for
* consumer groups.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param group the group name
* @param consumer the consumer name
* @param key the stream key
* @param id the last read id
*/
void xreadgroup(String group, String consumer, K key, String id);
/**
* Execute the command XREADGROUP.
* Summary: The {@code XREADGROUP} command is a special version of the {@code XREAD} command with support for
* consumer groups.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param group the group name
* @param consumer the consumer name
* @param lastIdsPerStream the map of key -> id indicating the last received id per stream to read
*/
void xreadgroup(String group, String consumer, Map lastIdsPerStream);
/**
* Execute the command XREADGROUP.
* Summary: The {@code XREADGROUP} command is a special version of the {@code XREAD} command with support for
* consumer groups.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param group the group name
* @param consumer the consumer name
* @param key the stream key
* @param id the last read id
* @param args the extra parameter
*/
void xreadgroup(String group, String consumer, K key, String id, XReadGroupArgs args);
/**
* Execute the command XREADGROUP.
* Summary: The {@code XREADGROUP} command is a special version of the {@code XREAD} command with support for
* consumer groups.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param group the group name
* @param consumer the consumer name
* @param lastIdsPerStream the map of key -> id indicating the last received id per stream to read
* @param args the extra parameter
*/
void xreadgroup(String group, String consumer, Map lastIdsPerStream, XReadGroupArgs args);
/**
* Execute the command XREVRANGE.
* Summary: This command is exactly like {@code XRANGE}, but with the notable difference of returning the entries
* in reverse order, and also taking the start-end range in reverse order: in {@code XREVRANGE} you need to state
* the end ID and later the start ID, and the command will produce all the element between (or exactly like) the
* two IDs, starting from the end side.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param range the range, must not be {@code null}
* @param count the max number of entries to return
*/
void xrevrange(K key, StreamRange range, int count);
/**
* Execute the command XRANGE.
* Summary: This command is exactly like {@code XRANGE}, but with the notable difference of returning the entries
* in reverse order, and also taking the start-end range in reverse order: in {@code XREVRANGE} you need to state
* the end ID and later the start ID, and the command will produce all the element between (or exactly like) the
* two IDs, starting from the end side.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key key the key
* @param range the range, must not be {@code null}
*/
void xrevrange(K key, StreamRange range);
/**
* Execute the command XTRIM.
* Summary: Trims the stream by evicting older entries (entries with lower IDs) if needed.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key the key
* @param threshold the threshold
*/
void xtrim(K key, String threshold);
/**
* Execute the command XTRIM.
* Summary: Trims the stream by evicting older entries (entries with lower IDs) if needed.
*
* Group: stream
* Requires Redis 5.0.0+
*
*
* @param key the key
* @param args the extra parameters
*/
void xtrim(K key, XTrimArgs args);
/**
* Execute the command XPENDING.
* Summary: The XPENDING command is the interface to inspect the list of pending messages, and is as thus a very
* important command in order to observe and understand what is happening with a streams consumer groups: what
* clients are active, what messages are pending to be consumed, or to see if there are idle messages.
*
* Group: stream
* Requires Redis 5.0.0+
*
* This variant of xpending uses the summary form.
*
* @param key the key
* @param group the group
*/
void xpending(K key, String group);
/**
* Execute the command XPENDING.
* Summary: The XPENDING command is the interface to inspect the list of pending messages, and is as thus a very
* important command in order to observe and understand what is happening with a streams consumer groups: what
* clients are active, what messages are pending to be consumed, or to see if there are idle messages.
*
* Group: stream
* Requires Redis 5.0.0+
*
* This variant of xpending uses the extended form.
*
* @param key the key
* @param group the group
* @param range the range
* @param count the number of message to include
*/
void xpending(K key, String group, StreamRange range, int count);
/**
* Execute the command XPENDING.
* Summary: The XPENDING command is the interface to inspect the list of pending messages, and is as thus a very
* important command in order to observe and understand what is happening with a streams consumer groups: what
* clients are active, what messages are pending to be consumed, or to see if there are idle messages.
*
* Group: stream
* Requires Redis 5.0.0+
*
* This variant of xpending uses the extended form.
*
* If the extra parameter include the name of the consumer, the produced list will only contain 0 or 1 item.
*
* @param key the key
* @param group the group
* @param range the range
* @param count the number of message to include
* @param args the extra argument (idle and consumer)
*/
void xpending(K key, String group, StreamRange range, int count, XPendingArgs args);
}