com.amazon.carbonado.qe

Class StandardQuery<S extends Storable>

java.lang.Object

com.amazon.carbonado.qe.AbstractQuery<S>

com.amazon.carbonado.qe.StandardQuery<S>

All Implemented Interfaces:

Query<S>, Appender

public abstract class StandardQuery<S extends Storable>
extends AbstractQuery<S>
implements Appender

Abstract query implementation which uses a QueryExecutor.

Author:

Brian S O'Neill

Nested Class Summary

Nested classes/interfaces inherited from interface com.amazon.carbonado.Query

Query.Controller, Query.Timeout

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StandardQuery(Filter<S> filter, FilterValues<S> values, OrderingList<S> ordering, QueryHints hints)

Method Summary

Methods

Modifier and Type	Method and Description
<T extends S> Query<S>	after(T start) Returns a query which fetches results for this query after a given starting point, which is useful for re-opening a cursor.
Query<S>	and(Filter<S> filter) Returns a new query which has another filter logically "and"ed to this, potentially reducing the amount of results.
void	appendTo(java.lang.Appendable app) Append the string representation of this object to the given Appendable.
protected void	clearExecutor() Clears any cached reference to a query executor.
long	count() Returns a count of all results matched by this query.
long	count(Query.Controller controller) Returns a count of all results matched by this query.
void	deleteAll() Deletes zero or more matching objects.
void	deleteAll(Query.Controller controller) Deletes zero or more matching objects.
protected abstract Transaction	enterTransaction(IsolationLevel level) Enter a transaction as needed by the standard delete operation, or null if transactions are not supported.
boolean	equals(java.lang.Object obj)
protected QueryExecutor<S>	executor() Returns the executor in use by this query.
protected abstract QueryExecutorFactory<S>	executorFactory() Return a QueryExecutorFactory which is used to get an executor.
boolean	exists() Returns true if any results are matched by this query.
boolean	exists(Query.Controller controller) Returns true if any results are matched by this query.
Cursor<S>	fetch() Fetches results for this query.
Cursor<S>	fetch(Query.Controller controller) Fetches results for this query.
Cursor<S>	fetchSlice(long from, java.lang.Long to) Fetches a slice of results for this query, as defined by a numerical range.
Cursor<S>	fetchSlice(long from, java.lang.Long to, Query.Controller controller) Fetches a slice of results for this query, as defined by a numerical range.
int	getBlankParameterCount() Returns the amount of blank parameters that need to be filled in.
Filter<S>	getFilter() Returns the query's filter.
FilterValues<S>	getFilterValues() Returns the query's filter values, which is null if filter has no parameters.
protected OrderingList<S>	getOrdering()
java.lang.Class<S>	getStorableType() Returns the specific type of Storable managed by this object.
int	hashCode()
protected abstract StandardQuery<S>	newInstance(FilterValues<S> values, OrderingList<S> ordering, QueryHints hints) Return a new or cached instance of StandardQuery implementation, using new filter values.
Query<S>	not() Returns a new query which produces all the results not supplied in this query.
Query<S>	or(Filter<S> filter) Returns a new query which has another filter logically "or"ed to this, potentially increasing the amount of results.
Query<S>	orderBy(java.lang.String... properties) Returns a copy of this query ordered by specific property values.
Query<S>	orderBy(java.lang.String property) Returns a copy of this query ordered by a specific property value.
boolean	printNative(java.lang.Appendable app, int indentLevel) Prints the native query to any appendable, which is useful for performance analysis.
boolean	printPlan(java.lang.Appendable app, int indentLevel) Prints the query excecution plan to any appendable, which is useful for performance analysis.
protected abstract QueryFactory<S>	queryFactory() Return a QueryFactory which is used to form new queries from this one.
protected void	resetExecutor() Resets any cached reference to a query executor.
protected void	setExecutor() Ensures that a cached query executor reference is available.
boolean	tryDeleteOne() Deletes zero or one matching objects.
boolean	tryDeleteOne(Query.Controller controller) Deletes zero or one matching objects.
Query<S>	with(boolean value) Returns a copy of this Query with the next blank parameter filled in.
Query<S>	with(byte value) Returns a copy of this Query with the next blank parameter filled in.
Query<S>	with(char value) Returns a copy of this Query with the next blank parameter filled in.
Query<S>	with(double value) Returns a copy of this Query with the next blank parameter filled in.
Query<S>	with(float value) Returns a copy of this Query with the next blank parameter filled in.
Query<S>	with(int value) Returns a copy of this Query with the next blank parameter filled in.
Query<S>	with(long value) Returns a copy of this Query with the next blank parameter filled in.
Query<S>	with(java.lang.Object value) Returns a copy of this Query with the next blank parameter filled in.
Query<S>	with(short value) Returns a copy of this Query with the next blank parameter filled in.
Query<S>	withValues(java.lang.Object... values) Returns a copy of this Query with the next blank parameters filled in.

Methods inherited from class com.amazon.carbonado.qe.AbstractQuery

and, checkSliceArguments, deleteOne, deleteOne, fetchAfter, fetchAfter, loadOne, loadOne, or, printNative, printNative, printPlan, printPlan, toString, tryLoadOne, tryLoadOne

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

StandardQuery

protected StandardQuery(Filter<S> filter,
             FilterValues<S> values,
             OrderingList<S> ordering,
             QueryHints hints)

Parameters:

filter - optional filter object, defaults to open filter if null

values - optional values object, defaults to filter initial values

ordering - optional order-by properties

hints - optional query hints

Method Detail

getStorableType

public java.lang.Class<S> getStorableType()

Description copied from interface: Query

Returns the specific type of Storable managed by this object.

Specified by:

getStorableType in interface Query<S extends Storable>

getFilter

public Filter<S> getFilter()

Description copied from interface: Query

Returns the query's filter.

Specified by:

getFilter in interface Query<S extends Storable>

getFilterValues

public FilterValues<S> getFilterValues()

Description copied from interface: Query

Returns the query's filter values, which is null if filter has no parameters.

Specified by:

getFilterValues in interface Query<S extends Storable>

getBlankParameterCount

public int getBlankParameterCount()

Description copied from interface: Query

Returns the amount of blank parameters that need to be filled in. If zero, then this query is ready to be used.

Specified by:

getBlankParameterCount in interface Query<S extends Storable>

with

public Query<S> with(int value)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameter filled in.

Specified by:

with in interface Query<S extends Storable>

Parameters:

value - parameter value to fill in

with

public Query<S> with(long value)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameter filled in.

Specified by:

with in interface Query<S extends Storable>

Parameters:

value - parameter value to fill in

with

public Query<S> with(float value)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameter filled in.

Specified by:

with in interface Query<S extends Storable>

Parameters:

value - parameter value to fill in

with

public Query<S> with(double value)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameter filled in.

Specified by:

with in interface Query<S extends Storable>

Parameters:

value - parameter value to fill in

with

public Query<S> with(boolean value)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameter filled in.

Specified by:

with in interface Query<S extends Storable>

Parameters:

value - parameter value to fill in

with

public Query<S> with(char value)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameter filled in.

Specified by:

with in interface Query<S extends Storable>

Parameters:

value - parameter value to fill in

with

public Query<S> with(byte value)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameter filled in.

Specified by:

with in interface Query<S extends Storable>

Parameters:

value - parameter value to fill in

with

public Query<S> with(short value)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameter filled in.

Specified by:

with in interface Query<S extends Storable>

Parameters:

value - parameter value to fill in

with

public Query<S> with(java.lang.Object value)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameter filled in.

Specified by:

with in interface Query<S extends Storable>

Parameters:

value - parameter value to fill in

withValues

public Query<S> withValues(java.lang.Object... values)

Description copied from interface: Query

Returns a copy of this Query with the next blank parameters filled in.

Specified by:

withValues in interface Query<S extends Storable>

Parameters:

values - parameter values to fill in; if null or empty, this Query instance is returned

and

public Query<S> and(Filter<S> filter)
                              throws FetchException

Description copied from interface: Query

Returns a new query which has another filter logically "and"ed to this, potentially reducing the amount of results.

Specified by:

and in interface Query<S extends Storable>

Parameters:

filter - query filter

Throws:

FetchException - if storage layer throws an exception

or

public Query<S> or(Filter<S> filter)
                             throws FetchException

Description copied from interface: Query

Returns a new query which has another filter logically "or"ed to this, potentially increasing the amount of results.

Specified by:

or in interface Query<S extends Storable>

Parameters:

filter - query filter

Throws:

FetchException - if storage layer throws an exception

not

public Query<S> not()
                              throws FetchException

Description copied from interface: Query

Returns a new query which produces all the results not supplied in this query. Any filled in parameters in this query are copied into the new one.

Specified by:

not in interface Query<S extends Storable>

Throws:

FetchException - if storage layer throws an exception

orderBy

public Query<S> orderBy(java.lang.String property)
                                  throws FetchException

Description copied from interface: Query

Returns a copy of this query ordered by a specific property value. The property name may be prefixed with '+' or '-' to indicate ascending or descending order. If the prefix is omitted, ascending order is assumed.

Note: Specification of ordering properties is not cumulative. Calling this method will first remove any previous ordering properties.

Specified by:

orderBy in interface Query<S extends Storable>

Parameters:

property - name of property to order by

Throws:

FetchException - if storage layer throws an exception

orderBy

public Query<S> orderBy(java.lang.String... properties)
                                  throws FetchException

Description copied from interface: Query

Returns a copy of this query ordered by specific property values. The property names may be prefixed with '+' or '-' to indicate ascending or descending order. If the prefix is omitted, ascending order is assumed.

Note: Specification of ordering properties is not cumulative. Calling this method will first remove any previous ordering properties.

Specified by:

orderBy in interface Query<S extends Storable>

Parameters:

properties - names of properties to order by

Throws:

FetchException - if storage layer throws an exception

after

public <T extends S> Query<S> after(T start)
                                throws FetchException

Description copied from interface: Query

Returns a query which fetches results for this query after a given starting point, which is useful for re-opening a cursor. This is only effective when query has been given an explicit ordering. If not a total ordering, then query may start at an earlier position.

Note: The returned query can be very expensive to fetch from repeatedly, if the query needs to perform a sort operation. Ideally, the query ordering should match the natural ordering of an index or key.

Specified by:

after in interface Query<S extends Storable>

Parameters:

start - storable to attempt to start after; if null, this query is returned

Throws:

FetchException - if storage layer throws an exception

fetch

public Cursor<S> fetch()
                                 throws FetchException

Description copied from interface: Query

Fetches results for this query. If any updates or deletes might be performed on the results, consider enclosing the fetch in a transaction. This allows the isolation level and "for update" mode to be adjusted. Some repositories might otherwise deadlock.

Specified by:

fetch in interface Query<S extends Storable>

Returns:

fetch results

Throws:

FetchException - if storage layer throws an exception

See Also:

Repository.enterTransaction(IsolationLevel)

fetch

public Cursor<S> fetch(Query.Controller controller)
                                 throws FetchException

Description copied from interface: Query

Fetches results for this query. If any updates or deletes might be performed on the results, consider enclosing the fetch in a transaction. This allows the isolation level and "for update" mode to be adjusted. Some repositories might otherwise deadlock.

Specified by:

fetch in interface Query<S extends Storable>

Parameters:

controller - optional controller which can abort query operation

Returns:

fetch results

Throws:

FetchException - if storage layer throws an exception

See Also:

Repository.enterTransaction(IsolationLevel)

fetchSlice

public Cursor<S> fetchSlice(long from,
                   java.lang.Long to)
                                      throws FetchException

Description copied from interface: Query

Fetches a slice of results for this query, as defined by a numerical range. A slice can be used to limit the number of results from a query. It is strongly recommended that the query be given a total ordering in order for the slice results to be deterministic.

Specified by:

fetchSlice in interface Query<S extends Storable>

Parameters:

from - zero-based from record number, inclusive

to - optional zero-based to record number, exclusive

Returns:

fetch results

Throws:

FetchException - if storage layer throws an exception

fetchSlice

public Cursor<S> fetchSlice(long from,
                   java.lang.Long to,
                   Query.Controller controller)
                                      throws FetchException

Description copied from interface: Query

Fetches a slice of results for this query, as defined by a numerical range. A slice can be used to limit the number of results from a query. It is strongly recommended that the query be given a total ordering in order for the slice results to be deterministic.

Specified by:

fetchSlice in interface Query<S extends Storable>

Parameters:

from - zero-based from record number, inclusive

to - optional zero-based to record number, exclusive

controller - optional controller which can abort query operation

Returns:

fetch results

Throws:

FetchException - if storage layer throws an exception

tryDeleteOne

public boolean tryDeleteOne()
                     throws PersistException

Description copied from interface: Query

Deletes zero or one matching objects. If the number of matching records exceeds one, then no delete occurs, and an exception is thrown instead.

Specified by:

tryDeleteOne in interface Query<S extends Storable>

Returns:

true if record existed and was deleted, or false if no match

Throws:

PersistMultipleException - if more than one record matches

PersistException - if storage layer throws an exception

tryDeleteOne

public boolean tryDeleteOne(Query.Controller controller)
                     throws PersistException

Description copied from interface: Query

Deletes zero or one matching objects. If the number of matching records exceeds one, then no delete occurs, and an exception is thrown instead.

Specified by:

tryDeleteOne in interface Query<S extends Storable>

Parameters:

controller - optional controller which can abort query operation

Returns:

true if record existed and was deleted, or false if no match

Throws:

PersistMultipleException - if more than one record matches

PersistException - if storage layer throws an exception

deleteAll

public void deleteAll()
               throws PersistException

Description copied from interface: Query

Deletes zero or more matching objects. There is no guarantee that deleteAll is an atomic operation. If atomic behavior is desired, wrap the call in a transaction scope.

Specified by:

deleteAll in interface Query<S extends Storable>

Throws:

PersistException - if storage layer throws an exception

deleteAll

public void deleteAll(Query.Controller controller)
               throws PersistException

Description copied from interface: Query

Deletes zero or more matching objects. There is no guarantee that deleteAll is an atomic operation. If atomic behavior is desired, wrap the call in a transaction scope.

Specified by:

deleteAll in interface Query<S extends Storable>

Parameters:

controller - optional controller which can abort query operation

Throws:

PersistException - if storage layer throws an exception

count

public long count()
           throws FetchException

Description copied from interface: Query

Returns a count of all results matched by this query. Even though no results are explicitly fetched, this method may still be expensive to call. The actual performance will vary by repository and available indexes.

Specified by:

count in interface Query<S extends Storable>

Returns:

count of matches

Throws:

FetchException - if storage layer throws an exception

count

public long count(Query.Controller controller)
           throws FetchException

Description copied from interface: Query

Returns a count of all results matched by this query. Even though no results are explicitly fetched, this method may still be expensive to call. The actual performance will vary by repository and available indexes.

Specified by:

count in interface Query<S extends Storable>

Parameters:

controller - optional controller which can abort query operation

Returns:

count of matches

Throws:

FetchException - if storage layer throws an exception

exists

public boolean exists()
               throws FetchException

Description copied from interface: Query

Returns true if any results are matched by this query.

Specified by:

exists in interface Query<S extends Storable>

Returns:

true if any matches

Throws:

FetchException - if storage layer throws an exception

exists

public boolean exists(Query.Controller controller)
               throws FetchException

Description copied from interface: Query

Returns true if any results are matched by this query.

Specified by:

exists in interface Query<S extends Storable>

Parameters:

controller - optional controller which can abort query operation

Returns:

true if any matches

Throws:

FetchException - if storage layer throws an exception

printNative

public boolean printNative(java.lang.Appendable app,
                  int indentLevel)
                    throws java.io.IOException

Description copied from interface: Query

Prints the native query to any appendable, which is useful for performance analysis. Not all repositories have a native query format. An example native format is SQL.

Specified by:

printNative in interface Query<S extends Storable>

Parameters:

app - append results here

indentLevel - amount to indent text, zero for none

Returns:

false if not implemented

Throws:

java.io.IOException

printPlan

public boolean printPlan(java.lang.Appendable app,
                int indentLevel)
                  throws java.io.IOException

Description copied from interface: Query

Prints the query excecution plan to any appendable, which is useful for performance analysis. There is no standard format for query plans, nor is it a requirement that this method be implemented.

Specified by:

printPlan in interface Query<S extends Storable>

Parameters:

app - append results here

indentLevel - amount to indent text, zero for none

Returns:

false if not implemented

Throws:

java.io.IOException

hashCode

public int hashCode()

Specified by:

hashCode in interface Query<S extends Storable>

Specified by:

hashCode in class AbstractQuery<S extends Storable>

equals

public boolean equals(java.lang.Object obj)

Specified by:

equals in interface Query<S extends Storable>

Specified by:

equals in class AbstractQuery<S extends Storable>

appendTo

public void appendTo(java.lang.Appendable app)
              throws java.io.IOException

Description copied from interface: Appender

Append the string representation of this object to the given Appendable.

Specified by:

appendTo in interface Appender

Parameters:

app - Appendable object to receive string representation

Throws:

java.io.IOException - if thrown from given Appendable

getOrdering

protected OrderingList<S> getOrdering()

executor

protected QueryExecutor<S> executor()
                                              throws RepositoryException

Returns the executor in use by this query.

Throws:

RepositoryException

setExecutor

protected void setExecutor()
                    throws RepositoryException

Ensures that a cached query executor reference is available. If not, the query executor factory is called and the executor is cached.

Throws:

RepositoryException

resetExecutor

protected void resetExecutor()
                      throws RepositoryException

Resets any cached reference to a query executor. If a reference is available, it is replaced, but a clear reference is not set.

Throws:

RepositoryException

clearExecutor

protected void clearExecutor()

Clears any cached reference to a query executor. The next time this Query is used, it will get an executor from the query executor factory and cache a reference to it.

enterTransaction

protected abstract Transaction enterTransaction(IsolationLevel level)

Enter a transaction as needed by the standard delete operation, or null if transactions are not supported.

Parameters:

level - minimum desired isolation level

queryFactory

protected abstract QueryFactory<S> queryFactory()

Return a QueryFactory which is used to form new queries from this one.

executorFactory

protected abstract QueryExecutorFactory<S> executorFactory()

Return a QueryExecutorFactory which is used to get an executor.

newInstance

protected abstract StandardQuery<S> newInstance(FilterValues<S> values,
                           OrderingList<S> ordering,
                           QueryHints hints)

Return a new or cached instance of StandardQuery implementation, using new filter values. The Filter in the FilterValues is the same as was passed in the constructor.

Parameters:

values - non-null values object

ordering - order-by properties, never null