com.amazon.carbonado

Interface Query<S extends Storable>

All Known Implementing Classes:

AbstractQuery, EmptyQuery, StandardQuery

public interface Query<S extends Storable>

Supports complex retrieval and deletion of Storable objects. Queries are immutable representations of an action – they do not contain any Storable instances. The apparent mutators (with, et al) do not actually modify the Query. Instead, they return another Query instance which has the requested modification. To obtain an initial Query instance, call one of the Storage query methods.

Query objects are usually compiled and cached, and the same instance can be re-used for future queries. This is possible because queries are immutable and naturally thread-safe.

Author:

Brian S O'Neill

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Query.Controller Controller instance can be used to abort query operations.
static class	Query.Timeout Timeout controller, for aborting long running queries.

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.
Query<S>	and(java.lang.String filter) Returns a new query which has another filter logically "and"ed to this, potentially reducing the amount of results.
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.
void	deleteOne() Deletes one matching object.
void	deleteOne(Query.Controller controller) Deletes one matching object.
boolean	equals(java.lang.Object obj)
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.
<T extends S> Cursor<S>	fetchAfter(T start) Fetches results for this query after a given starting point, which is useful for re-opening a cursor.
<T extends S> Cursor<S>	fetchAfter(T start, Query.Controller controller) Fetches results for this query after a given starting point, which is useful for re-opening a cursor.
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.
java.lang.Class<S>	getStorableType() Returns the specific type of Storable managed by this object.
int	hashCode()
S	loadOne() Attempts to load exactly one matching object.
S	loadOne(Query.Controller controller) Attempts to load exactly one matching object.
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>	or(java.lang.String 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() Print the native query to standard out, which is useful for performance analysis.
boolean	printNative(java.lang.Appendable app) Prints the native query to any appendable, which is useful for performance analysis.
boolean	printNative(java.lang.Appendable app, int indentLevel) Prints the native query to any appendable, which is useful for performance analysis.
boolean	printPlan() Prints the query excecution plan to standard out, which is useful for performance analysis.
boolean	printPlan(java.lang.Appendable app) Prints the query excecution plan 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.
java.lang.String	toString() Returns a description of the query filter and any other arguments.
boolean	tryDeleteOne() Deletes zero or one matching objects.
boolean	tryDeleteOne(Query.Controller controller) Deletes zero or one matching objects.
S	tryLoadOne() Tries to load one record, but returns null if nothing was found.
S	tryLoadOne(Query.Controller controller) Tries to load one record, but returns null if nothing was found.
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.

Method Detail

getStorableType

java.lang.Class<S> getStorableType()

Returns the specific type of Storable managed by this object.

getFilter

Filter<S> getFilter()

Returns the query's filter.

getFilterValues

FilterValues<S> getFilterValues()

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

getBlankParameterCount

int getBlankParameterCount()

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

with

Query<S> with(int value)

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

Parameters:

value - parameter value to fill in

Throws:

java.lang.IllegalStateException - if no blank parameters

java.lang.IllegalArgumentException - if type doesn't match

with

Query<S> with(long value)

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

Parameters:

value - parameter value to fill in

Throws:

java.lang.IllegalStateException - if no blank parameters

java.lang.IllegalArgumentException - if type doesn't match

with

Query<S> with(float value)

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

Parameters:

value - parameter value to fill in

Throws:

java.lang.IllegalStateException - if no blank parameters

java.lang.IllegalArgumentException - if type doesn't match

with

Query<S> with(double value)

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

Parameters:

value - parameter value to fill in

Throws:

java.lang.IllegalStateException - if no blank parameters

java.lang.IllegalArgumentException - if type doesn't match

with

Query<S> with(boolean value)

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

Parameters:

value - parameter value to fill in

Throws:

java.lang.IllegalStateException - if no blank parameters

java.lang.IllegalArgumentException - if type doesn't match

with

Query<S> with(char value)

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

Parameters:

value - parameter value to fill in

Throws:

java.lang.IllegalStateException - if no blank parameters

java.lang.IllegalArgumentException - if type doesn't match

with

Query<S> with(byte value)

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

Parameters:

value - parameter value to fill in

Throws:

java.lang.IllegalStateException - if no blank parameters

java.lang.IllegalArgumentException - if type doesn't match

with

Query<S> with(short value)

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

Parameters:

value - parameter value to fill in

Throws:

java.lang.IllegalStateException - if no blank parameters

java.lang.IllegalArgumentException - if type doesn't match

with

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

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

Parameters:

value - parameter value to fill in

Throws:

java.lang.IllegalStateException - if no blank parameters

java.lang.IllegalArgumentException - if type doesn't match

withValues

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

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

Parameters:

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

Throws:

java.lang.IllegalStateException - if no blank parameters or if too many parameter values supplied

java.lang.IllegalArgumentException - if any type doesn't match

and

Query<S> and(java.lang.String filter)
                              throws FetchException

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

Parameters:

filter - query filter expression

Throws:

FetchException - if storage layer throws an exception

java.lang.IllegalStateException - if any blank parameters in this query, or if this query is already guaranteed to fetch nothing

java.lang.IllegalArgumentException - if filter is null

MalformedFilterException - if expression is malformed

java.lang.UnsupportedOperationException - if given filter is unsupported by repository

and

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

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

Parameters:

filter - query filter

Throws:

FetchException - if storage layer throws an exception

java.lang.IllegalStateException - if any blank parameters in this query, or if this query is already guaranteed to fetch nothing

java.lang.IllegalArgumentException - if filter is null

java.lang.UnsupportedOperationException - if given filter is unsupported by repository

or

Query<S> or(java.lang.String filter)
                             throws FetchException

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

Parameters:

filter - query filter expression

Throws:

FetchException - if storage layer throws an exception

java.lang.IllegalStateException - if any blank parameters in this query, or if this query is already guaranteed to fetch everything

java.lang.IllegalArgumentException - if filter is null

MalformedFilterException - if expression is malformed

java.lang.UnsupportedOperationException - if given filter is unsupported by repository

or

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

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

Parameters:

filter - query filter

Throws:

FetchException - if storage layer throws an exception

java.lang.IllegalStateException - if any blank parameters in this query, or if this query is already guaranteed to fetch everything

java.lang.IllegalArgumentException - if filter is null

java.lang.UnsupportedOperationException - if given filter is unsupported by repository

not

Query<S> not()
                              throws FetchException

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.

Throws:

FetchException - if storage layer throws an exception

java.lang.UnsupportedOperationException - if new query is unsupported by repository

orderBy

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

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.

Parameters:

property - name of property to order by

Throws:

FetchException - if storage layer throws an exception

java.lang.IllegalArgumentException - if property is null or is not a member of type S

java.lang.UnsupportedOperationException - if given ordering, combined with query filter, is unsupported by repository

orderBy

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

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.

Parameters:

properties - names of properties to order by

Throws:

FetchException - if storage layer throws an exception

java.lang.IllegalArgumentException - if any property is null or is not a member of type S

java.lang.UnsupportedOperationException - if given ordering, combined with query filter, is unsupported by repository

after

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

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.

Parameters:

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

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchException - if storage layer throws an exception

Since:

1.2

fetch

Cursor<S> fetch()
                                 throws FetchException

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.

Returns:

fetch results

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchException - if storage layer throws an exception

See Also:

Repository.enterTransaction(IsolationLevel)

fetch

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

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.

Parameters:

controller - optional controller which can abort query operation

Returns:

fetch results

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchException - if storage layer throws an exception

See Also:

Repository.enterTransaction(IsolationLevel)

fetchSlice

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

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.

Parameters:

from - zero-based from record number, inclusive

to - optional zero-based to record number, exclusive

Returns:

fetch results

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

java.lang.IllegalArgumentException - if from is negative or if from is more than to

FetchException - if storage layer throws an exception

Since:

1.2

fetchSlice

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

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.

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:

java.lang.IllegalStateException - if any blank parameters in this query

java.lang.IllegalArgumentException - if from is negative or if from is more than to

FetchException - if storage layer throws an exception

Since:

1.2

fetchAfter

<T extends S> Cursor<S> fetchAfter(T start)
                                      throws FetchException

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 cursor may start at an earlier position.

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

Calling fetchAfter(s) is equivalent to calling after(s).fetch().

Parameters:

start - storable to attempt to start after; if null, fetch all results

Returns:

fetch results

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchException - if storage layer throws an exception

See Also:

Repository.enterTransaction(IsolationLevel), after(T)

fetchAfter

<T extends S> Cursor<S> fetchAfter(T start,
                                 Query.Controller controller)
                                      throws FetchException

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 cursor may start at an earlier position.

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

Calling fetchAfter(s) is equivalent to calling after(s).fetch().

Parameters:

start - storable to attempt to start after; if null, fetch all results

controller - optional controller which can abort query operation

Returns:

fetch results

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchException - if storage layer throws an exception

See Also:

Repository.enterTransaction(IsolationLevel), after(T)

loadOne

S loadOne()
                           throws FetchException

Attempts to load exactly one matching object. If the number of matching records is zero or exceeds one, then an exception is thrown instead.

Returns:

a single fetched object

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchNoneException - if no matching record found

FetchMultipleException - if more than one matching record found

FetchException - if storage layer throws an exception

loadOne

S loadOne(Query.Controller controller)
                           throws FetchException

Attempts to load exactly one matching object. If the number of matching records is zero or exceeds one, then an exception is thrown instead.

Parameters:

controller - optional controller which can abort query operation

Returns:

a single fetched object

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchNoneException - if no matching record found

FetchMultipleException - if more than one matching record found

FetchException - if storage layer throws an exception

tryLoadOne

S tryLoadOne()
                              throws FetchException

Tries to load one record, but returns null if nothing was found. Throws exception if record count is more than one.

Returns:

null or a single fetched object

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchMultipleException - if more than one matching record found

FetchException - if storage layer throws an exception

tryLoadOne

S tryLoadOne(Query.Controller controller)
                              throws FetchException

Tries to load one record, but returns null if nothing was found. Throws exception if record count is more than one.

Parameters:

controller - optional controller which can abort query operation

Returns:

null or a single fetched object

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchMultipleException - if more than one matching record found

FetchException - if storage layer throws an exception

deleteOne

void deleteOne()
               throws PersistException

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

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

PersistNoneException - if no matching record found

PersistMultipleException - if more than one record matches

PersistException - if storage layer throws an exception

deleteOne

void deleteOne(Query.Controller controller)
               throws PersistException

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

Parameters:

controller - optional controller which can abort query operation

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

PersistNoneException - if no matching record found

PersistMultipleException - if more than one record matches

PersistException - if storage layer throws an exception

tryDeleteOne

boolean tryDeleteOne()
                     throws PersistException

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

Returns:

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

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

PersistMultipleException - if more than one record matches

PersistException - if storage layer throws an exception

tryDeleteOne

boolean tryDeleteOne(Query.Controller controller)
                     throws PersistException

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

Parameters:

controller - optional controller which can abort query operation

Returns:

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

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

PersistMultipleException - if more than one record matches

PersistException - if storage layer throws an exception

deleteAll

void deleteAll()
               throws PersistException

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.

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

PersistException - if storage layer throws an exception

deleteAll

void deleteAll(Query.Controller controller)
               throws PersistException

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.

Parameters:

controller - optional controller which can abort query operation

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

PersistException - if storage layer throws an exception

count

long count()
           throws FetchException

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.

Returns:

count of matches

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchException - if storage layer throws an exception

count

long count(Query.Controller controller)
           throws FetchException

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.

Parameters:

controller - optional controller which can abort query operation

Returns:

count of matches

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchException - if storage layer throws an exception

exists

boolean exists()
               throws FetchException

Returns true if any results are matched by this query.

Returns:

true if any matches

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchException - if storage layer throws an exception

Since:

1.2

exists

boolean exists(Query.Controller controller)
               throws FetchException

Returns true if any results are matched by this query.

Parameters:

controller - optional controller which can abort query operation

Returns:

true if any matches

Throws:

java.lang.IllegalStateException - if any blank parameters in this query

FetchException - if storage layer throws an exception

Since:

1.2

printNative

boolean printNative()

Print the native query to standard out, which is useful for performance analysis. Not all repositories have a native query format. An example native format is SQL.

Returns:

false if not implemented

printNative

boolean printNative(java.lang.Appendable app)
                    throws java.io.IOException

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.

Parameters:

app - append results here

Returns:

false if not implemented

Throws:

java.io.IOException

printNative

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

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.

Parameters:

app - append results here

indentLevel - amount to indent text, zero for none

Returns:

false if not implemented

Throws:

java.io.IOException

printPlan

boolean printPlan()

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

Returns:

false if not implemented

printPlan

boolean printPlan(java.lang.Appendable app)
                  throws java.io.IOException

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.

Parameters:

app - append results here

Returns:

false if not implemented

Throws:

java.io.IOException

printPlan

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

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.

Parameters:

app - append results here

indentLevel - amount to indent text, zero for none

Returns:

false if not implemented

Throws:

java.io.IOException

hashCode

int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

toString

java.lang.String toString()

Returns a description of the query filter and any other arguments.

Overrides:

toString in class java.lang.Object