/*
* Copyright 2008-2009 LinkedIn, Inc
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package org.sdnplatform.sync;
import java.util.Iterator;
import java.util.Map.Entry;
import org.sdnplatform.sync.error.ObsoleteVersionException;
import org.sdnplatform.sync.error.SyncException;
/**
* The user-facing interface to a sync store. Gives basic put/get/delete
* plus helper functions.
*
* @param <K> The type of the key being stored
* @param <V> The type of the value being stored
*/
public interface IStoreClient<K, V> {
/**
* 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.
*
* @param key The key
* @throws SyncException
*/
public V getValue(K key) 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.
*
* @param key The key for which to fetch the associated value
* @param defaultValue A value to return if there is no value associated
* with this key
* @return Either the value stored for the key or the default value.
* @throws SyncException
*/
public V getValue(K key, V defaultValue) throws SyncException;
/**
* Get the versioned value associated with the given key. Note that while
* this function will never return null, the {@link Versioned} returned
* can have a null value (i.e. {@link Versioned#getValue() can be null}
* if the key is not present.
*
* @param key The key for which to fetch the value.
* @return The versioned value
* @throws SyncException
*/
public Versioned<V> get(K key) throws SyncException;
/**
* Get the versioned value associated with the given key or the defaultValue
* if no value is associated with the key.
*
* @param key The key for which to fetch the value.
* @return The versioned value, or the defaultValue if no value is stored
* for this key.
* @throws SyncException
*/
public Versioned<V> get(K key, Versioned<V> defaultValue)
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 {@link 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:
* <code>
* IClosableIterator iter = store.entries();
* try {
* // do your iteration
* } finally {
* iter.close();
* }
* </code>
*
* Another important caveat is that because {@link IClosableIterator}
* extends {@link Iterator}, there is no checked exception declared in
* {@link Iterator#next()}. Because of this, calling
* {@link Iterator#next()} on the iterator returned here may throw a
* SyncRuntimeException wrapping a SyncException such as might be
* returned by {@link IStoreClient#get(Object)}
* @return
* @throws SyncException
*/
public IClosableIterator<Entry<K, Versioned<V>>> entries()
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 {@link #put(Object, Versioned)}
* or {@link #putIfNotObsolete(Object, Versioned)}
*
* @param key The key
* @param value The value
* @return version The version of the object
* @throws ObsoleteVersionException
* @throws SyncException
*/
public IVersion put(K key, V value) 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.
*
* @param key The key
* @param versioned The value and its versioned
* @throws ObsoleteVersionException
* @throws SyncException
* @throws ObsoleteVersionException if the entry assoicated with the key
* was locally modified by another thread after the get.
*/
public IVersion put(K key, Versioned<V> versioned)
throws SyncException;
/**
* Put the versioned value to the key, ignoring any ObsoleteVersionException
* that may be thrown
*
* @param key The key
* @param versioned The versioned value
* @return true if the put succeeded
* @throws SyncException
*/
public boolean putIfNotObsolete(K key, Versioned<V> versioned)
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 {@link #delete(Object, IVersion)}
* should be used.
*
* @param key The key
* @throws SyncException
*/
public void delete(K key) throws SyncException;
/**
* Delete the key by writing a null tombstone to the store using the
* provided {@link IVersion}.
*
* @param key The key to delete
* @param version The version of the key
* @throws SyncException
* @throws ObsoleteVersionException if the entry assoicated with the key
* was locally modified by another thread after the get.
*/
public void delete(K key, IVersion version) throws SyncException;
/**
* Add a listener that will be notified about changes to the given store.
* @param listener the {@link IStoreListener} that will receive the
* notifications
*/
public void addStoreListener(IStoreListener<K> listener);
}