com.aquenos.cassandra.pvarchiver.server.database

Interface GenericDataStoreDAO

All Known Implementing Classes:

GenericDataStoreDAOImpl

public interface GenericDataStoreDAO

Data access object that can be used by other component to store arbitrary (small amounts of) data.

Once initialized, this DAO publishes a GenericDataStoreDAOInitializedEvent in the application context, which can be used by other beans that need to use this DAO.

Author:

Sebastian Marsching

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	GenericDataStoreDAO.DataItem Value object representing a single data item.

Method Summary

Modifier and Type	Method and Description
ListenableFuture<Pair<Boolean,String>>	createItem(UUID componentId, String key, String value) Create a data item for the specified component and key if no such item exists yet.
ListenableFuture<Void>	createOrUpdateItem(UUID componentId, String key, String value) Creates a data item or updates it if an item with the specified key already exists for the specified component.
ListenableFuture<Void>	deleteAllItems(UUID componentId) Removes all data items for the specified component.
ListenableFuture<Void>	deleteItem(UUID componentId, String key) Removes the item with the specified key from collection of data items for the specified component.
ListenableFuture<? extends Iterable<? extends GenericDataStoreDAO.DataItem>>	getAllItems(UUID componentId) Returns all data items for the specified component.
ListenableFuture<? extends GenericDataStoreDAO.DataItem>	getItem(UUID componentId, String key) Returns the data item with the specified key for the specified component.
boolean	isInitialized() Tells whether this DAO has finished initialization and is ready to be used.
ListenableFuture<Pair<Boolean,String>>	updateItem(UUID componentId, String key, String oldValue, String newValue) Updates the data item with the specified key and component.

Method Detail

createItem

ListenableFuture<Pair<Boolean,String>> createItem(UUID componentId,
                                                  String key,
                                                  String value)

Create a data item for the specified component and key if no such item exists yet. Typically, this is less efficient than createOrUpdateItem(UUID, String, String), so code should prefer the latter method unless it has to ensure that it does not overwrite an existing value. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

componentId - ID of the component for which the data item should be created.

key - key identifying the data item within the component.

value - value of the data item.

Returns:

pair of a boolean flag and a string exposed through a future. The boolean flag indicates whether the item was created. If true, the item was created, if false, an item with the specified key already existed for the specified component. In this case, the string is the value of the existing item. In case of failure, the future's get() method will throw an exception.

createOrUpdateItem

ListenableFuture<Void> createOrUpdateItem(UUID componentId,
                                          String key,
                                          String value)

Creates a data item or updates it if an item with the specified key already exists for the specified component. This is the most efficient way to create or update a data item and should be preferred over createItem(UUID, String, String) and updateItem(UUID, String, String, String). The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

componentId - ID of the component for which the data item should be created or updated.

key - key identifying the data item within the component.

value - value of the data item.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

deleteAllItems

ListenableFuture<Void> deleteAllItems(UUID componentId)

Removes all data items for the specified component. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

componentId - ID of the component for which all data items should be removed.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

deleteItem

ListenableFuture<Void> deleteItem(UUID componentId,
                                  String key)

Removes the item with the specified key from collection of data items for the specified component. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

componentId - ID of the component that owns the data item.

key - key identifying the data item within the component.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

getAllItems

ListenableFuture<? extends Iterable<? extends GenericDataStoreDAO.DataItem>> getAllItems(UUID componentId)

Returns all data items for the specified component. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Parameters:

componentId - ID of the component for which all data items should be retrieved.

Returns:

all data items for the specified component exposed through a future. In case of failure, the future's get() method will throw an exception.

getItem

ListenableFuture<? extends GenericDataStoreDAO.DataItem> getItem(UUID componentId,
                                                                 String key)

Returns the data item with the specified key for the specified component. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

componentId - ID of the component that owns the data item.

key - key identifying the data item within the component.

Returns:

data item with the specified key for the specified component exposed through a future. If no such data item exists, the future's get method returns null. In case of failure, the future's get() method will throw an exception.

isInitialized

boolean isInitialized()

Tells whether this DAO has finished initialization and is ready to be used. Even if this method returns true, operations might still fail because of transient problems.

Returns:

true if this DAO has been initialized and is ready to be used, false if initialization has not completed yet.

updateItem

ListenableFuture<Pair<Boolean,String>> updateItem(UUID componentId,
                                                  String key,
                                                  String oldValue,
                                                  String newValue)

Updates the data item with the specified key and component. The item is only updated if its current value matches the specified oldValue. This type of atomic operation incurs an additional overhead. Code that does not mind overwriting a different value should prefer the createOrUpdateItem(UUID, String, String) method. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

componentId - ID of the component that owns the data item.

key - key identifying the data item within the component.

oldValue - old value of the data item that must be matched for the update operation to proceed.

newValue - new value that the data item shall be updated with if the old value matches.

Returns:

pair of a boolean flag and a string exposed through a future. The boolean flag indicates whether the item was updated. If true, the item was updated, if false, the item's value did not match the specified oldValue or the item did not exist. If the flag is false, the string is the current value of the existing item or null if no item with the specified component ID and key exists. In case of failure, the future's get() method will throw an exception.