com.amazon.carbonado.qe

Class AbstractQuery<S extends Storable>

java.lang.Object

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

All Implemented Interfaces:

Query<S>, Appender

Direct Known Subclasses:

EmptyQuery, StandardQuery

public abstract class AbstractQuery<S extends Storable>
extends java.lang.Object
implements Query<S>, Appender

AbstractQuery implements a small set of common Query methods. Subclasses should consider overriding some of these methods, if it provides better performance.

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	AbstractQuery()

Method Summary

Methods

Modifier and Type	Method and Description
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.
protected boolean	checkSliceArguments(long from, java.lang.Long to) Called by sliced fetch to ensure that arguments are valid.
void	deleteOne() Deletes one matching object.
void	deleteOne(Query.Controller controller) Deletes one matching object.
abstract boolean	equals(java.lang.Object obj)
<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.
abstract 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>	or(java.lang.String filter) Returns a new query which has another filter logically "or"ed to this, potentially increasing the amount of results.
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	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.
java.lang.String	toString() Implementation calls appendTo.
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.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.amazon.carbonado.Query

after, and, count, count, deleteAll, deleteAll, exists, exists, fetch, fetch, fetchSlice, fetchSlice, getBlankParameterCount, getFilter, getFilterValues, getStorableType, not, or, orderBy, orderBy, printNative, printPlan, tryDeleteOne, tryDeleteOne, with, with, with, with, with, with, with, with, with, withValues

Methods inherited from interface com.amazon.carbonado.util.Appender

appendTo

Constructor Detail

AbstractQuery

protected AbstractQuery()

Method Detail

and

public Query<S> and(java.lang.String 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 expression

Throws:

FetchException - if storage layer throws an exception

or

public Query<S> or(java.lang.String 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 expression

Throws:

FetchException - if storage layer throws an exception

fetchAfter

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

Description copied from interface: Query

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().

Specified by:

fetchAfter in interface Query<S extends Storable>

Parameters:

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

Returns:

fetch results

Throws:

FetchException - if storage layer throws an exception

See Also:

Repository.enterTransaction(IsolationLevel), Query.after(T)

fetchAfter

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

Description copied from interface: Query

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().

Specified by:

fetchAfter in interface Query<S extends Storable>

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:

FetchException - if storage layer throws an exception

See Also:

Repository.enterTransaction(IsolationLevel), Query.after(T)

loadOne

public S loadOne()
                           throws FetchException

Description copied from interface: Query

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

Specified by:

loadOne in interface Query<S extends Storable>

Returns:

a single fetched object

Throws:

FetchNoneException - if no matching record found

FetchMultipleException - if more than one matching record found

FetchException - if storage layer throws an exception

loadOne

public S loadOne(Query.Controller controller)
                           throws FetchException

Description copied from interface: Query

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

Specified by:

loadOne in interface Query<S extends Storable>

Parameters:

controller - optional controller which can abort query operation

Returns:

a single fetched object

Throws:

FetchNoneException - if no matching record found

FetchMultipleException - if more than one matching record found

FetchException - if storage layer throws an exception

tryLoadOne

public S tryLoadOne()
                              throws FetchException

Description copied from interface: Query

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

Specified by:

tryLoadOne in interface Query<S extends Storable>

Returns:

null or a single fetched object

Throws:

FetchMultipleException - if more than one matching record found

FetchException - if storage layer throws an exception

tryLoadOne

public S tryLoadOne(Query.Controller controller)
                              throws FetchException

Description copied from interface: Query

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

Specified by:

tryLoadOne in interface Query<S extends Storable>

Parameters:

controller - optional controller which can abort query operation

Returns:

null or a single fetched object

Throws:

FetchMultipleException - if more than one matching record found

FetchException - if storage layer throws an exception

deleteOne

public void deleteOne()
               throws PersistException

Description copied from interface: Query

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.

Specified by:

deleteOne in interface Query<S extends Storable>

Throws:

PersistNoneException - if no matching record found

PersistMultipleException - if more than one record matches

PersistException - if storage layer throws an exception

deleteOne

public void deleteOne(Query.Controller controller)
               throws PersistException

Description copied from interface: Query

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.

Specified by:

deleteOne in interface Query<S extends Storable>

Parameters:

controller - optional controller which can abort query operation

Throws:

PersistNoneException - if no matching record found

PersistMultipleException - if more than one record matches

PersistException - if storage layer throws an exception

printNative

public boolean printNative()

Description copied from interface: Query

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.

Specified by:

printNative in interface Query<S extends Storable>

Returns:

false if not implemented

printNative

public boolean printNative(java.lang.Appendable app)
                    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

Returns:

false if not implemented

Throws:

java.io.IOException

printPlan

public boolean printPlan()

Description copied from interface: Query

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.

Specified by:

printPlan in interface Query<S extends Storable>

Returns:

false if not implemented

printPlan

public boolean printPlan(java.lang.Appendable app)
                  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

Returns:

false if not implemented

Throws:

java.io.IOException

toString

public java.lang.String toString()

Implementation calls appendTo.

Specified by:

toString in interface Query<S extends Storable>

Overrides:

toString in class java.lang.Object

hashCode

public abstract int hashCode()

Specified by:

hashCode in interface Query<S extends Storable>

Overrides:

hashCode in class java.lang.Object

equals

public abstract boolean equals(java.lang.Object obj)

Specified by:

equals in interface Query<S extends Storable>

Overrides:

equals in class java.lang.Object

checkSliceArguments

protected boolean checkSliceArguments(long from,
                          java.lang.Long to)

Called by sliced fetch to ensure that arguments are valid.

Returns:

false if from is 0 and to is null

Throws:

java.lang.IllegalArgumentException - if arguments are invalid

Since:

1.2