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

Type Parameters:

ID - The ID type for records that will be indexed

REC - The type of record that will be indexed

public interface QueryIndexer<ID,REC>

An QueryIndexer handles creation and retrieval of IdxIndexes against an indexable repository. Application code does not normally operate directly with a QueryIndexer, but rather utilizes the corresponding index management methods on a QueryRepository or QueryEngine which delegate index management to their underlying QueryIndexer

Any IdxIndex created or retrieved through an instance of this class are considered 'owned' by that instance and are tied to its lifecycle.

Method Summary

void	clear(boolean dropIndexes) Removes all indexed entries, optionally preserving the index definitions.
void	close() Shut down the QueryIndexer.
void	commit(long commitSequenceNumber) Commits all indexeing operations since the last call to commit(long).
<T> IdxIndex<T,ID>	createIndex(IdxField<REC,T> field, boolean unique, String name) Adds an index to this QueryIndexer.
void	delete() If the index is persistent, deletes the index.
<T> boolean	dropIndex(IdxField<REC,T> field) Drops a previously created index.
boolean	dropIndex(String indexName) Drops a previously created index for this.
<T> IdxIndex<T,ID>	getIndex(IdxField<REC,T> field) Retrieve an existing IdxIndex.
List<IdxIndex<?,ID>>	getIndexes() Retrieve all IdxIndexes.
String	getIndexProperty(String name) Gets a stored property value.
<T> IdxIndex.Stats<T>	getIndexStats(IdxField<REC,T> field) Gets Index statistics for an index.
long	getLiveCommitSequenceNumber() Retrieved the last (highest) successfully committed sequence number.
<T> IdxNonUniqueIndex<T,ID>	getNonUniqueIndex(IdxField<REC,T> field) Retrieve an existing IdxNonUniqueIndex.
int	getSize() Return the size of the indexed data set.
<T> IdxUniqueIndex<T,ID>	getUniqueIndex(IdxField<REC,T> field) Retrieve an existing IdxUniqueIndex.
boolean	isLiveCommitSequenceNumber(long commitSequence) Indicates whether this commit sequence number represents a live commit sequence number.
void	open() Opens an QueryIndexer.
void	put(REC record) Indexes an object.
void	remove(REC record) Remove all index entries for this object.
void	rename(String newName) Renames the QueryIndexer.
void	rollback() Discard any current indexing.
void	setIndexProperty(String name, String value) Stores a name/value pair for the indexer.
void	update(REC before, REC after) Updates indexes by removing indexed values for an old record and adding values for a new record.
<T> void	updateField(REC record, IdxField<REC,T> field, T oldVal, T newVal) Updates indexes for a single field and it subfields by removing indexed values for the old field value and adding indexes for the new field value.

Method Detail

setIndexProperty

void setIndexProperty(String name,
                      String value)

Stores a name/value pair for the indexer. This can be used to store identifying information for the indexer. These properties must be persisted if the indexer is a persistent index.

Parameters:

name - The property name

value - The property value

getIndexProperty

String getIndexProperty(String name)

Gets a stored property value.

Parameters:

name - The property name

getLiveCommitSequenceNumber

long getLiveCommitSequenceNumber()

Retrieved the last (highest) successfully committed sequence number. This is used by a QueryRepository to indicate which records have already been indexed.

Any index owned by this QueryIndexer's IdxIndex are considered to be 'live' if all of the records up to this sequence number have been indexed for that index. An index that is not live is one that has been added after initial indexing has been done. Such indexes trigger a re-index operation to catch them up to the live sequence number.

The live sequence number does not necessarily indicate that the index is up to date with respect to all of the records in the QueryRepository being indexed. It is possible that the repositories indexer has records beyond this sequence number that still need indexing.

Returns:

Retrieves the last live committed sequence number.

isLiveCommitSequenceNumber

boolean isLiveCommitSequenceNumber(long commitSequence)

Indicates whether this commit sequence number represents a live commit sequence number.

Parameters:

commitSequence - the commitSequenceNumber to test.

open

void open()
          throws Exception

Opens an QueryIndexer.

Throws:

Exception - If there is an error opening the QueryIndexer.

Threading:

This method is not safe for concurrent access with other methods

close

void close()
           throws Exception

Shut down the QueryIndexer. Any indexes returned by the index manager are no longer valid for use.

Throws:

Exception - If there is an error closing the QueryIndexer.

Threading:

This method is not safe for concurrent access with other methods

rename

void rename(String newName)
            throws QueryException

Renames the QueryIndexer. The name of an indexer is used to to create its persistent files. After calling this method all indexes owned by this QueryIndexer are invalid, and must be refetched.

Parameters:

newName - The new name of the QueryIndexer

Throws:

QueryException

Threading:

This method is not safe for concurrent access with other methods in this class or any IdxIndex owned by this QueryIndexer

delete

void delete()
            throws QueryException,
                   IllegalStateException

If the index is persistent, deletes the index. This can only be called on an indexer that is closed.

Throws:

QueryException - If there is an error deleting the index.

IllegalStateException - if the indexer is open.

Threading:

This method is not safe for concurrent access with other methods

rollback

void rollback()

Discard any current indexing.

commit

void commit(long commitSequenceNumber)

Commits all indexeing operations since the last call to commit(long).

Parameters:

commitSequenceNumber - A monotonically increasing commit sequence number.

createIndex

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

Adds an index to this QueryIndexer. 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 name will be the name of the field as returned by IdxField.getName()

If this QueryIndexer 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 QueryIndexer 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 QueryIndexer isn't open an exception is thrown.

Upon addition of a new index, the caller must reindex existing records prior to committing any new records. The next call to commit with a sequence number greater than or equal to the last commit sequence number returned by getLiveCommitSequenceNumber() will have the effect of marking the newly created index as being indexed up until that point so it is critical that all existing records be reindexed before such a call is made.

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 or existing index.

Throws:

QueryException - If there is an error creating the index.

dropIndex

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

Drops a previously created index. If there is no such index this method simply does nothing. Once dropped any corresponding IdxIndex may no longer be used.

Parameters:

field - the field for which the index should be dropped.

Returns:

true if an index was 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. If there is no such index this method simply does nothing. Once dropped the corresponding IdxIndex may no longer be used.

Parameters:

indexName - the name of the index to drop.

Returns:

true if an index was dropped.

Throws:

QueryException - If there is an error dropping the index.

getIndex

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

Retrieve an existing IdxIndex.

Parameters:

field - IdxField the field for which the index should be retrieved.

Returns:

The index or null of no such index exists,

getUniqueIndex

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

Retrieve an existing IdxUniqueIndex.

Parameters:

field - IdxField the field for which the index should be retrieved.

Returns:

The index or null of no such index exists,

getNonUniqueIndex

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

Retrieve an existing IdxNonUniqueIndex.

Parameters:

field - IdxField the field for which the index should be retrieved.

Returns:

The index or null of no such index exists,

getIndexes

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

Retrieve all IdxIndexes.

Returns:

All IdxIndexes.

getIndexStats

<T> IdxIndex.Stats<T> getIndexStats(IdxField<REC,T> field)

Gets Index statistics for an index.

Parameters:

field - The field for which to retrieve index statistics.

Returns:

The index stats or null if no index exists for the field.

put

void put(REC record)

Indexes an object. All of the fields on the record that match an index will be indexed.

Parameters:

record - The record to be indexed.

update

void update(REC before,
            REC after)

Updates indexes by removing indexed values for an old record and adding values for a new record.

Parameters:

before - The record containing the last indexed values. If null this method behaves just like put(Object)

after - The record containing the new values to index

updateField

<T> void updateField(REC record,
                     IdxField<REC,T> field,
                     T oldVal,
                     T newVal)

Updates indexes for a single field and it subfields by removing indexed values for the old field value and adding indexes for the new field value.

Parameters:

record - The record containing the field

field - The field

oldVal - The old value

newVal - The new value

remove

void remove(REC record)

Remove all index entries for this object.

Parameters:

record - The record for index entries should be removed.

clear

void clear(boolean dropIndexes)

Removes all indexed entries, optionally preserving the index definitions.

Parameters:

dropIndexes - If false all indexes will be dropped along with their contents if true, then all the enties in the indexes will be dropped, but the index definitions will remain.

getSize

int getSize()

Return the size of the indexed data set.