org.bluedb.api

Interface BlueCollection<V extends java.io.Serializable>

Type Parameters:

V - the object type of values to be serialized into the collection

All Known Implementing Classes:

BlueCollectionOnDisk

public interface BlueCollection<V extends java.io.Serializable>

A BlueCollection represents a persisted map of keys (of type BlueKey) to values of object type V. A collection has a name (to distinguish between collections in a BlueDb instance), a key type, and a value type.

Method Summary

Modifier and Type	Method and Description
void	batchDelete(java.util.Collection<BlueKey> keys) Deletes the values for the given keys.
void	batchUpsert(java.util.Map<BlueKey,V> values) Inserts or replaces the given key value pairs.
boolean	contains(BlueKey key) Returns true if the collection contains a value for the given key.
<K extends ValueKey> BlueIndex<K,V>	createIndex(java.lang.String name, java.lang.Class<K> keyType, KeyExtractor<K,V> keyExtractor) Creates (or returns existing) BlueIndex that maps objects of type ValueKey (UUIDKey, StringKey, IntegerKey, LongKey) to values in the collection.
void	delete(BlueKey key) Deletes the value for the given key
V	get(BlueKey key) Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key
<K extends ValueKey> BlueIndex<K,V>	getIndex(java.lang.String name, java.lang.Class<K> keyType) Returns existing BlueIndex that maps objects of type keyType to values in the collection.
BlueKey	getLastKey() Returns the key with the highest grouping number that exists in this collection
void	insert(BlueKey key, V value) Inserts the given key value pair
BlueQuery<V>	query() Creates a BlueQuery object which can be used to build and execute a query against this collection.
void	replace(BlueKey key, Mapper<V> updater) Replaces the value for the given key by passing it to the given updater
void	update(BlueKey key, Updater<V> updater) Mutates the value for the given key by passing it to the given updater

Method Detail

createIndex

<K extends ValueKey> BlueIndex<K,V> createIndex(java.lang.String name,
                                                java.lang.Class<K> keyType,
                                                KeyExtractor<K,V> keyExtractor)
                                         throws BlueDbException

Creates (or returns existing) BlueIndex that maps objects of type ValueKey (UUIDKey, StringKey, IntegerKey, LongKey) to values in the collection.

Type Parameters:

K - the key type of the index or the type of data that the collection is being indexed on. It must be a concretion of ValueKey (UUIDKey, StringKey, LongKey, or IntegerKey).

Parameters:

name - index name (one index per name per each collection)

keyType - the type of each key which is used to lookup a value using the index (this must match the keyType of any existing index with the same name)

keyExtractor - a function that maps a value to the keys by which the value should be indexed. The appropriate subclass can be used and would be more simple to implement. These include UUIDIndexKeyExtractor, StringIndexKeyExtractor, IntegerIndexKeyExtractor, and LongIndexKeyExtractor

Returns:

a BlueIndex object (existing index if it exists, otherwise a newly created index)

Throws:

BlueDbException - if the index exists but is not compatible with these types

getIndex

<K extends ValueKey> BlueIndex<K,V> getIndex(java.lang.String name,
                                             java.lang.Class<K> keyType)
                                      throws BlueDbException

Returns existing BlueIndex that maps objects of type keyType to values in the collection.

Type Parameters:

K - the key type of the index or the type of data that the collection is being indexed on. It must be a concretion of ValueKey (UUIDKey, StringKey, LongKey, or IntegerKey).

Parameters:

name - index name (one index per name per each collection)

keyType - the type of each key which is used to lookup a value using the index (this must match the keyType of any existing index with the same name)

Returns:

a BlueIndex with the same name if it exists and has the same keyType

Throws:

BlueDbException - if index doesn't exist or has a different keyType

contains

boolean contains(BlueKey key)
          throws BlueDbException

Returns true if the collection contains a value for the given key.

Parameters:

key - the key that may or may not be in collection

Returns:

true if the collection contains a value for the given key, else false

Throws:

BlueDbException - if the type of key was not the type specified when the collection was created

insert

void insert(BlueKey key,
            V value)
     throws BlueDbException

Inserts the given key value pair

Parameters:

key - key where value should be saved (must match the keyType specified when the collection was created)

value - value to be saved for the key

Throws:

BlueDbException - if the key type is not the type specified when the collection was created

batchUpsert

void batchUpsert(java.util.Map<BlueKey,V> values)
          throws BlueDbException

Inserts or replaces the given key value pairs. Batch methods are much more efficient than calling non-batch methods many times.

Parameters:

values - the key value pairs to insert. Key types must match the keyType specified when the collection was created.

Throws:

BlueDbException - if the key types do not match the type specified when the collection was created

get

V get(BlueKey key)
throws BlueDbException

Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key

Parameters:

key - the key for the desired value

Returns:

the value to which the specified key is mapped, or null if this map contains no mapping for the key

Throws:

BlueDbException - if the key is not the same type specified when the collection was created

update

void update(BlueKey key,
            Updater<V> updater)
     throws BlueDbException

Mutates the value for the given key by passing it to the given updater

Parameters:

key - The key for the value which will be updated

updater - a function that mutates the value to which the specified key is mapped

Throws:

BlueDbException - if type of key is not the type specified when the collection was created or if updater throws an exception

replace

void replace(BlueKey key,
             Mapper<V> updater)
      throws BlueDbException

Replaces the value for the given key by passing it to the given updater

Parameters:

key - the key for the value which will be replaced

updater - a function that returns the value that should replace the value to which the specified key is mapped

Throws:

BlueDbException - if type of key is not the type specified when the collection was created or if updater throws an exception

delete

void delete(BlueKey key)
     throws BlueDbException

Deletes the value for the given key

Parameters:

key - the key for the value which will be deleted

Throws:

BlueDbException - if type of key is not the type specified when the collection was created

batchDelete

void batchDelete(java.util.Collection<BlueKey> keys)
          throws BlueDbException

Deletes the values for the given keys. Batch methods are much more efficient than calling non-batch methods many times.

Parameters:

keys - the keys for the values which will be deleted

Throws:

BlueDbException - if type of key is not the type specified when the collection was created

query

BlueQuery<V> query()

Creates a BlueQuery object which can be used to build and execute a query against this collection.

Returns:

a BlueQuery object which can be used to build and execute a query against this collection.

getLastKey

BlueKey getLastKey()

Returns the key with the highest grouping number that exists in this collection

Returns:

the key with the highest grouping number that exists in this collection