com.neeve.query
Interface QueryRepository<ID,REC>

All Known Subinterfaces:

IStoreQueryRepository, RogLogRepository

public interface QueryRepository<ID,REC>

A QueryRepository is an indexable store of Objects that can be queried by a QueryEngine.

Its 3 main purpose are:

• Maintain indexes on objects that are exposed to the QueryEngine that map object attributes to their unique keys.
• Provide accessors to its objects.
• Map values to their unique key.

A QueryEngine uses a QueryRepository's IdxIndexes to assist in execution of queries. Users can proactively add indexes to this QueryRepository or it can be left to the discretion of the QueryEngine or the QueryRepository implementation itself.

A QueryRepository is responsible for keeping its indexes in sync with the objects it contains. Any operation performed on an IdxIndex in the repository must be representative of all values in the repository at the time the IdxIndex is accessed.

However, it is possible that from the time an IdxIndex returns results to the time the index entries are used to access records in the repository that the corresponding values have changed. To allow access to multiple indexes and object retrieval while the repository is in a consistent state the acquireWriteLock() method may be called.

Method Summary

void	acquireWriteLock() Lock the QueryRepository from being updated.
void	close() Close the repository and its associated indexes.
<T> IdxIndex<T,ID>	createIndex(IdxField<REC,T> field, boolean unique) Adds an index to this repository.
<T> IdxIndex<T,ID>	createIndex(IdxField<REC,T> field, boolean unique, String name) Adds an index to this QueryRepository.
boolean	dropIndex(IdxField<REC,?> field) Drops a previously created index for this QueryRepository.
boolean	dropIndex(String indexName) Drops a previously created index for this QueryRepository.
void	flushIndexing() Waits for indexing to complete.
<T> IdxIndex<T,ID>	getIndex(IdxField<REC,T> field) Gets a IdxIndex for the given Class's field if an index exists, or null no index exists.
List<IdxIndex<?,ID>>	getIndexes() Retrieve a list of the names of all indexes managed by this repository.
String	getName()
<T> IdxNonUniqueIndex<T,ID>	getNonUniqueIndex(IdxField<REC,T> field) Gets a IdxNonUniqueIndex for the given Class's field if such an index exists, or null no index exists.
<T> IdxUniqueIndex<T,ID>	getUniqueIndex(IdxField<REC,T> field) Gets a IdxUniqueIndex for the given Class's corresponding field if such an index exists, or null no index exists.
void	open() Opens this repository and its associate index.
void	releaseWriteLock() Releases a QueryRepositorys write lock.
REC	retrieve(ID key) Retrieves a record for the repository.
Iterable<REC>	retrieve(Iterable<ID> keys) Returns an Iterable of all values in the QueryRepository for the given keys.
Iterable<REC>	retrieveAll() Returns an iterable set of all values in the QueryRepository.

Method Detail

getName

String getName()

Returns:

The name of this repository.

open

void open()
          throws Exception

Opens this repository and its associate index. A subsequent call to open on an open repository has no effect.

Throws:

Exception - If there is an error opening the log.

close

void close()
           throws Exception

Close the repository and its associated indexes.

Throws:

Exception - If there is an error closing the repository.

createIndex

<T> IdxIndex<T,ID> createIndex(IdxField<REC,T> field,
                               boolean unique)
                           throws QueryException

Adds an index to this repository. An index must be declared as either unique or non-unique. This decision determines whether the particular field is unique across all Object in this repository.

This is equivalent to calling createIndex(IdxField, boolean, String) with a name that is null

Parameters:

field - The IdxField to index.

unique - Whether or not the index is guaranteed to be unique.

Returns:

The newly created index, null otherwise.

Throws:

QueryException

createIndex

<T> IdxIndex<T,ID> createIndex(IdxField<REC,T> field,
                               boolean unique,
                               String name)
                           throws QueryException

Adds an index to this QueryRepository. An index must be declared as either unique or non-unique. This decision determines whether the particular field is unique across all Object in this repository.

If the name provided is null or empty then the name of the index will be the name of the field as returned by IdxField.getName()

If this QueryRepository already has the index then this operation will not have any effect unless the existing index has a name different from this field's name in which case it will result in the index being renamed.

If this QueryRepository already has an index with this name, but corresponding to a different field then the existing index will be dropped and replaced by this index.

If this QueryRepository isn't open an exception is thrown.

Parameters:

field - The IdxField to index.

unique - Whether or not the index is guaranteed to be unique.

name - A name for the index. If null the name of the field will be used.

Returns:

The newly created index if a new index was created, null otherwise

Throws:

QueryException - If there is an error creating the index

dropIndex

boolean dropIndex(IdxField<REC,?> field)
                  throws QueryException

Drops a previously created index for this QueryRepository. If there is no such index this method simply does nothing.

If this QueryRepository isn't open an exception is thrown.

Parameters:

field - The IdxField to stop indexing.

Returns:

true if this resulted in an index being dropped.

Throws:

QueryException - If there is an error dropping the index

dropIndex

boolean dropIndex(String indexName)
                  throws QueryException

Drops a previously created index for this QueryRepository. If there is no such index this method simply does nothing.

If this QueryRepository isn't open an exception is thrown.

Parameters:

indexName - The name of the index to drop

Returns:

true if this resulted in an index being dropped.

Throws:

QueryException - If there is an error dropping the index

getIndexes

List<IdxIndex<?,ID>> getIndexes()

Retrieve a list of the names of all indexes managed by this repository.

If this QueryRepository isn't open an exception is thrown.

Returns:

The Set of index names for the QueryRepository

getIndex

<T> IdxIndex<T,ID> getIndex(IdxField<REC,T> field)
                        throws QueryException

Gets a IdxIndex for the given Class's field if an index exists, or null no index exists.

Parameters:

field - The IdxField for which to retrieve the index.

Throws:

QueryException

getUniqueIndex

<T> IdxUniqueIndex<T,ID> getUniqueIndex(IdxField<REC,T> field)
                                    throws QueryException

Gets a IdxUniqueIndex for the given Class's corresponding field if such an index exists, or null no index exists.

Parameters:

field - The IdxField for which to retrieve the index.

Throws:

QueryException

getNonUniqueIndex

<T> IdxNonUniqueIndex<T,ID> getNonUniqueIndex(IdxField<REC,T> field)
                                          throws QueryException

Gets a IdxNonUniqueIndex for the given Class's field if such an index exists, or null no index exists.

Parameters:

field - The IdxField for which to retrieve the index.

Throws:

QueryException

retrieve

REC retrieve(ID key)
             throws QueryException

Retrieves a record for the repository.

Parameters:

key - The unique key that identifies the record.

Returns:

The repository record or null if no such record exists.

Throws:

QueryException - if there is an error fetching the result.

retrieveAll

Iterable<REC> retrieveAll()
                          throws QueryException

Returns an iterable set of all values in the QueryRepository.

Returns:

An iterable set of all values in the QueryRepository.

Throws:

QueryException - if there is an error preparing the results

retrieve

Iterable<REC> retrieve(Iterable<ID> keys)
                       throws QueryException

Returns an Iterable of all values in the QueryRepository for the given keys. If a particular key can not be found then the returned Iterable should omit the value without complaint. This returned Iterable does not need to prefetch these values and may instead fetch them lazily.

Parameters:

keys - The keys for the values to be retrieved.

Returns:

The values from the repository.

Throws:

QueryException - if there is an error preparing the results

acquireWriteLock

void acquireWriteLock()

Lock the QueryRepository from being updated. This allows a QueryEngine to perform operations against multiple indexes against the QueryRepository while it is in a consistent state.

releaseWriteLock

void releaseWriteLock()

Releases a QueryRepositorys write lock.

flushIndexing

void flushIndexing()
                   throws QueryException

Waits for indexing to complete. If new entries are being added to the repository this method need only wait until current entries are indexed.

Throws:

QueryException - if there is an error waiting for indexing to complete.