StandardQuery (Carbonado 1.2.3 API)

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

Class StandardQuery<S extends Storable>

Nested Class Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Constructor Detail

StandardQuery

Method Detail

getStorableType

getFilter

getFilterValues

getBlankParameterCount

with

with

with

with

with

with

with

with

with

withValues

and

or

not

orderBy

orderBy

after

fetch

fetch

fetchSlice

fetchSlice

tryDeleteOne

tryDeleteOne

deleteAll

deleteAll

count

count

exists

exists

printNative

printPlan

hashCode

equals

appendTo

getOrdering

executor

setExecutor

resetExecutor

clearExecutor

enterTransaction

queryFactory

executorFactory

newInstance