com.distelli.persistence

Interface Index<T>

public interface Index<T>

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Index.Builder<T>
static interface	Index.Factory To provide suitable defaults for the endpoint/credProvider/proxy/keyProvider, it is recommended to implement a custom Factory implementation.

Method Summary

Modifier and Type	Method and Description
<N> Index.Builder<N>	clone(Class<N> clazz) Clone this index, use the builder methods to customize the clone.
int	countItems(PageIterator pageIterator) Count all items in the table.
default void	deleteItem(Object hk, Object rk) Shortcut method to always delete an item (no condition specified).
void	deleteItem(Object hk, Object rk, FilterCondFn filterCondFn) Delete an item from the table with the specified hash key and range key, optionally specify a filter condition that if evaluated to false causes a RollbackException to be thrown (and no item deleted).
void	deleteItems(IndexKey... keys) Batch delete all items with the specified hash key and range key in the IndexKey object.
default Object	getDynamoDBUnsafe() Obtain the underlying DynamoDB object for this table.
String	getHashKeyName()
default T	getItem(Object hk) Same as getItem(hk, null).
T	getItem(Object hk, Object rk) Obtain an item stored with the specified hash key and range key.
default <V> V	getItem(Object hk, Object rk, Class<V> type) Shortcut method to getItem() with all attributes.
<V> V	getItem(Object hk, Object rk, Collection<String> attributes, Class<V> type) Obtain an item stored with the specified hash key and range key, but convert to a different class type, and only select the specified attributes.
default T	getItemOrThrow(Object hk, Object rk) Obtain a specific item, but instead of returning null, throw EntityNotFoundException NOTE: This only works on "main" indexes.
Map<IndexKey,T>	getItems(IndexKey... keys) Do a batch get of items with the specified hash key and range keys.
default Object	getMySQLDataSourceUnsafe() Obtain the underlaying DataSource object for this table.
String	getRangeKeyName()
String	getTableName()
Set<IndexKey>	itemsExist(IndexKey... keys) Test if a set of DB keys exist, if so those IndexKeys are returned in the set.
T	putItem(T item) Overwrite or create a new item in the table.
default boolean	putItemIfNotExists(T item) Shortcut method to catch EntityExistsException and return true/false instead.
void	putItemOrThrow(T item) Create a new item in the table, but if an item already exists, throw EntityExistsException.
void	putItems(T... items) Batch put items, overwriting any items in the table that have the same hash key and range key.
QueryItemsBuilder<T>	queryItems(Object hk, PageIterator pageIterator)
List<T>	scanItems(PageIterator pageIterator) Iterate over all items in the table.
String	toMarker(T item, boolean hasHashKey) Call the configured ConvertMarker.toMarker() implementation.
UpdateItemBuilder<T>	updateItem(Object hk, Object rk) Update or create the item identified with the specified hash key and range key.

Method Detail

getHashKeyName

String getHashKeyName()

Returns:

the hash key name.

getRangeKeyName

String getRangeKeyName()

Returns:

the range key name.

getTableName

String getTableName()

Returns:

the fully qualified table name.

getDynamoDBUnsafe

default Object getDynamoDBUnsafe()

Obtain the underlying DynamoDB object for this table. This should only be used by code paths that are specific to DynamoDB. Note that this only works on MAIN indexes.

Returns:

an instance of com.amazonaws.services.dynamodbv2.document.DynamoDB or null if the underlying data store is NOT backed by dynamo.

getMySQLDataSourceUnsafe

default Object getMySQLDataSourceUnsafe()

Obtain the underlaying DataSource object for this table. T

Returns:

an instance of javax.sql.DataSource or null if the underlying data store is NOT backed by a MySql DB.

toMarker

String toMarker(T item,
                boolean hasHashKey)

Call the configured ConvertMarker.toMarker() implementation.

Parameters:

item - is an item for which we desire to obtain a marker for.

hasHashKey - should be set to true only if we are guaranteed to call fromMarker() with a non-null hash key parameter.

Returns:

a marker

clone

<N> Index.Builder<N> clone(Class<N> clazz)

Clone this index, use the builder methods to customize the clone. Useful if you want to obtain a different index of the same table (for example).

Type Parameters:

N - is the type of elements we plan to store/retrieve.

Parameters:

clazz - is the type of elements we plan to store/retrieve from the Index created by the returned builder.

Returns:

a new Index.Builder configured based on the parameters of this Index.

queryItems

QueryItemsBuilder<T> queryItems(Object hk,
                                PageIterator pageIterator)

Parameters:

hk - is the hash key to query on.

pageIterator - is the page iterator to use for iterating over multiple result sets.

Returns:

a query item builder used to formulate the desired query.

scanItems

List<T> scanItems(PageIterator pageIterator)

Iterate over all items in the table.

Parameters:

pageIterator - is the page iterator to use.

Returns:

the next list of results. This list is unmodifiable.

countItems

int countItems(PageIterator pageIterator)

Count all items in the table.

Parameters:

pageIterator - is the page iterator to use.

Returns:

the count of items in the first page of results.

getItem

T getItem(Object hk,
          Object rk)

Obtain an item stored with the specified hash key and range key. NOTE: This only works on "main" indexes.

Parameters:

hk - is the hash key.

rk - is the range key, or null if this table does not have a range key name.

Returns:

the item with this primary key or null.

getItem

default T getItem(Object hk)

Same as getItem(hk, null). NOTE: This only works on "main" indexes.

Parameters:

hk - is the hash key.

Returns:

the item with this primary key or null.

getItem

<V> V getItem(Object hk,
              Object rk,
              Collection<String> attributes,
              Class<V> type)

Obtain an item stored with the specified hash key and range key, but convert to a different class type, and only select the specified attributes. NOTE: This only works on "main" indexes.

Type Parameters:

V - is the alternative item type to retrieve.

Parameters:

hk - is the hash key.

rk - is the range key (or null if this table has no range key).

attributes - is the set of attribute names to obtain.

type - is the class of the alternative item type to retrieve.

Returns:

the item with this primary key or null.

getItem

default <V> V getItem(Object hk,
                      Object rk,
                      Class<V> type)

Shortcut method to getItem() with all attributes. NOTE: This only works on "main" indexes.

Type Parameters:

V - is the alternative item type to retrieve.

Parameters:

hk - is the hash key.

rk - is the range key.

type - is the class of the alternative item type to retrieve.

Returns:

the item with this primary key or null.

getItemOrThrow

default T getItemOrThrow(Object hk,
                         Object rk)
                  throws javax.persistence.EntityNotFoundException

Obtain a specific item, but instead of returning null, throw EntityNotFoundException NOTE: This only works on "main" indexes.

Parameters:

hk - is the hash key.

rk - is the range key.

Returns:

the item with this primary key, never returns null.

Throws:

javax.persistence.EntityNotFoundException - if no such item exists.

getItems

Map<IndexKey,T> getItems(IndexKey... keys)

Do a batch get of items with the specified hash key and range keys. If an item does not exist, there will not be an entry in the map for the IndexKey. NOTE: This only works on "main" indexes.

Parameters:

keys - is an array of index keys to obtain in a single batch call.

Returns:

a map of IndexKey to the item, if an item does not exist the key will map to null. The returned map is unmodifiable.

itemsExist

Set<IndexKey> itemsExist(IndexKey... keys)

Test if a set of DB keys exist, if so those IndexKeys are returned in the set. This is a little more efficient then calling getItems(). NOTE: This only works on "main" indexes.

Parameters:

keys - is an array of index keys to check for existance of.

Returns:

a set of index keys that do exist. Any key missing from this set does not exist. The returned set is unmodifiable.

putItem

T putItem(T item)

Overwrite or create a new item in the table. NOTE: This only works on "main" indexes.

Parameters:

item - is the item to put.

Returns:

the previous item (or null)

putItemOrThrow

void putItemOrThrow(T item)
             throws javax.persistence.EntityExistsException

Create a new item in the table, but if an item already exists, throw EntityExistsException. NOTE: This only works on "main" indexes.

Parameters:

item - is the item to put.

Throws:

javax.persistence.EntityExistsException - if the primary key of item already exists in this table.

putItemIfNotExists

default boolean putItemIfNotExists(T item)

Shortcut method to catch EntityExistsException and return true/false instead. NOTE: This only works on "main" indexes.

Parameters:

item - is the item to put.

Returns:

false if the primary key of this item already exists in which case the item was not actually saved to the table.

putItems

void putItems(T... items)

Batch put items, overwriting any items in the table that have the same hash key and range key. NOTE: This only works on "main" indexes.

Parameters:

items - are the items to put in the table.

updateItem

UpdateItemBuilder<T> updateItem(Object hk,
                                Object rk)

Update or create the item identified with the specified hash key and range key. NOTE: This only works on "main" indexes.

Parameters:

hk - is the hash key.

rk - is the range key, or null if this table has no range key name.

Returns:

an update item builder used to describe what update should take place.

deleteItem

void deleteItem(Object hk,
                Object rk,
                FilterCondFn filterCondFn)
         throws javax.persistence.RollbackException

Delete an item from the table with the specified hash key and range key, optionally specify a filter condition that if evaluated to false causes a RollbackException to be thrown (and no item deleted). NOTE: This only works on "main" indexes.

Parameters:

hk - is the hash key.

rk - is the range key, or null if this table has no range key name.

filterCondFn - is used to describe under what condition this item may be deleted.

Throws:

javax.persistence.RollbackException - if the filterCondFn condition was not met.

deleteItem

default void deleteItem(Object hk,
                        Object rk)

Shortcut method to always delete an item (no condition specified). NOTE: This only works on "main" indexes.

Parameters:

hk - is the hash key.

rk - is the range key, or null if this table has no range key name.

deleteItems

void deleteItems(IndexKey... keys)

Batch delete all items with the specified hash key and range key in the IndexKey object. NOTE: This only works on "main" indexes.

Parameters:

keys - is an array of index keys that should be unconditionally deleted if they exist.