io.nats.client

Interface StreamContext

public interface StreamContext

The Stream Context provide a set of operations for managing the stream and its contents and for managing consumers.

For basic usage examples see JetStream

Method Summary

Modifier and Type	Method and Description
@NonNull OrderedConsumerContext	createOrderedConsumer(@NonNull OrderedConsumerConfiguration config) Create an ordered consumer context for the context's stream.
@NonNull ConsumerContext	createOrUpdateConsumer(@NonNull ConsumerConfiguration config) Management function to create or update a consumer on this stream.
boolean	deleteConsumer(@NonNull java.lang.String consumerName) Management function to deletes a consumer.
boolean	deleteMessage(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(long seq, boolean erase) Deletes a message, optionally erasing the content of the message.
@NonNull ConsumerContext	getConsumerContext(@NonNull java.lang.String consumerName) Get a consumer context for the context's stream and specific named consumer.
@NonNull ConsumerInfo	getConsumerInfo(@NonNull java.lang.String consumerName) Gets the info for an existing consumer.
@NonNull java.util.List<java.lang.String>	getConsumerNames() Return a list of consumers by name
@NonNull java.util.List<ConsumerInfo>	getConsumers() Return a list of ConsumerInfo objects.
@NonNull MessageInfo	getFirstMessage(@NonNull java.lang.String subject) Get MessageInfo for the first message of the subject.
@NonNull MessageInfo	getLastMessage(@NonNull java.lang.String subject) Get MessageInfo for the last message of the subject.
@NonNull MessageInfo	getMessage(long seq) Get MessageInfo for the message with the exact sequence in the stream.
@NonNull MessageInfo	getNextMessage(long seq, @NonNull java.lang.String subject) Get MessageInfo for the message of the message sequence is equal to or greater the requested sequence for the subject.
@NonNull StreamInfo	getStreamInfo() Gets information about the stream for this context.
@NonNull StreamInfo	getStreamInfo(@Nullable StreamInfoOptions options) Gets information about the stream for this context.
@NonNull java.lang.String	getStreamName() Gets the stream name that was used to create the context.
@NonNull PurgeResponse	purge() Purge stream messages
@NonNull PurgeResponse	purge(PurgeOptions options) Purge messages for a specific subject

Method Detail

getStreamName

@NonNull java.lang.String getStreamName()

Gets the stream name that was used to create the context.

Returns:

the stream name

getStreamInfo

@NonNull StreamInfo getStreamInfo()
                           throws java.io.IOException,
                                  JetStreamApiException

Gets information about the stream for this context. Does not retrieve any optional data. See the overloaded version that accepts StreamInfoOptions

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, most likely the stream has been removed since the context was created.

getStreamInfo

@NonNull StreamInfo getStreamInfo(@Nullable StreamInfoOptions options)
                           throws java.io.IOException,
                                  JetStreamApiException

Gets information about the stream for this context.

Parameters:

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, most likely the stream has been removed since the context was created.

purge

@NonNull PurgeResponse purge()
                      throws java.io.IOException,
                             JetStreamApiException

Purge stream messages

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

purge

@NonNull PurgeResponse purge(PurgeOptions options)
                      throws java.io.IOException,
                             JetStreamApiException

Purge messages for a specific subject

Parameters:

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

getConsumerContext

@NonNull ConsumerContext getConsumerContext(@NonNull java.lang.String consumerName)
                                     throws java.io.IOException,
                                            JetStreamApiException

Get a consumer context for the context's stream and specific named consumer. Verifies that the consumer exists.

Note that ConsumerContext expects a pull consumer.

Parameters:

consumerName - the name of the consumer

Returns:

a ConsumerContext object

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.

createOrUpdateConsumer

@NonNull ConsumerContext createOrUpdateConsumer(@NonNull ConsumerConfiguration config)
                                         throws java.io.IOException,
                                                JetStreamApiException

Management function to create or update a consumer on this stream.

Note that ConsumerContext expects a pull consumer.

Parameters:

config - the consumer configuration to use.

Returns:

a ConsumerContext object

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.

createOrderedConsumer

@NonNull OrderedConsumerContext createOrderedConsumer(@NonNull OrderedConsumerConfiguration config)
                                               throws java.io.IOException,
                                                      JetStreamApiException

Create an ordered consumer context for the context's stream.

Parameters:

config - the configuration for the ordered consumer

Returns:

an OrderedConsumerContext object

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

deleteConsumer

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

Management function to deletes a consumer.

Parameters:

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.

getConsumerInfo

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

Gets the info for an existing consumer.

Parameters:

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

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

Return a list of consumers by name

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

@NonNull java.util.List<ConsumerInfo> getConsumers()
                                            throws java.io.IOException,
                                                   JetStreamApiException

Return a list of ConsumerInfo objects.

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

getMessage

@NonNull MessageInfo getMessage(long seq)
                         throws java.io.IOException,
                                JetStreamApiException

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

Parameters:

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

getLastMessage

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

Get MessageInfo for the last message of the subject.

Parameters:

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

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

Get MessageInfo for the first message of the subject.

Parameters:

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

@NonNull MessageInfo getNextMessage(long seq,
                                    @NonNull 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:

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(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:

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(long seq,
                      boolean erase)
               throws java.io.IOException,
                      JetStreamApiException

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

Parameters:

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