com.neeve.query

Interface QueryEngine<ID,REC>

All Superinterfaces:

IdxFieldResolver<REC>

All Known Subinterfaces:

IStoreQueryEngine, RogLogQueryEngine

public interface QueryEngine<ID,REC>
extends IdxFieldResolver<REC>

A QueryEngine provides query functionality across one or more QueryRepositorys that have homogeneous key and value types.

QueryEngine implementations may support multiple

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	QueryEngine.BackgroundIndexingPolicy Enumerates valid background indexing policies.

Method Summary

Modifier and Type	Method and Description
void	addRepository(QueryRepository<ID,REC> repository, String alias) Adds a repository to the QueryEngine with the given alias.
void	close() Closes this QueryEngine.
<T> boolean	createIndex(IdxField<REC,T> field, boolean unique) Adds an index to this QueryEngine's repositories.
<T> boolean	createIndex(IdxField<REC,T> field, boolean unique, String name) Adds an index to this QueryEngine's repositories.
<T> boolean	createIndex(String columnDefinition, boolean unique) Parses a field using the QueryEngine's XPQL query syntax and creates an index for it.
Query<REC>	createQuery() Creates an empty Query that can be executed against this QueryEngine.
Query<REC>	createQuery(String xpql) Creates a Query corresponding to the provided SELECT statement.
boolean	dropIndex(IdxField<REC,?> field) Drops a previously created index for this QueryRepository.
boolean	dropIndex(String indexName) Drops a previously created indexes on each of this QueryEngine's QueryRepositorys.
QueryResultSet<REC>	execute(Query<REC> query) Executes a Query against this QueryEngine.
QueryResultSet<REC>	execute(String xpql) Executes an xpql query against this QueryEngine.
Object	executeStatement(String sql) Executes the XPQL Query or DDL statement.
double	getFetchRatioThreshold() Indicate the minimum proportion of an index's keys that qualify the index to be used in a Query.
<T> IdxField<REC,T>	getField(String columnDefinition) Parses a field using the query engine's parser.
Set<IdxField<REC,?>>	getIndexedFields() Retrieve the set of the fields that are being indexed by this QueryEngine's QueryRepositorys
<T> IdxNonUniqueIndex<T,ID>	getNonUniqueIndex(IdxField<REC,T> field) Retrieves non-unique index from this QueryEngine's repositories.
Collection<? extends QueryRepository<ID,REC>>	getRepositories() Gets this QueryEngine's current QueryRepositorys.
<T> IdxUniqueIndex<T,ID>	getUniqueIndex(IdxField<REC,T> field) Retrieves unique index from this QueryEngine's repositories.
void	removeRepository(String alias) Removes a QueryRepository from the QueryEngine.
void	setAutoIndexing(boolean autoIndex) Indicates whether or not automatic index creation should be performed for fields referenced by queries.
void	setAutoIndexLimit(int autoIndexLimit) Indicate the number of fields that should be indexed when auto-indexing is enabled.
void	setBackgroundIndexingPolicy(QueryEngine.BackgroundIndexingPolicy policy) Sets the policy to use for background index creation.
void	setDefaultIndexing(boolean defaultIndexing) Enable or disable the automatic creation of default indexes.
void	setDefaultPackage(Package pkg) Specify the Package within which to find classes that are used in queries.
void	setFetchRatioThreshold(double threshold) Indicate the minimum proportion of an index's keys that qualify the index to be used in a Query.
void	setQueryStatGeneration(boolean generateStats) Enable or disable the generation of QueryStats for Queries that are executed going forward.
void	setSortAreaInMemoryCardinality(int maxCardinality) Indicate the maximum number of records a SortArea-backed data structure can hold before it is moved to a disk-based data structure.
void	waitForBackgroundIndexing() Waits for any background indexing to complete

Methods inherited from interface com.neeve.query.index.IdxFieldResolver

getField, getField, getField

Method Detail

addRepository

void addRepository(QueryRepository<ID,REC> repository,
                   String alias)

Adds a repository to the QueryEngine with the given alias. Future queries can then reference this QueryRepository in the from clause using this QueryRepository, its alias, or its name as returned by QueryRepository.getName()

This is equivalent to calling addRepository(QueryRepository, String) with a null alias.

Adding a QueryRepository multiple times with a different alias has the effect of registering multiple alias for the QueryRepository. Adding a new QueryRepository with an already used alias replaces the current alias with the new QueryRepository.

Parameters:

repository - The repository to add.

See Also:

Query.from(String)

removeRepository

void removeRepository(String alias)

Removes a QueryRepository from the QueryEngine. It will be unavailable to future Querys that reference it. If the QueryRepository was added with one or more aliases these aliases will be unregistered as well.

Parameters:

alias - The alias with which the QueryRepository was added.

getRepositories

Collection<? extends QueryRepository<ID,REC>> getRepositories()

Gets this QueryEngine's current QueryRepositorys. The returned Collection should be considered immutable.

Returns:

this QueryEngine's current QueryRepositorys.

setDefaultPackage

void setDefaultPackage(Package pkg)

Specify the Package within which to find classes that are used in queries.

Parameters:

pkg - The default package to use when an a field's container type is unqualified.

setAutoIndexing

void setAutoIndexing(boolean autoIndex)

Indicates whether or not automatic index creation should be performed for fields referenced by queries.

Parameters:

autoIndex - True to dynamically create indexes.

createQuery

Query<REC> createQuery()

Creates an empty Query that can be executed against this QueryEngine.

Returns:

A new Query.

createQuery

Query<REC> createQuery(String xpql)
                throws QueryParseException

Creates a Query corresponding to the provided SELECT statement.

Parameters:

xpql - The query string

Throws:

QueryParseException

execute

QueryResultSet<REC> execute(String xpql)

Executes an xpql query against this QueryEngine.

Parameters:

xpql - The SELECT statement to execute.

Returns:

the QueryResult.

execute

QueryResultSet<REC> execute(Query<REC> query)

Executes a Query against this QueryEngine.

Parameters:

query - The Query to execute.

Returns:

the QueryResult.

executeStatement

Object executeStatement(String sql)
                 throws QueryException,
                        QueryParseException

Executes the XPQL Query or DDL statement. This statement returns a QueryResultSet if the provided sql is a SELECT statement.

Parameters:

sql - The statement to execute.

Returns:

An object containing the execution result if one exists.

Throws:

QueryException - If there is an error executing the statement.

QueryParseException - If there is an error parsing the statement.

close

void close()
    throws Exception

Closes this QueryEngine. A close on the database will interrupt and cleanly shutdown any ongoing indexing operations

Throws:

Exception

getField

<T> IdxField<REC,T> getField(String columnDefinition)
                      throws QueryException,
                             QueryParseException

Parses a field using the query engine's parser.

Parameters:

columnDefinition - A field.

Returns:

The resolved field

Throws:

QueryParseException - if the columnDefinition can't be parsed as a valid column name

QueryException - if there is an error resolving the field

createIndex

<T> boolean createIndex(String columnDefinition,
                        boolean unique)
                 throws QueryException,
                        QueryParseException

Parses a field using the QueryEngine's XPQL query syntax and creates an index for it. This is equivalent to calling getField(String) and using the result with createIndex(IdxField, boolean)

Parameters:

columnDefinition - The field defined in XPQL

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

Returns:

true if this resulted in an index being created.

Throws:

QueryParseException - if the fieldDef can't be parsed as a valid column name

QueryException - if there is an error creating the index.

See Also:

getField(String)

createIndex

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

Adds an index to this QueryEngine's repositories. 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 equivalent to calling createIndex(IdxField, boolean, String) with a value of null for the name.

Parameters:

field - The IdxField to index.

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

Returns:

true if this resulted in an index being created.

Throws:

QueryException - if there is an error creating the index.

createIndex

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

Adds an index to this QueryEngine's repositories. An index must be declared as either unique or non-unique. This decision determines whether the particular field is unique across all Object on a per QueryRepository basis.

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 a repository 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 a repository 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 QueryEngine currently has no open repositories an exception is thrown.

If this QueryEngine has been closed 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:

true if this resulted in an index being created.

Throws:

QueryException - If there is an error creating the index

getUniqueIndex

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

Retrieves unique index from this QueryEngine's repositories.

Parameters:

field - Field definition by which to search.

Returns:

The index instance, or null if none was found.

Throws:

QueryException - if index found, but is not unique.

getNonUniqueIndex

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

Retrieves non-unique index from this QueryEngine's repositories.

Parameters:

field - Field definition by which to search.

Returns:

The index instance, or null if none was found.

Throws:

QueryException - if index is found, but is unique.

setBackgroundIndexingPolicy

void setBackgroundIndexingPolicy(QueryEngine.BackgroundIndexingPolicy policy)

Sets the policy to use for background index creation.

Parameters:

policy - The indexing policy to use.

waitForBackgroundIndexing

void waitForBackgroundIndexing()
                        throws InterruptedException

Waits for any background indexing to complete

Throws:

InterruptedException - If the current thread is interrupted while waiting for background index creation

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 QueryEngine currently has no open repositories an exception is thrown.

If this QueryEngine has been closed an exception is thrown

Parameters:

field - The IdxField to stop indexing.

Throws:

QueryException - If there is an error dropping the index

dropIndex

boolean dropIndex(String indexName)
           throws QueryException

Drops a previously created indexes on each of this QueryEngine's QueryRepositorys. If there are no indexed with the given name this method does nothing.

Any QueryResultSet or QueryResult that depends on an index that is dropped is invalidated when an index is dropped.

If this QueryEngine currently has no open repositories an exception is thrown.

If this QueryEngine has been closed 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

getIndexedFields

Set<IdxField<REC,?>> getIndexedFields()

Retrieve the set of the fields that are being indexed by this QueryEngine's QueryRepositorys

Returns:

The Set of the fields indexed for this QueryEngine's QueryRepositorys

setFetchRatioThreshold

void setFetchRatioThreshold(double threshold)

Indicate the minimum proportion of an index's keys that qualify the index to be used in a Query. A value of 0.0 indicates that an index should only be used if it would return no results from the repository, e.g. WHERE someField = 'non-existent value'. A value of 0.1 would indicate that indexes should only be used if they would return 10% or less of the indexed field values, e.g. WHERE Person.age >= 85 A value of 1.0 would indicate that any usable indexes should be considered, even if this would result in reading the entire index only to then read the entire repository, e.g. WHERE Person.age < 120.

Parameters:

threshold - must be between 0.0 and 1.0.

getFetchRatioThreshold

double getFetchRatioThreshold()

Indicate the minimum proportion of an index's keys that qualify the index to be used in a Query. A value of 0.0 indicates that an index should only be used if it would return no results from the repository, e.g. WHERE someField = 'non-existent value'.

Returns:

The current fetch ration threshold.

setDefaultIndexing

void setDefaultIndexing(boolean defaultIndexing)

Enable or disable the automatic creation of default indexes. The specific indexes are determined by the particular QueryEngine. These fields may include, for example, a timestamp or audit fields. Such indexes are then create created in any repository associated with this QueryEngine.

Parameters:

defaultIndexing - A boolean value that enables/disables this functionality.

setQueryStatGeneration

void setQueryStatGeneration(boolean generateStats)

Enable or disable the generation of QueryStats for Queries that are executed going forward. See QueryResultSet.getQueryStats(String repositoryName).

Parameters:

generateStats - Whether or not to enables stats collection

setAutoIndexLimit

void setAutoIndexLimit(int autoIndexLimit)

Indicate the number of fields that should be indexed when auto-indexing is enabled.

Parameters:

autoIndexLimit - The auto index limit.

setSortAreaInMemoryCardinality

void setSortAreaInMemoryCardinality(int maxCardinality)

Indicate the maximum number of records a SortArea-backed data structure can hold before it is moved to a disk-based data structure.

Parameters:

maxCardinality - The threshold beyond which sort area results are offloaded to disk.