org.apache.gora.store
Interface DataStore<K,T extends Persistent>

Type Parameters:

K - the class of keys in the datastore

T - the class of persistent objects in the datastore

All Known Subinterfaces:

FileBackedDataStore<K,T>, WebServiceBackedDataStore<K,T>

All Known Implementing Classes:

AccumuloStore, AvroStore, CassandraStore, DataFileAvroStore, DataStoreBase, DynamoDBStore, FileBackedDataStoreBase, HBaseStore, MemStore, SqlStore, WSBackedDataStoreBase, WSDataStoreBase

public interface DataStore<K,T extends Persistent>

DataStore handles actual object persistence. Objects can be persisted, fetched, queried or deleted by the DataStore methods. DataStores can be constructed by an instance of DataStoreFactory.

DataStores implementations should be thread safe.

Note: Results of updates (put(Object, Persistent), delete(Object) and deleteByQuery(Query) operations) are guaranteed to be visible to subsequent get / execute operations ONLY after a subsequent call to flush(). Additionally, exception handling is largely DataStore specific and is not largely dealt with from within this interface.

Method Summary

void	close() Close the DataStore.
void	createSchema() Creates the optional schema or table (or similar) in the datastore to hold the objects.
boolean	delete(K key) Deletes the object with the given key
long	deleteByQuery(Query<K,T> query) Deletes all the objects matching the query.
void	deleteSchema() Deletes the underlying schema or table (or similar) in the datastore that holds the objects.
Result<K,T>	execute(Query<K,T> query) Executes the given query and returns the results.
void	flush() Forces the write caches to be flushed.
T	get(K key) Returns the object corresponding to the given key fetching all the fields.
T	get(K key, String[] fields) Returns the object corresponding to the given key.
BeanFactory<K,T>	getBeanFactory() Returns the BeanFactory used by the DataStore
Class<K>	getKeyClass() Returns the class of the keys
List<PartitionQuery<K,T>>	getPartitions(Query<K,T> query) Partitions the given query and returns a list of PartitionQuerys, which will execute on local data.
Class<T>	getPersistentClass() Returns the class of the persistent objects
String	getSchemaName() Returns the schema name given to this DataStore
void	initialize(Class<K> keyClass, Class<T> persistentClass, Properties properties) Initializes this DataStore.
K	newKey() Returns a new instance of the key object.
T	newPersistent() Returns a new instance of the managed persistent object.
Query<K,T>	newQuery() Constructs and returns a new Query.
void	put(K key, T obj) Inserts the persistent object with the given key.
boolean	schemaExists() Returns whether the schema that holds the data exists in the datastore.
void	setBeanFactory(BeanFactory<K,T> beanFactory) Sets the BeanFactory to use by the DataStore.
void	setKeyClass(Class<K> keyClass) Sets the class of the keys
void	setPersistentClass(Class<T> persistentClass) Sets the class of the persistent objects
void	truncateSchema() Deletes all the data associated with the schema, but keeps the schema (table or similar) intact.

Method Detail

initialize

void initialize(Class<K> keyClass,
                Class<T> persistentClass,
                Properties properties)

Initializes this DataStore.

Parameters:

keyClass - the class of the keys

persistentClass - the class of the persistent objects

properties - extra metadata

Throws:

IOException

setKeyClass

void setKeyClass(Class<K> keyClass)

Sets the class of the keys

Parameters:

keyClass - the class of keys

getKeyClass

Class<K> getKeyClass()

Returns the class of the keys

Returns:

class of the keys

setPersistentClass

void setPersistentClass(Class<T> persistentClass)

Sets the class of the persistent objects

Parameters:

persistentClass - class of persistent objects

getPersistentClass

Class<T> getPersistentClass()

Returns the class of the persistent objects

Returns:

class of the persistent objects

getSchemaName

String getSchemaName()

Returns the schema name given to this DataStore

Returns:

schema name

createSchema

void createSchema()

Creates the optional schema or table (or similar) in the datastore to hold the objects. If the schema is already created previously, or the underlying data model does not support or need this operation, the operation is ignored.

Throws:

IOException

deleteSchema

void deleteSchema()

Deletes the underlying schema or table (or similar) in the datastore that holds the objects. This also deletes all the data associated with the schema.

Throws:

IOException

truncateSchema

void truncateSchema()

Deletes all the data associated with the schema, but keeps the schema (table or similar) intact.

Throws:

IOException

schemaExists

boolean schemaExists()

Returns whether the schema that holds the data exists in the datastore.

Returns:

whether schema exists

Throws:

IOException

newKey

K newKey()

Returns a new instance of the key object. If the object cannot be instantiated (it the class is a Java primitive wrapper, or does not have no-arg constructor) it throws an exception. Only use this function if you can make sure that the key class has a no-arg constructor.

Returns:

a new instance of the key object.

Throws:

IOException

newPersistent

T newPersistent()

Returns a new instance of the managed persistent object.

Returns:

a new instance of the managed persistent object.

Throws:

IOException

get

T get(K key)

Returns the object corresponding to the given key fetching all the fields.

Parameters:

key - the key of the object

Returns:

the Object corresponding to the key or null if it cannot be found

Throws:

IOException

get

T get(K key,
      String[] fields)

Returns the object corresponding to the given key.

Parameters:

key - the key of the object

fields - the fields required in the object. Pass null, to retrieve all fields

Returns:

the Object corresponding to the key or null if it cannot be found

Throws:

IOException

put

void put(K key,
         T obj)

Inserts the persistent object with the given key. If an object with the same key already exists it will silently be replaced. See also the note on visibility.

Throws:

IOException

delete

boolean delete(K key)

Deletes the object with the given key

Parameters:

key - the key of the object

Returns:

whether the object was successfully deleted

Throws:

IOException

deleteByQuery

long deleteByQuery(Query<K,T> query)

Deletes all the objects matching the query. See also the note on visibility.

Parameters:

query - matching records to this query will be deleted

Returns:

number of deleted records

Throws:

IOException

execute

Result<K,T> execute(Query<K,T> query)

Executes the given query and returns the results.

Parameters:

query - the query to execute.

Returns:

the results as a Result object.

Throws:

IOException

newQuery

Query<K,T> newQuery()

Constructs and returns a new Query.

Returns:

a new Query.

getPartitions

List<PartitionQuery<K,T>> getPartitions(Query<K,T> query)
                                                           throws IOException

Partitions the given query and returns a list of PartitionQuerys, which will execute on local data.

Parameters:

query - the base query to create the partitions for. If the query is null, then the data store returns the partitions for the default query (returning every object)

Returns:

a List of PartitionQuery's

Throws:

IOException

flush

void flush()

Forces the write caches to be flushed. DataStore implementations may optimize their writing by deferring the actual put / delete operations until this moment. See also the note on visibility.

Throws:

IOException

setBeanFactory

void setBeanFactory(BeanFactory<K,T> beanFactory)

Sets the BeanFactory to use by the DataStore.

Parameters:

beanFactory - the BeanFactory to use

getBeanFactory

BeanFactory<K,T> getBeanFactory()

Returns the BeanFactory used by the DataStore

Returns:

the BeanFactory used by the DataStore

close

void close()

Close the DataStore. This should release any resources held by the implementation, so that the instance is ready for GC. All other DataStore methods cannot be used after this method was called. Subsequent calls of this method are ignored.

Throws:

IOException