io.nats.client

Interface KeyValue

public interface KeyValue

Key Value Store Management context for creation and access to key value buckets.

Method Summary

Modifier and Type	Method and Description
long	create(java.lang.String key, byte[] value) Put as the value for a key iff the key does not exist (there is no history) or is deleted (history shows the key is deleted)
void	delete(java.lang.String key) Soft deletes the key by placing a delete marker.
KeyValueEntry	get(java.lang.String key) Get the entry for a key when the key exists and is live (not deleted and not purged)
KeyValueEntry	get(java.lang.String key, long revision) Get the specific revision of an entry for a key when the key exists and is live (not deleted and not purged)
java.lang.String	getBucketName() Get the name of the bucket.
KeyValueStatus	getStatus() Get the KeyValueStatus object
java.util.List<KeyValueEntry>	history(java.lang.String key) Get the history (list of KeyValueEntry) for a key
java.util.List<java.lang.String>	keys() Get a list of the keys in a bucket.
void	purge(java.lang.String key) Purge all values/history from the specific key
void	purgeDeletes() Remove history from all keys that currently are deleted or purged with using a default KeyValuePurgeOptions
void	purgeDeletes(KeyValuePurgeOptions options) Remove history from all keys that currently are deleted or purged, considering options.
long	put(java.lang.String key, byte[] value) Put a byte[] as the value for a key
long	put(java.lang.String key, java.lang.Number value) Put a long as the value for a key
long	put(java.lang.String key, java.lang.String value) Put a string as the value for a key
long	update(java.lang.String key, byte[] value, long expectedRevision) Put as the value for a key iff the key exists and its last revision matches the expected
long	update(java.lang.String key, java.lang.String value, long expectedRevision) Put a string as the value for a key iff the key exists and its last revision matches the expected
io.nats.client.impl.NatsKeyValueWatchSubscription	watch(java.lang.String key, KeyValueWatcher watcher, KeyValueWatchOption... watchOptions) Watch updates for a specific key.
io.nats.client.impl.NatsKeyValueWatchSubscription	watchAll(KeyValueWatcher watcher, KeyValueWatchOption... watchOptions) Watch updates for all keys.

Method Detail

getBucketName

java.lang.String getBucketName()

Get the name of the bucket.

Returns:

the name

get

KeyValueEntry get(java.lang.String key)
           throws java.io.IOException,
                  JetStreamApiException

Get the entry for a key when the key exists and is live (not deleted and not purged)

Parameters:

key - the key

Returns:

the KvEntry object or null if not found.

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

get

KeyValueEntry get(java.lang.String key,
                  long revision)
           throws java.io.IOException,
                  JetStreamApiException

Get the specific revision of an entry for a key when the key exists and is live (not deleted and not purged)

Parameters:

key - the key

revision - the revision

Returns:

the KvEntry object or null if not found.

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

put

long put(java.lang.String key,
         byte[] value)
  throws java.io.IOException,
         JetStreamApiException

Put a byte[] as the value for a key

Parameters:

key - the key

value - the bytes of the value

Returns:

the revision number for the key

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

put

long put(java.lang.String key,
         java.lang.String value)
  throws java.io.IOException,
         JetStreamApiException

Put a string as the value for a key

Parameters:

key - the key

value - the UTF-8 string

Returns:

the revision number for the key

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

put

long put(java.lang.String key,
         java.lang.Number value)
  throws java.io.IOException,
         JetStreamApiException

Put a long as the value for a key

Parameters:

key - the key

value - the number

Returns:

the revision number for the key

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

create

long create(java.lang.String key,
            byte[] value)
     throws java.io.IOException,
            JetStreamApiException

Put as the value for a key iff the key does not exist (there is no history) or is deleted (history shows the key is deleted)

Parameters:

key - the key

value - the bytes of the value

Returns:

the revision number for the key

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

update

long update(java.lang.String key,
            byte[] value,
            long expectedRevision)
     throws java.io.IOException,
            JetStreamApiException

Put as the value for a key iff the key exists and its last revision matches the expected

Parameters:

key - the key

value - the bytes of the value

expectedRevision - the expected last revision

Returns:

the revision number for the key

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

update

long update(java.lang.String key,
            java.lang.String value,
            long expectedRevision)
     throws java.io.IOException,
            JetStreamApiException

Put a string as the value for a key iff the key exists and its last revision matches the expected

Parameters:

key - the key

value - the UTF-8 string

expectedRevision - the expected last revision

Returns:

the revision number for the key

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

delete

void delete(java.lang.String key)
     throws java.io.IOException,
            JetStreamApiException

Soft deletes the key by placing a delete marker.

Parameters:

key - the key

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

void purge(java.lang.String key)
    throws java.io.IOException,
           JetStreamApiException

Purge all values/history from the specific key

Parameters:

key - the key

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

watch

io.nats.client.impl.NatsKeyValueWatchSubscription watch(java.lang.String key,
                                                        KeyValueWatcher watcher,
                                                        KeyValueWatchOption... watchOptions)
                                                 throws java.io.IOException,
                                                        JetStreamApiException,
                                                        java.lang.InterruptedException

Watch updates for a specific key.

Parameters:

key - the key

watcher - the watcher the implementation to receive changes

watchOptions - the watch options to apply. If multiple conflicting options are supplied, the last options wins.

Returns:

The KeyValueWatchSubscription

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.InterruptedException - if the thread is interrupted

watchAll

io.nats.client.impl.NatsKeyValueWatchSubscription watchAll(KeyValueWatcher watcher,
                                                           KeyValueWatchOption... watchOptions)
                                                    throws java.io.IOException,
                                                           JetStreamApiException,
                                                           java.lang.InterruptedException

Watch updates for all keys.

Parameters:

watcher - the watcher the implementation to receive changes

watchOptions - the watch options to apply. If multiple conflicting options are supplied, the last options wins.

Returns:

The KeyValueWatchSubscription

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.InterruptedException - if the thread is interrupted

keys

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

Get a list of the keys in a bucket.

Returns:

List of keys

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.InterruptedException - if the thread is interrupted

history

java.util.List<KeyValueEntry> history(java.lang.String key)
                               throws java.io.IOException,
                                      JetStreamApiException,
                                      java.lang.InterruptedException

Get the history (list of KeyValueEntry) for a key

Parameters:

key - the key

Returns:

List of KvEntry

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.InterruptedException - if the thread is interrupted

purgeDeletes

void purgeDeletes()
           throws java.io.IOException,
                  JetStreamApiException,
                  java.lang.InterruptedException

Remove history from all keys that currently are deleted or purged with using a default KeyValuePurgeOptions

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.InterruptedException - if the thread is interrupted

purgeDeletes

void purgeDeletes(KeyValuePurgeOptions options)
           throws java.io.IOException,
                  JetStreamApiException,
                  java.lang.InterruptedException

Remove history from all keys that currently are deleted or purged, considering options.

Parameters:

options - the purge options

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.InterruptedException - if the thread is interrupted

getStatus

KeyValueStatus getStatus()
                  throws java.io.IOException,
                         JetStreamApiException,
                         java.lang.InterruptedException

Get the KeyValueStatus object

Returns:

the status 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

java.lang.InterruptedException - if the thread is interrupted