org.sdnplatform.sync
Interface IStoreClient<K,V>

Type Parameters:

K - The type of the key being stored

V - The type of the value being stored

All Known Implementing Classes:

AbstractStoreClient, DefaultStoreClient

public interface IStoreClient<K,V>

The user-facing interface to a sync store. Gives basic put/get/delete plus helper functions.

Method Summary

void	addStoreListener(IStoreListener<K> listener) Add a listener that will be notified about changes to the given store.
void	delete(K key) Delete the key by writing a null tombstone to the store obliterating any existing value stored for the key.
void	delete(K key, IVersion version) Delete the key by writing a null tombstone to the store using the provided IVersion.
IClosableIterator<java.util.Map.Entry<K,Versioned<V>>>	entries() Get an iterator that will get all the entries in the store.
Versioned<V>	get(K key) Get the versioned value associated with the given key.
Versioned<V>	get(K key, Versioned<V> defaultValue) Get the versioned value associated with the given key or the defaultValue if no value is associated with the key.
V	getValue(K key) Get the value associated with the given key or null if there is no value associated with this key.
V	getValue(K key, V defaultValue) Get the value associated with the given key or defaultValue if there is no value associated with the key.
IVersion	put(K key, V value) Associated the given value to the key, clobbering any existing values stored for the key.
IVersion	put(K key, Versioned<V> versioned) Put the given Versioned value into the store for the given key if the version is greater to or concurrent with existing values.
boolean	putIfNotObsolete(K key, Versioned<V> versioned) Put the versioned value to the key, ignoring any ObsoleteVersionException that may be thrown

Method Detail

getValue

V getValue(K key)
           throws SyncException

Get the value associated with the given key or null if there is no value associated with this key. This method strips off all version information and is only useful when no further storage operations will be done on this key. In general, you should prefer the get() method that returns version information unless.

Parameters:

key - The key

Throws:

SyncException

getValue

V getValue(K key,
           V defaultValue)
           throws SyncException

Get the value associated with the given key or defaultValue if there is no value associated with the key. This method strips off all version information and is only useful when no further storage operations will be done on this key.In general, you should prefer the get() method that returns version information unless.

Parameters:

key - The key for which to fetch the associated value

defaultValue - A value to return if there is no value associated with this key

Returns:

Either the value stored for the key or the default value.

Throws:

SyncException

get

Versioned<V> get(K key)
                 throws SyncException

Get the versioned value associated with the given key. Note that while this function will never return null, the Versioned returned can have a null value (i.e. can be null if the key is not present.

Parameters:

key - The key for which to fetch the value.

Returns:

The versioned value

Throws:

SyncException

get

Versioned<V> get(K key,
                 Versioned<V> defaultValue)
                 throws SyncException

Get the versioned value associated with the given key or the defaultValue if no value is associated with the key.

Parameters:

key - The key for which to fetch the value.

Returns:

The versioned value, or the defaultValue if no value is stored for this key.

Throws:

SyncException

entries

IClosableIterator<java.util.Map.Entry<K,Versioned<V>>> entries()
                                                               throws SyncException

Get an iterator that will get all the entries in the store. Note that this has the potential to miss any values added while you're iterating through the collection, and it's possible that items will be deleted before you get to the end. Note that you *must* close the IClosableIterator when you are finished with it or there may be resource leaks. An example of how you should use this iterator to ensure that it is closed even if there are exceptions follows: IClosableIterator iter = store.entries(); try { // do your iteration } finally { iter.close(); } Another important caveat is that because IClosableIterator extends Iterator, there is no checked exception declared in Iterator.next(). Because of this, calling Iterator.next() on the iterator returned here may throw a SyncRuntimeException wrapping a SyncException such as might be returned by get(Object)

Returns:

Throws:

SyncException

put

IVersion put(K key,
             V value)
             throws SyncException

Associated the given value to the key, clobbering any existing values stored for the key. Only use this variant if the write cannot possibly depend on the current value in the store and if there cannot be a concurrent update from multiple threads. Otherwise put(Object, Versioned) or putIfNotObsolete(Object, Versioned)

Parameters:

key - The key

value - The value

Returns:

version The version of the object

Throws:

ObsoleteVersionException

SyncException

put

IVersion put(K key,
             Versioned<V> versioned)
             throws SyncException

Put the given Versioned value into the store for the given key if the version is greater to or concurrent with existing values. Throw an ObsoleteVersionException otherwise.

Parameters:

key - The key

versioned - The value and its versioned

Throws:

ObsoleteVersionException

SyncException

ObsoleteVersionException - if the entry assoicated with the key was locally modified by another thread after the get.

putIfNotObsolete

boolean putIfNotObsolete(K key,
                         Versioned<V> versioned)
                         throws SyncException

Put the versioned value to the key, ignoring any ObsoleteVersionException that may be thrown

Parameters:

key - The key

versioned - The versioned value

Returns:

true if the put succeeded

Throws:

SyncException

delete

void delete(K key)
            throws SyncException

Delete the key by writing a null tombstone to the store obliterating any existing value stored for the key. Only use this variant if the delete cannot possibly depend on the current value in the store and if there cannot be a concurrent update from multiple threads. Otherwise delete(Object, IVersion) should be used.

Parameters:

key - The key

Throws:

SyncException

delete

void delete(K key,
            IVersion version)
            throws SyncException

Delete the key by writing a null tombstone to the store using the provided IVersion.

Parameters:

key - The key to delete

version - The version of the key

Throws:

SyncException

ObsoleteVersionException - if the entry assoicated with the key was locally modified by another thread after the get.

addStoreListener

void addStoreListener(IStoreListener<K> listener)

Add a listener that will be notified about changes to the given store.

Parameters:

listener - the IStoreListener that will receive the notifications