com.ibm.etcd.client.utils

Class RangeCache

java.lang.Object

com.ibm.etcd.client.utils.RangeCache

All Implemented Interfaces:

AutoCloseable, Iterable<KeyValue>

public class RangeCache
extends Object
implements AutoCloseable, Iterable<KeyValue>

Auto-updated write-through lock-free cache for etcd3, supporting atomic compare-and-set updates.

The cache must be started via the start() method before it will populate and update itself with key/values from the specified range.

Note that no range checking is done - the cache will not update itself with keys outside of the specified range, but it is possible to put, delete and getRemote keys outside of the range. This is not advised and may result in stale out-of-range key/values remaining in the cache.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	RangeCache.Listener Interface for listening to update events from the cache
static class	RangeCache.PutResult Stores result of put operations

Field Summary

Fields

Modifier and Type	Field and Description
protected Executor	listenerExecutor
protected List<RangeCache.Listener>	listeners
protected static org.slf4j.Logger	logger
static long	TIMEOUT_MS

Constructor Summary

Constructors

Constructor and Description
RangeCache(EtcdClient client, com.google.protobuf.ByteString prefix)
RangeCache(EtcdClient client, com.google.protobuf.ByteString prefix, boolean sorted)
RangeCache(EtcdClient client, com.google.protobuf.ByteString prefix, boolean sorted, Executor listenerExecutor)
RangeCache(EtcdClient client, com.google.protobuf.ByteString fromKey, com.google.protobuf.ByteString toKey, boolean sorted)
RangeCache(EtcdClient client, com.google.protobuf.ByteString fromKey, com.google.protobuf.ByteString toKey, boolean sorted, Executor listenerExecutor)
RangeCache(EtcdClient client, com.google.protobuf.ByteString prefix, Executor listenerExecutor)

Method Summary

Modifier and Type	Method and Description
void	addListener(RangeCache.Listener listener)
void	close()
boolean	delete(com.google.protobuf.ByteString key) Unconditional delete
boolean	delete(com.google.protobuf.ByteString key, long modRev) Conditional delete
void	forEach(Consumer<? super KeyValue> action)
protected com.google.common.util.concurrent.ListenableFuture<Boolean>	fullRefreshCache()
KeyValue	get(com.google.protobuf.ByteString key)
KeyValue	getFirst()
KeyValue	getRemote(com.google.protobuf.ByteString key)
protected KeyValue	getRemote(com.google.protobuf.ByteString key, boolean weak)
KeyValue	getRemoteWeak(com.google.protobuf.ByteString key)
boolean	isClosed()
protected static boolean	isDeleted(KeyValue kv)
Iterator<KeyValue>	iterator() Iterator.remove() not supported on returned iterators
boolean	keyExists(com.google.protobuf.ByteString key)
boolean	keyExistsRemote(com.google.protobuf.ByteString key)
Set<com.google.protobuf.ByteString>	keySet()
protected static KeyValue	kvOrNullIfDeleted(KeyValue fromCache)
protected static Compare.Builder	modRevCompare(com.google.protobuf.ByteString key, long modRev)
protected void	notifyListeners(RangeCache.Listener.EventType type, KeyValue keyValue, boolean inListenerExecutor)
protected KeyValue	offerDelete(com.google.protobuf.ByteString key, long modRevision) Assumed to not be called from watch/listener executor
protected KeyValue	offerExpiry(com.google.protobuf.ByteString key) Deprecated. this method now has no effect
protected KeyValue	offerUpdate(KeyValue keyValue, boolean watchThread)
long	put(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value) Unconditional put.
RangeCache.PutResult	put(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value, long modRev)
RangeCache.PutResult	put(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value, long lease, CompareOrBuilder... conditions) Multi-purpose put or delete, returns updated or existing KeyValue
RangeCache.PutResult	put(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value, long leaseId, long modRev)
long	putNoGet(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value, long modRev)
long	putNoGet(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value, long lease, CompareOrBuilder... conditions) Multi-purpose put or delete.
long	putNoGet(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value, long leaseId, long modRev)
protected TxnRequest	putTxn(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value, boolean getOnFail, long lease, CompareOrBuilder... conditions)
boolean	removeListener(RangeCache.Listener listener)
protected void	revisionUpdate(long upToRev)
int	size()
com.google.common.util.concurrent.ListenableFuture<Boolean>	start() Start the cache.
Iterator<KeyValue>	strongIterator() Iterator whose contents is guaranteed to be sequentially consistent with remote updates to the cached range.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

spliterator

Field Detail

logger

protected static final org.slf4j.Logger logger

TIMEOUT_MS

public static final long TIMEOUT_MS

See Also:

Constant Field Values

listeners

protected final List<RangeCache.Listener> listeners

listenerExecutor

protected final Executor listenerExecutor

Constructor Detail

RangeCache

public RangeCache(EtcdClient client,
                  com.google.protobuf.ByteString prefix)

RangeCache

public RangeCache(EtcdClient client,
                  com.google.protobuf.ByteString prefix,
                  Executor listenerExecutor)

RangeCache

public RangeCache(EtcdClient client,
                  com.google.protobuf.ByteString prefix,
                  boolean sorted)

RangeCache

public RangeCache(EtcdClient client,
                  com.google.protobuf.ByteString prefix,
                  boolean sorted,
                  Executor listenerExecutor)

RangeCache

public RangeCache(EtcdClient client,
                  com.google.protobuf.ByteString fromKey,
                  com.google.protobuf.ByteString toKey,
                  boolean sorted)

RangeCache

public RangeCache(EtcdClient client,
                  com.google.protobuf.ByteString fromKey,
                  com.google.protobuf.ByteString toKey,
                  boolean sorted,
                  Executor listenerExecutor)

Method Detail

start

public com.google.common.util.concurrent.ListenableFuture<Boolean> start()

Start the cache. This must be called before the cache will automatically populate and update its internal state.

Returns:

a future which completes when the cache is fully initialized - i.e. when its contents reflects the state of the range at or after the time this method was called

fullRefreshCache

protected com.google.common.util.concurrent.ListenableFuture<Boolean> fullRefreshCache()

revisionUpdate

protected void revisionUpdate(long upToRev)

addListener

public void addListener(RangeCache.Listener listener)

removeListener

public boolean removeListener(RangeCache.Listener listener)

notifyListeners

protected void notifyListeners(RangeCache.Listener.EventType type,
                               KeyValue keyValue,
                               boolean inListenerExecutor)

offerExpiry

protected KeyValue offerExpiry(com.google.protobuf.ByteString key)

Deprecated. this method now has no effect

offerDelete

protected KeyValue offerDelete(com.google.protobuf.ByteString key,
                               long modRevision)

Assumed to not be called from watch/listener executor

Returns:

latest value, may or may not be the provided one

offerUpdate

protected KeyValue offerUpdate(KeyValue keyValue,
                               boolean watchThread)

Parameters:

keyValue -

watchThread - if being called from background watch context

Returns:

the provided value, or a newer one

kvOrNullIfDeleted

protected static KeyValue kvOrNullIfDeleted(KeyValue fromCache)

isDeleted

protected static boolean isDeleted(KeyValue kv)

get

public KeyValue get(com.google.protobuf.ByteString key)

getFirst

public KeyValue getFirst()

Returns:

the first KeyValue or null if empty

getRemote

protected KeyValue getRemote(com.google.protobuf.ByteString key,
                             boolean weak)

getRemote

public KeyValue getRemote(com.google.protobuf.ByteString key)

getRemoteWeak

public KeyValue getRemoteWeak(com.google.protobuf.ByteString key)

size

public int size()

keyExists

public boolean keyExists(com.google.protobuf.ByteString key)

keyExistsRemote

public boolean keyExistsRemote(com.google.protobuf.ByteString key)

put

public long put(com.google.protobuf.ByteString key,
                com.google.protobuf.ByteString value)

Unconditional put. Can be used to unconditionally delete by passing a null value, but it's preferable to use delete(ByteString) for this.

Parameters:

key -

value - value to put

Returns:

modRevision of updated keyValue

put

public RangeCache.PutResult put(com.google.protobuf.ByteString key,
                                com.google.protobuf.ByteString value,
                                long lease,
                                CompareOrBuilder... conditions)

Multi-purpose put or delete, returns updated or existing KeyValue

Parameters:

key -

value - new value to put, or null to delete

lease - leaseId to associate value with if successful, or 0L for no lease

conditions - conditions which must all match to proceed, null or empty for unconditional

Returns:

PutResult

put

public RangeCache.PutResult put(com.google.protobuf.ByteString key,
                                com.google.protobuf.ByteString value,
                                long modRev)

Parameters:

key -

value - new value to put, or null to delete

modRev - last-modified revision to match, or 0 for put-if-absent

Returns:

PutResult

put

public RangeCache.PutResult put(com.google.protobuf.ByteString key,
                                com.google.protobuf.ByteString value,
                                long leaseId,
                                long modRev)

Parameters:

key -

value - new value to put, or null to delete

leaseId - leaseId to associate value with if successful, or 0L for no lease

modRev - last-modified revision to match, or 0 for put-if-absent

Returns:

PutResult

putNoGet

public long putNoGet(com.google.protobuf.ByteString key,
                     com.google.protobuf.ByteString value,
                     long lease,
                     CompareOrBuilder... conditions)

Multi-purpose put or delete. If successful returns modRevision of updated keyValue or 0 if deleted

Parameters:

key -

value - new value to put, or null to delete

lease - leaseId to associate value with if successful, or 0L for no lease

conditions - conditions which must all match to proceed, null or empty for unconditional

Returns:

-1 if condition failed, else modRevision of updated keyValue

putNoGet

public long putNoGet(com.google.protobuf.ByteString key,
                     com.google.protobuf.ByteString value,
                     long modRev)

Parameters:

key -

value - new value to put, or null to delete

modRev - last-modified revision to match, or 0 for put-if-absent

Returns:

-1 if condition failed, else modRevision of updated keyValue

putNoGet

public long putNoGet(com.google.protobuf.ByteString key,
                     com.google.protobuf.ByteString value,
                     long leaseId,
                     long modRev)

Parameters:

key -

value - new value to put, or null to delete

leaseId - leaseId to associate value with if successful, or 0L for no lease

modRev - last-modified rev to match, or 0 for put-if-absent

Returns:

-1 if condition failed, else modRevision of updated keyValue

modRevCompare

protected static Compare.Builder modRevCompare(com.google.protobuf.ByteString key,
                                               long modRev)

putTxn

protected TxnRequest putTxn(com.google.protobuf.ByteString key,
                            com.google.protobuf.ByteString value,
                            boolean getOnFail,
                            long lease,
                            CompareOrBuilder... conditions)

delete

public boolean delete(com.google.protobuf.ByteString key)

Unconditional delete

Parameters:

key -

Returns:

true if entry was deleted, false if already absent

delete

public boolean delete(com.google.protobuf.ByteString key,
                      long modRev)

Conditional delete

Parameters:

key -

modRev -

Returns:

true if entry was deleted, false if already absent

keySet

public Set<com.google.protobuf.ByteString> keySet()

iterator

public Iterator<KeyValue> iterator()

Iterator.remove() not supported on returned iterators

Specified by:

iterator in interface Iterable<KeyValue>

Returns:

an Iterator over the KeyValues of this cache

forEach

public void forEach(Consumer<? super KeyValue> action)

Specified by:

forEach in interface Iterable<KeyValue>

strongIterator

public Iterator<KeyValue> strongIterator()

Iterator whose contents is guaranteed to be sequentially consistent with remote updates to the cached range.

Returns:

an Iterator over the KeyValues of this cache

close

public void close()

Specified by:

close in interface AutoCloseable

isClosed

public boolean isClosed()