SelectQuery (Cayenne Server 4.0.M2 API)

java.lang.Object
- org.apache.cayenne.query.AbstractQuery
- - org.apache.cayenne.query.SelectQuery<T>

All Implemented Interfaces:

Serializable, ConfigurationNode, ParameterizedQuery, Query, Select<T>, XMLSerializable

Direct Known Subclasses:

PrefetchSelectQuery
```
public class SelectQuery<T>
extends AbstractQuery
implements ParameterizedQuery, XMLSerializable, Select<T>
```
A query that selects persistent objects of a certain type or "raw data" (aka DataRows). Supports expression qualifier, multiple orderings and a number of other parameters that serve as runtime hints to Cayenne on how to optimize the fetch and result processing.

See Also:
Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`distinct`
`static boolean`	`DISTINCT_DEFAULT`
`static String`	`DISTINCT_PROPERTY`
`protected List<Ordering>`	`orderings`
`protected Expression`	`qualifier`

Fields inherited from class org.apache.cayenne.query.AbstractQuery
dataMap, name, root

Constructor Summary

Constructors
Constructor and Description
`SelectQuery()` Creates an empty SelectQuery.
`SelectQuery(Class<T> rootClass)` Creates a SelectQuery that selects all objects of a given persistent class.
`SelectQuery(Class<T> rootClass, Expression qualifier)` Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
`SelectQuery(Class<T> rootClass, Expression qualifier, List<? extends Ordering> orderings)` Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
`SelectQuery(DbEntity root)` Creates a SelectQuery for the specified DbEntity.
`SelectQuery(DbEntity root, Expression qualifier)` Creates a SelectQuery for the specified DbEntity with the given qualifier.
`SelectQuery(DbEntity root, Expression qualifier, List<? extends Ordering> orderings)` Creates a SelectQuery for the specified DbEntity with the given qualifier and orderings.
`SelectQuery(ObjEntity root)` Creates a SelectQuery with null qualifier, for the specifed ObjEntity
`SelectQuery(ObjEntity root, Expression qualifier)` Creates a SelectQuery for the specified ObjEntity with the given qualifier.
`SelectQuery(ObjEntity root, Expression qualifier, List<? extends Ordering> orderings)` Creates a SelectQuery for the specified ObjEntity with the given qualifier and orderings.
`SelectQuery(String objEntityName)` Creates SelectQuery with `objEntityName` parameter.
`SelectQuery(String objEntityName, Expression qualifier)` Creates SelectQuery with `objEntityName` and `qualifier` parameters.
`SelectQuery(String objEntityName, Expression qualifier, List<? extends Ordering> orderings)` Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addOrdering(Ordering ordering)` Adds ordering specification to this query orderings.
`void`	`addOrdering(String sortPathSpec, SortOrder order)` Adds ordering specification to this query orderings.
`void`	`addOrderings(Collection<? extends Ordering> orderings)` Adds a list of orderings.
`void`	`addPrefetch(PrefetchTreeNode prefetchElement)` Adds a prefetch with specified relationship path to the query.
`PrefetchTreeNode`	`addPrefetch(String prefetchPath)` Adds a prefetch with specified relationship path to the query.
`void`	`aliasPathSplits(String path, String... aliases)` Adds one or more aliases for the qualifier expression path.
`void`	`andQualifier(Expression e)` Adds specified qualifier to the existing qualifier joining it using "AND".
`void`	`clearOrderings()` Clears all configured orderings.
`void`	`clearPrefetches()` Clears all stored prefetch paths.
`SelectQuery<T>`	`createQuery(Map<String,?> parameters)` Creates and returns a new SelectQuery built using this query as a prototype and substituting qualifier parameters with the values from the map.
`SQLAction`	`createSQLAction(SQLActionVisitor visitor)` Calls "makeSelect" on the visitor.
`static SelectQuery<DataRow>`	`dataRowQuery(Class<?> rootClass)`
`static SelectQuery<DataRow>`	`dataRowQuery(Class<?> rootClass, Expression qualifier)` Creates a SelectQuery that selects DataRows that correspond to a given persistent class that match supplied qualifier.
`static SelectQuery<DataRow>`	`dataRowQuery(Class<?> rootClass, Expression qualifier, List<Ordering> orderings)`
`void`	`encodeAsXML(XMLEncoder encoder)` Prints itself as XML to the provided PrintWriter.
`String[]`	`getCacheGroups()`
`QueryCacheStrategy`	`getCacheStrategy()`
`int`	`getFetchLimit()` Returns the fetchLimit.
`int`	`getFetchOffset()` Returns the fetchOffset.
`QueryMetadata`	`getMetaData(EntityResolver resolver)` Returns default select parameters.
`List<Ordering>`	`getOrderings()` Returns a list of orderings used by this query.
`int`	`getPageSize()` Returns `pageSize` property.
`PrefetchTreeNode`	`getPrefetchTree()`
`Expression`	`getQualifier()` Returns query qualifier.
`int`	`getStatementFetchSize()`
`void`	`initWithProperties(Map<String,?> properties)` Initializes query parameters using a set of properties.
`boolean`	`isDistinct()` Returns true if this query returns distinct rows.
`boolean`	`isFetchingDataRows()` Returns `true` if this query should produce a list of data rows as opposed to DataObjects, `false` for DataObjects.
`void`	`orQualifier(Expression e)` Adds specified qualifier to the existing qualifier joining it using "OR".
`static <T> SelectQuery<T>`	`query(Class<T> rootClass)` Creates a SelectQuery that selects objects of a given persistent class.
`static <T> SelectQuery<T>`	`query(Class<T> rootClass, Expression qualifier)` Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
`static <T> SelectQuery<T>`	`query(Class<T> rootClass, Expression qualifier, List<? extends Ordering> orderings)` Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
`SelectQuery<T>`	`queryWithParameters(Map<String,?> parameters)` A shortcut for `queryWithParameters(Map, boolean)`that prunes parts of qualifier that have no parameter value set.
`SelectQuery<T>`	`queryWithParameters(Map<String,?> parameters, boolean pruneMissing)` Returns a query built using this query as a prototype, using a set of parameters to build the qualifier.
`void`	`removeOrdering(Ordering ordering)` Removes ordering.
`void`	`removePrefetch(String prefetchPath)` Removes prefetch.
`void`	`route(QueryRouter router, EntityResolver resolver, Query substitutedQuery)` Routes itself and if there are any prefetches configured, creates prefetch queries and routes them as well.
`void`	`setCacheGroups(String... cacheGroups)`
`void`	`setCacheStrategy(QueryCacheStrategy strategy)`
`void`	`setDistinct(boolean distinct)` Sets `distinct` property that determines whether this query returns distinct row.
`void`	`setFetchingDataRows(boolean flag)` Deprecated. since 4.0, use `dataRowQuery(Class, Expression)` to create DataRow query instead.
`void`	`setFetchLimit(int fetchLimit)` Sets the fetchLimit.
`void`	`setFetchOffset(int fetchOffset)`
`void`	`setPageSize(int pageSize)` Sets `pageSize` property.
`void`	`setPrefetchTree(PrefetchTreeNode prefetchTree)`
`void`	`setQualifier(Expression qualifier)` Sets new query qualifier.
`void`	`setStatementFetchSize(int size)` Sets statement's fetch size (0 for default size)
`void`	`useLocalCache(String... cacheGroups)` Instructs Cayenne to look for query results in the "local" cache when running the query.
`void`	`useSharedCache(String... cacheGroups)` Instructs Cayenne to look for query results in the "shared" cache when running the query.

Methods inherited from class org.apache.cayenne.query.AbstractQuery
acceptVisitor, getDataMap, getName, getRoot, setDataMap, setName, setRoot, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.cayenne.query.Query
getDataMap, getName

Methods inherited from interface org.apache.cayenne.configuration.ConfigurationNode
acceptVisitor

- Field Detail
  - DISTINCT_PROPERTY
```
public static final String DISTINCT_PROPERTY
```
    See Also:
    Constant Field Values
  - DISTINCT_DEFAULT
```
public static final boolean DISTINCT_DEFAULT
```
    See Also:
    Constant Field Values
  - qualifier
```
protected Expression qualifier
```
  - orderings
```
protected List<Ordering> orderings
```
  - distinct
```
protected boolean distinct
```
- Constructor Detail
  - SelectQuery
```
public SelectQuery()
```
    Creates an empty SelectQuery.
  - SelectQuery
```
public SelectQuery(ObjEntity root)
```
    Creates a SelectQuery with null qualifier, for the specifed ObjEntity
    
    Parameters:
    root - the ObjEntity this SelectQuery is for.
  - SelectQuery
```
public SelectQuery(ObjEntity root,
           Expression qualifier)
```
    Creates a SelectQuery for the specified ObjEntity with the given qualifier.
    
    Parameters:
    root - the ObjEntity this SelectQuery is for.
    qualifier - an Expression indicating which objects should be fetched
  - SelectQuery
```
public SelectQuery(ObjEntity root,
           Expression qualifier,
           List<? extends Ordering> orderings)
```
    Creates a SelectQuery for the specified ObjEntity with the given qualifier and orderings.
    
    Parameters:
    root - the ObjEntity this SelectQuery is for.
    qualifier - an Expression indicating which objects should be fetched.
    orderings - defines how to order the results, may be null.
    Since:
    
    3.1
  - SelectQuery
```
public SelectQuery(Class<T> rootClass)
```
    Creates a SelectQuery that selects all objects of a given persistent class.
    
    Parameters:
    rootClass - the Class of objects fetched by this query.
  - SelectQuery
```
public SelectQuery(Class<T> rootClass,
           Expression qualifier)
```
    Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
    
    Parameters:
    rootClass - the Class of objects fetched by this query.
    qualifier - an Expression indicating which objects should be fetched.
  - SelectQuery
```
public SelectQuery(Class<T> rootClass,
           Expression qualifier,
           List<? extends Ordering> orderings)
```
    Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
    
    Parameters:
    rootClass - the Class of objects fetched by this query.
    qualifier - an Expression indicating which objects should be fetched.
    orderings - defines how to order the results, may be null.
    Since:
    
    3.1
  - SelectQuery
```
public SelectQuery(DbEntity root)
```
    Creates a SelectQuery for the specified DbEntity.
    
    Parameters:
    root - the DbEntity this SelectQuery is for.
    Since:
    
    1.1
  - SelectQuery
```
public SelectQuery(DbEntity root,
           Expression qualifier)
```
    Creates a SelectQuery for the specified DbEntity with the given qualifier.
    
    Parameters:
    root - the DbEntity this SelectQuery is for.
    qualifier - an Expression indicating which objects should be fetched.
    Since:
    
    1.1
  - SelectQuery
```
public SelectQuery(DbEntity root,
           Expression qualifier,
           List<? extends Ordering> orderings)
```
    Creates a SelectQuery for the specified DbEntity with the given qualifier and orderings.
    
    Parameters:
    root - the DbEntity this SelectQuery is for.
    qualifier - an Expression indicating which objects should be fetched.
    orderings - defines how to order the results, may be null.
    Since:
    
    3.1
  - SelectQuery
```
public SelectQuery(String objEntityName)
```
    Creates SelectQuery with objEntityName parameter.
  - SelectQuery
```
public SelectQuery(String objEntityName,
           Expression qualifier)
```
    Creates SelectQuery with objEntityName and qualifier parameters.
  - SelectQuery
```
public SelectQuery(String objEntityName,
           Expression qualifier,
           List<? extends Ordering> orderings)
```
    Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
    
    Parameters:
    objEntityName - the name of the ObjEntity to fetch from.
    qualifier - an Expression indicating which objects should be fetched.
    orderings - defines how to order the results, may be null.
    Since:
    
    3.1
- Method Detail
  - query
```
public static <T> SelectQuery<T> query(Class<T> rootClass)
```
    Creates a SelectQuery that selects objects of a given persistent class.
    
    Parameters:
    rootClass - the Class of objects fetched by this query.
    Since:
    
    4.0
  - query
```
public static <T> SelectQuery<T> query(Class<T> rootClass,
                       Expression qualifier)
```
    Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
    
    Parameters:
    rootClass - the Class of objects fetched by this query.
    qualifier - an Expression indicating which objects should be fetched.
    Since:
    
    4.0
  - query
```
public static <T> SelectQuery<T> query(Class<T> rootClass,
                       Expression qualifier,
                       List<? extends Ordering> orderings)
```
    Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
    
    Parameters:
    rootClass - the Class of objects fetched by this query.
    qualifier - an Expression indicating which objects should be fetched.
    orderings - defines how to order the results, may be null.
    Since:
    
    4.0
  - dataRowQuery
```
public static SelectQuery<DataRow> dataRowQuery(Class<?> rootClass)
```
    Since:
    
    4.0
  - dataRowQuery
```
public static SelectQuery<DataRow> dataRowQuery(Class<?> rootClass,
                                Expression qualifier)
```
    Creates a SelectQuery that selects DataRows that correspond to a given persistent class that match supplied qualifier.
    
    Parameters:
    rootClass - the Class of objects that correspond to DataRows entity.
    qualifier - an Expression indicating which objects should be fetched.
    Since:
    
    4.0
  - dataRowQuery
```
public static SelectQuery<DataRow> dataRowQuery(Class<?> rootClass,
                                Expression qualifier,
                                List<Ordering> orderings)
```
    Since:
    
    4.0
  - getMetaData
```
public QueryMetadata getMetaData(EntityResolver resolver)
```
    Description copied from class: AbstractQuery
    
    Returns default select parameters.
    
    Specified by:
    
    getMetaData in interface Query
    
    Overrides:
    
    getMetaData in class AbstractQuery
    
    Since:
    
    1.2
  - route
```
public void route(QueryRouter router,
         EntityResolver resolver,
         Query substitutedQuery)
```
    Routes itself and if there are any prefetches configured, creates prefetch queries and routes them as well.
    
    Specified by:
    
    route in interface Query
    
    Overrides:
    
    route in class AbstractQuery
    
    Since:
    
    1.2
  - createSQLAction
```
public SQLAction createSQLAction(SQLActionVisitor visitor)
```
    Calls "makeSelect" on the visitor.
    
    Specified by:
    
    createSQLAction in interface Query
    
    Specified by:
    
    createSQLAction in class AbstractQuery
    
    Since:
    
    1.2
  - initWithProperties
```
public void initWithProperties(Map<String,?> properties)
```
    Initializes query parameters using a set of properties.
    
    Since:
    
    1.1
  - encodeAsXML
```
public void encodeAsXML(XMLEncoder encoder)
```
    Prints itself as XML to the provided PrintWriter.
    
    Specified by:
    
    encodeAsXML in interface XMLSerializable
    
    Since:
    
    1.1
  - queryWithParameters
```
public SelectQuery<T> queryWithParameters(Map<String,?> parameters)
```
    A shortcut for queryWithParameters(Map, boolean)that prunes parts of qualifier that have no parameter value set.
  - queryWithParameters
```
public SelectQuery<T> queryWithParameters(Map<String,?> parameters,
                                 boolean pruneMissing)
```
    Returns a query built using this query as a prototype, using a set of parameters to build the qualifier.
    
    See Also:
    parameter substitution.
  - createQuery
```
public SelectQuery<T> createQuery(Map<String,?> parameters)
```
    Creates and returns a new SelectQuery built using this query as a prototype and substituting qualifier parameters with the values from the map.
    
    Specified by:
    
    createQuery in interface ParameterizedQuery
    
    Since:
    
    1.1
  - addOrdering
```
public void addOrdering(Ordering ordering)
```
    Adds ordering specification to this query orderings.
  - addOrderings
```
public void addOrderings(Collection<? extends Ordering> orderings)
```
    Adds a list of orderings.
  - addOrdering
```
public void addOrdering(String sortPathSpec,
               SortOrder order)
```
    Adds ordering specification to this query orderings.
    
    Since:
    
    3.0
  - removeOrdering
```
public void removeOrdering(Ordering ordering)
```
    Removes ordering.
    
    Since:
    
    1.1
  - getOrderings
```
public List<Ordering> getOrderings()
```
    Returns a list of orderings used by this query.
  - clearOrderings
```
public void clearOrderings()
```
    Clears all configured orderings.
  - isDistinct
```
public boolean isDistinct()
```
    Returns true if this query returns distinct rows.
  - setDistinct
```
public void setDistinct(boolean distinct)
```
    Sets distinct property that determines whether this query returns distinct row.
  - aliasPathSplits
```
public void aliasPathSplits(String path,
                   String... aliases)
```
    Adds one or more aliases for the qualifier expression path. Aliases serve to instruct Cayenne to generate separate sets of joins for overlapping paths, that maybe needed for complex conditions. An example of an implicit splits is this method: ExpressionFactory.matchAllExp(String, Object...).
    
    Since:
    
    3.0
  - getPrefetchTree
```
public PrefetchTreeNode getPrefetchTree()
```
    Since:
    
    1.2
  - setPrefetchTree
```
public void setPrefetchTree(PrefetchTreeNode prefetchTree)
```
    Since:
    
    1.2
  - addPrefetch
```
public void addPrefetch(PrefetchTreeNode prefetchElement)
```
    Adds a prefetch with specified relationship path to the query.
    
    Since:
    
    4.0
  - addPrefetch
```
public PrefetchTreeNode addPrefetch(String prefetchPath)
```
    Adds a prefetch with specified relationship path to the query.
    
    Since:
    
    1.2 signature changed to return created PrefetchTreeNode.
  - clearPrefetches
```
public void clearPrefetches()
```
    Clears all stored prefetch paths.
  - removePrefetch
```
public void removePrefetch(String prefetchPath)
```
    Removes prefetch.
    
    Since:
    
    1.1
  - isFetchingDataRows
```
public boolean isFetchingDataRows()
```
    Returns true if this query should produce a list of data rows as opposed to DataObjects, false for DataObjects. This is a hint to QueryEngine executing this query.
  - setFetchingDataRows
```
public void setFetchingDataRows(boolean flag)
```
    Deprecated. since 4.0, use dataRowQuery(Class, Expression) to create DataRow query instead.
    
    Sets query result type. If flag parameter is true, then results will be in the form of data rows.
    Note that if the root of this query is a DbEntity, this setting has no effect, and data rows are always fetched.
  - getCacheStrategy
```
public QueryCacheStrategy getCacheStrategy()
```
    Since:
    
    3.0
  - setCacheStrategy
```
public void setCacheStrategy(QueryCacheStrategy strategy)
```
    Since:
    
    3.0
  - getCacheGroups
```
public String[] getCacheGroups()
```
    Since:
    
    3.0
  - setCacheGroups
```
public void setCacheGroups(String... cacheGroups)
```
    Since:
    
    3.0
  - useLocalCache
```
public void useLocalCache(String... cacheGroups)
```
    Instructs Cayenne to look for query results in the "local" cache when running the query. This is a short-hand notation for:
```
 query.setCacheStrategy(QueryCacheStrategy.LOCAL_CACHE);
 query.setCacheGroups("group1", "group2");
 
```
    Since:
    
    4.0
  - useSharedCache
```
public void useSharedCache(String... cacheGroups)
```
    Instructs Cayenne to look for query results in the "shared" cache when running the query. This is a short-hand notation for:
```
 query.setCacheStrategy(QueryCacheStrategy.SHARED_CACHE);
 query.setCacheGroups("group1", "group2");
 
```
    Since:
    
    4.0
  - getFetchOffset
```
public int getFetchOffset()
```
    Returns the fetchOffset.
    
    Since:
    
    3.0
  - getFetchLimit
```
public int getFetchLimit()
```
    Returns the fetchLimit.
  - setFetchLimit
```
public void setFetchLimit(int fetchLimit)
```
    Sets the fetchLimit.
  - setFetchOffset
```
public void setFetchOffset(int fetchOffset)
```
    Since:
    
    3.0
  - getPageSize
```
public int getPageSize()
```
    Returns pageSize property. See setPageSize for more details.
  - setPageSize
```
public void setPageSize(int pageSize)
```
    Sets pageSize property. By setting a page size, the Collection returned by performing a query will return hollow DataObjects. This is considerably faster and uses a tiny fraction of the memory compared to a non-paged query when large numbers of objects are returned in the result. When a hollow DataObject is accessed all DataObjects on the same page will be faulted into memory. There will be a small delay when faulting objects while the data is fetched from the data source, but otherwise you do not need to do anything special to access data in hollow objects. The first page is always faulted into memory immediately.
    
    Parameters:
    pageSize - The pageSize to set
  - setStatementFetchSize
```
public void setStatementFetchSize(int size)
```
    Sets statement's fetch size (0 for default size)
    
    Since:
    
    3.0
  - getStatementFetchSize
```
public int getStatementFetchSize()
```
    Returns:
    statement's fetch size
    Since:
    
    3.0
  - setQualifier
```
public void setQualifier(Expression qualifier)
```
    Sets new query qualifier.
  - getQualifier
```
public Expression getQualifier()
```
    Returns query qualifier.
  - andQualifier
```
public void andQualifier(Expression e)
```
    Adds specified qualifier to the existing qualifier joining it using "AND".
  - orQualifier
```
public void orQualifier(Expression e)
```
    Adds specified qualifier to the existing qualifier joining it using "OR".

Class SelectQuery<T>

Field Summary

Fields inherited from class org.apache.cayenne.query.AbstractQuery

Constructor Summary

Method Summary

Methods inherited from class org.apache.cayenne.query.AbstractQuery

Methods inherited from class java.lang.Object

Methods inherited from interface org.apache.cayenne.query.Query

Methods inherited from interface org.apache.cayenne.configuration.ConfigurationNode

Field Detail

DISTINCT_PROPERTY

DISTINCT_DEFAULT

qualifier

orderings

distinct

Constructor Detail

SelectQuery

SelectQuery

SelectQuery

SelectQuery

SelectQuery

SelectQuery

SelectQuery

SelectQuery

SelectQuery

SelectQuery

SelectQuery

SelectQuery

SelectQuery

Method Detail

query

query

query

dataRowQuery

dataRowQuery

dataRowQuery

getMetaData

route

createSQLAction

initWithProperties

encodeAsXML

queryWithParameters

queryWithParameters

createQuery

addOrdering

addOrderings

addOrdering

removeOrdering

getOrderings

clearOrderings

isDistinct

setDistinct

aliasPathSplits

getPrefetchTree

setPrefetchTree

addPrefetch

addPrefetch

clearPrefetches

removePrefetch

isFetchingDataRows

setFetchingDataRows

getCacheStrategy

setCacheStrategy

getCacheGroups

setCacheGroups

useLocalCache

useSharedCache

getFetchOffset

getFetchLimit

setFetchLimit

setFetchOffset

getPageSize

setPageSize

setStatementFetchSize

getStatementFetchSize

setQualifier

getQualifier

andQualifier

orQualifier