io.nats.client

Interface JetStreamManagement

public interface JetStreamManagement

JetStream Management context for creation and access to streams and consumers in NATS.

Using JetStream Management is the recommended way of managing Jetstream resources.

Basic usage examples can be found in JetStream

Method Summary

Modifier and Type	Method and Description
ConsumerInfo	addOrUpdateConsumer(java.lang.String streamName, ConsumerConfiguration config) Loads or creates a consumer.
StreamInfo	addStream(StreamConfiguration config) Loads or creates a stream.
ConsumerInfo	createConsumer(java.lang.String streamName, ConsumerConfiguration config) Creates a consumer.
boolean	deleteConsumer(java.lang.String streamName, java.lang.String consumerName) Deletes a consumer.
boolean	deleteMessage(java.lang.String streamName, long seq) Deletes a message, overwriting the message data with garbage This can be considered an expensive (time-consuming) operation, but is more secure.
boolean	deleteMessage(java.lang.String streamName, long seq, boolean erase) Deletes a message, optionally erasing the content of the message.
boolean	deleteStream(java.lang.String streamName) Deletes an existing stream.
AccountStatistics	getAccountStatistics() Gets the account statistics for the logged in account.
ConsumerInfo	getConsumerInfo(java.lang.String streamName, java.lang.String consumerName) Gets the info for an existing consumer.
java.util.List<java.lang.String>	getConsumerNames(java.lang.String streamName) Return a list of consumers by name
java.util.List<ConsumerInfo>	getConsumers(java.lang.String streamName) Return a list of ConsumerInfo objects.
MessageInfo	getFirstMessage(java.lang.String streamName, java.lang.String subject) Get MessageInfo for the first message of the subject.
MessageInfo	getFirstMessage(java.lang.String streamName, java.time.ZonedDateTime startTime) Get MessageInfo for the first message created at or after the start time.
MessageInfo	getFirstMessage(java.lang.String streamName, java.time.ZonedDateTime startTime, java.lang.String subject) Get MessageInfo for the first message created at or after the start time matching the subject.
MessageInfo	getLastMessage(java.lang.String streamName, java.lang.String subject) Get MessageInfo for the last message of the subject.
MessageInfo	getMessage(java.lang.String streamName, long seq) Get MessageInfo for the message with the exact sequence in the stream.
MessageInfo	getMessage(java.lang.String streamName, io.nats.client.api.MessageGetRequest messageGetRequest) Get MessageInfo for the message matching the MessageGetRequest.
MessageInfo	getNextMessage(java.lang.String streamName, long seq, java.lang.String subject) Get MessageInfo for the message of the message sequence is equal to or greater the requested sequence for the subject.
StreamInfo	getStreamInfo(java.lang.String streamName) Gets the info for an existing stream.
StreamInfo	getStreamInfo(java.lang.String streamName, StreamInfoOptions options) Gets the info for an existing stream, and include subject or deleted details as defined by StreamInfoOptions.
java.util.List<java.lang.String>	getStreamNames() Get the names of all streams.
java.util.List<java.lang.String>	getStreamNames(java.lang.String subjectFilter) Get a list of stream names that have subjects matching the subject filter.
java.util.List<StreamInfo>	getStreams() Return a list of StreamInfo objects.
java.util.List<StreamInfo>	getStreams(java.lang.String subjectFilter) Return a list of StreamInfo objects that have subjects matching the filter.
JetStream	jetStream() Gets a context for publishing and subscribing to subjects backed by Jetstream streams and consumers, using the same connection and JetStreamOptions as the management.
ConsumerPauseResponse	pauseConsumer(java.lang.String streamName, java.lang.String consumerName, java.time.ZonedDateTime pauseUntil) Pauses a consumer.
PurgeResponse	purgeStream(java.lang.String streamName) Purge stream messages
PurgeResponse	purgeStream(java.lang.String streamName, PurgeOptions options) Purge messages for a specific subject
boolean	resumeConsumer(java.lang.String streamName, java.lang.String consumerName) Resumes a paused consumer.
ConsumerInfo	updateConsumer(java.lang.String streamName, ConsumerConfiguration config) Updates an existing consumer.
StreamInfo	updateStream(StreamConfiguration config) Updates an existing stream.

Method Detail

getAccountStatistics

AccountStatistics getAccountStatistics()
                                throws java.io.IOException,
                                       JetStreamApiException

Gets the account statistics for the logged in account.

Returns:

account statistics

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

java.lang.IllegalArgumentException - the server is not JetStream enabled

addStream

StreamInfo addStream(StreamConfiguration config)
              throws java.io.IOException,
                     JetStreamApiException

Loads or creates a stream.

Parameters:

config - the stream configuration to use.

Returns:

stream information

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

java.lang.IllegalArgumentException - the configuration is missing or invalid

updateStream

StreamInfo updateStream(StreamConfiguration config)
                 throws java.io.IOException,
                        JetStreamApiException

Updates an existing stream.

Parameters:

config - the stream configuration to use.

Returns:

stream information

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

java.lang.IllegalArgumentException - the configuration is missing or invalid

deleteStream

boolean deleteStream(java.lang.String streamName)
              throws java.io.IOException,
                     JetStreamApiException

Deletes an existing stream.

Parameters:

streamName - the stream name to use.

Returns:

true if the delete succeeded. Usually throws a JetStreamApiException otherwise

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getStreamInfo

StreamInfo getStreamInfo(java.lang.String streamName)
                  throws java.io.IOException,
                         JetStreamApiException

Gets the info for an existing stream. Does not retrieve any optional data. See the overloaded version that accepts StreamInfoOptions

Parameters:

streamName - the stream name to use.

Returns:

stream information

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getStreamInfo

StreamInfo getStreamInfo(java.lang.String streamName,
                         StreamInfoOptions options)
                  throws java.io.IOException,
                         JetStreamApiException

Gets the info for an existing stream, and include subject or deleted details as defined by StreamInfoOptions.

Parameters:

streamName - the stream name to use.

options - the stream info options. If null, request will not return any optional data.

Returns:

stream information

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

purgeStream

PurgeResponse purgeStream(java.lang.String streamName)
                   throws java.io.IOException,
                          JetStreamApiException

Purge stream messages

Parameters:

streamName - the stream name to use.

Returns:

PurgeResponse the purge response

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

purgeStream

PurgeResponse purgeStream(java.lang.String streamName,
                          PurgeOptions options)
                   throws java.io.IOException,
                          JetStreamApiException

Purge messages for a specific subject

Parameters:

streamName - the stream name to use.

options - the purge options

Returns:

PurgeResponse the purge response

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

addOrUpdateConsumer

ConsumerInfo addOrUpdateConsumer(java.lang.String streamName,
                                 ConsumerConfiguration config)
                          throws java.io.IOException,
                                 JetStreamApiException

Loads or creates a consumer.

Parameters:

streamName - name of the stream

config - the consumer configuration to use.

Returns:

consumer information.

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

createConsumer

ConsumerInfo createConsumer(java.lang.String streamName,
                            ConsumerConfiguration config)
                     throws java.io.IOException,
                            JetStreamApiException

Creates a consumer. Must not already exist.

Parameters:

streamName - name of the stream

config - the consumer configuration to use.

Returns:

consumer information.

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data such as the consumer already exists

updateConsumer

ConsumerInfo updateConsumer(java.lang.String streamName,
                            ConsumerConfiguration config)
                     throws java.io.IOException,
                            JetStreamApiException

Updates an existing consumer. Must already exist.

Parameters:

streamName - name of the stream

config - the consumer configuration to use.

Returns:

consumer information.

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data such as the consumer does not already exist

deleteConsumer

boolean deleteConsumer(java.lang.String streamName,
                       java.lang.String consumerName)
                throws java.io.IOException,
                       JetStreamApiException

Deletes a consumer.

Parameters:

streamName - name of the stream

consumerName - the name of the consumer.

Returns:

true if the delete succeeded

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data, for instance the consumer does not exist.

pauseConsumer

ConsumerPauseResponse pauseConsumer(java.lang.String streamName,
                                    java.lang.String consumerName,
                                    java.time.ZonedDateTime pauseUntil)
                             throws java.io.IOException,
                                    JetStreamApiException

Pauses a consumer.

Parameters:

streamName - name of the stream

consumerName - the name of the consumer.

pauseUntil - consumer is paused until this time.

Returns:

ConsumerPauseResponse the pause response

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data, for instance the consumer does not exist.

resumeConsumer

boolean resumeConsumer(java.lang.String streamName,
                       java.lang.String consumerName)
                throws java.io.IOException,
                       JetStreamApiException

Resumes a paused consumer.

Parameters:

streamName - name of the stream

consumerName - the name of the consumer.

Returns:

true if the resume succeeded

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data, for instance the consumer does not exist.

getConsumerInfo

ConsumerInfo getConsumerInfo(java.lang.String streamName,
                             java.lang.String consumerName)
                      throws java.io.IOException,
                             JetStreamApiException

Gets the info for an existing consumer.

Parameters:

streamName - name of the stream

consumerName - the name of the consumer.

Returns:

consumer information

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getConsumerNames

java.util.List<java.lang.String> getConsumerNames(java.lang.String streamName)
                                           throws java.io.IOException,
                                                  JetStreamApiException

Return a list of consumers by name

Parameters:

streamName - the name of the stream.

Returns:

The list of names

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getConsumers

java.util.List<ConsumerInfo> getConsumers(java.lang.String streamName)
                                   throws java.io.IOException,
                                          JetStreamApiException

Return a list of ConsumerInfo objects.

Parameters:

streamName - the name of the stream.

Returns:

The list of ConsumerInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getStreamNames

java.util.List<java.lang.String> getStreamNames()
                                         throws java.io.IOException,
                                                JetStreamApiException

Get the names of all streams.

Returns:

The list of names

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getStreamNames

java.util.List<java.lang.String> getStreamNames(java.lang.String subjectFilter)
                                         throws java.io.IOException,
                                                JetStreamApiException

Get a list of stream names that have subjects matching the subject filter.

Parameters:

subjectFilter - the subject. Wildcards are allowed.

Returns:

The list of stream names matching the subject filter. May be empty, will not be null.

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getStreams

java.util.List<StreamInfo> getStreams()
                               throws java.io.IOException,
                                      JetStreamApiException

Return a list of StreamInfo objects.

Returns:

The list of StreamInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getStreams

java.util.List<StreamInfo> getStreams(java.lang.String subjectFilter)
                               throws java.io.IOException,
                                      JetStreamApiException

Return a list of StreamInfo objects that have subjects matching the filter.

Parameters:

subjectFilter - the filter to limit the streams by subjects. Wildcards allowed.

Returns:

The list of StreamInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getMessage

MessageInfo getMessage(java.lang.String streamName,
                       long seq)
                throws java.io.IOException,
                       JetStreamApiException

Get MessageInfo for the message with the exact sequence in the stream.

Parameters:

streamName - the name of the stream.

seq - the sequence number of the message

Returns:

The MessageInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getMessage

MessageInfo getMessage(java.lang.String streamName,
                       io.nats.client.api.MessageGetRequest messageGetRequest)
                throws java.io.IOException,
                       JetStreamApiException

Get MessageInfo for the message matching the MessageGetRequest.

Parameters:

streamName - the name of the stream.

messageGetRequest - the MessageGetRequest to get a message

Returns:

The MessageInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getLastMessage

MessageInfo getLastMessage(java.lang.String streamName,
                           java.lang.String subject)
                    throws java.io.IOException,
                           JetStreamApiException

Get MessageInfo for the last message of the subject.

Parameters:

streamName - the name of the stream.

subject - the subject to get the last message for.

Returns:

The MessageInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getFirstMessage

MessageInfo getFirstMessage(java.lang.String streamName,
                            java.lang.String subject)
                     throws java.io.IOException,
                            JetStreamApiException

Get MessageInfo for the first message of the subject.

Parameters:

streamName - the name of the stream.

subject - the subject to get the first message for.

Returns:

The MessageInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getFirstMessage

MessageInfo getFirstMessage(java.lang.String streamName,
                            java.time.ZonedDateTime startTime)
                     throws java.io.IOException,
                            JetStreamApiException

Get MessageInfo for the first message created at or after the start time.

This API 1) is currently EXPERIMENTAL and is subject to change. 2) Works on Server 2.11 or later

Parameters:

streamName - the name of the stream.

startTime - the start time to get the first message for.

Returns:

The MessageInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getFirstMessage

MessageInfo getFirstMessage(java.lang.String streamName,
                            java.time.ZonedDateTime startTime,
                            java.lang.String subject)
                     throws java.io.IOException,
                            JetStreamApiException

Get MessageInfo for the first message created at or after the start time matching the subject.

This API 1) is currently EXPERIMENTAL and is subject to change. 2) Works on Server 2.11 or later

Parameters:

streamName - the name of the stream.

startTime - the start time to get the first message for.

subject - the subject to get the first message for.

Returns:

The MessageInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

getNextMessage

MessageInfo getNextMessage(java.lang.String streamName,
                           long seq,
                           java.lang.String subject)
                    throws java.io.IOException,
                           JetStreamApiException

Get MessageInfo for the message of the message sequence is equal to or greater the requested sequence for the subject.

Parameters:

streamName - the name of the stream.

seq - the first possible sequence number of the message

subject - the subject to get the next message for.

Returns:

The MessageInfo

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

deleteMessage

boolean deleteMessage(java.lang.String streamName,
                      long seq)
               throws java.io.IOException,
                      JetStreamApiException

Deletes a message, overwriting the message data with garbage This can be considered an expensive (time-consuming) operation, but is more secure.

Parameters:

streamName - name of the stream

seq - the sequence number of the message

Returns:

true if the delete succeeded

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

deleteMessage

boolean deleteMessage(java.lang.String streamName,
                      long seq,
                      boolean erase)
               throws java.io.IOException,
                      JetStreamApiException

Deletes a message, optionally erasing the content of the message.

Parameters:

streamName - name of the stream

seq - the sequence number of the message

erase - whether to erase the message (overwriting with garbage) or only mark it as erased.

Returns:

true if the delete succeeded

Throws:

java.io.IOException - covers various communication issues with the NATS server such as timeout or interruption

JetStreamApiException - the request had an error related to the data

jetStream

JetStream jetStream()

Gets a context for publishing and subscribing to subjects backed by Jetstream streams and consumers, using the same connection and JetStreamOptions as the management.

Returns:

a JetStream instance.