org.apache.cayenne.query
Class SelectQuery

java.lang.Object
  extended by org.apache.cayenne.query.AbstractQuery
      extended by org.apache.cayenne.query.QualifiedQuery
          extended by org.apache.cayenne.query.SelectQuery
All Implemented Interfaces:
java.io.Serializable, ConfigurationNode, ParameterizedQuery, Query, XMLSerializable
Direct Known Subclasses:
PrefetchSelectQuery

public class SelectQuery
extends QualifiedQuery
implements ParameterizedQuery, XMLSerializable

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
protected  boolean distinct
           
static boolean DISTINCT_DEFAULT
           
static java.lang.String DISTINCT_PROPERTY
           
protected  java.util.List<Ordering> orderings
           
 
Fields inherited from class org.apache.cayenne.query.QualifiedQuery
qualifier
 
Fields inherited from class org.apache.cayenne.query.AbstractQuery
dataMap, name, root
 
Constructor Summary
SelectQuery()
          Creates an empty SelectQuery.
SelectQuery(java.lang.Class<?> rootClass)
          Creates a SelectQuery that selects all objects of a given persistent class.
SelectQuery(java.lang.Class<?> rootClass, Expression qualifier)
          Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
SelectQuery(java.lang.Class<?> rootClass, Expression qualifier, java.util.List<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, java.util.List<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, java.util.List<Ordering> orderings)
          Creates a SelectQuery for the specified ObjEntity with the given qualifier and orderings.
SelectQuery(java.lang.String objEntityName)
          Creates SelectQuery with objEntityName parameter.
SelectQuery(java.lang.String objEntityName, Expression qualifier)
          Creates SelectQuery with objEntityName and qualifier parameters.
SelectQuery(java.lang.String objEntityName, Expression qualifier, java.util.List<Ordering> orderings)
          Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
 
Method Summary
 void addOrdering(Ordering ordering)
          Adds ordering specification to this query orderings.
 void addOrdering(java.lang.String sortPathSpec, SortOrder order)
          Adds ordering specification to this query orderings.
 void addOrderings(java.util.List<Ordering> orderings)
          Adds a list of orderings.
 PrefetchTreeNode addPrefetch(java.lang.String prefetchPath)
          Adds a prefetch with specified relationship path to the query.
 void aliasPathSplits(java.lang.String path, java.lang.String... aliases)
          Adds one or more aliases for the qualifier expression path.
 void clearOrderings()
          Clears all configured orderings.
 void clearPrefetches()
          Clears all stored prefetch paths.
 Query createQuery(java.util.Map<java.lang.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.
 void encodeAsXML(XMLEncoder encoder)
          Prints itself as XML to the provided PrintWriter.
 java.lang.String[] getCacheGroups()
           
 QueryCacheStrategy getCacheStrategy()
           
 int getFetchLimit()
          Returns the fetchLimit.
 int getFetchOffset()
          Returns the fetchOffset.
 QueryMetadata getMetaData(EntityResolver resolver)
          Returns default select parameters.
 java.util.List<Ordering> getOrderings()
          Returns a list of orderings used by this query.
 int getPageSize()
          Returns pageSize property.
 PrefetchTreeNode getPrefetchTree()
           
 int getStatementFetchSize()
           
 void initWithProperties(java.util.Map<java.lang.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.
 SelectQuery queryWithParameters(java.util.Map<java.lang.String,?> parameters)
          A shortcut for queryWithParameters(Map, boolean)that prunes parts of qualifier that have no parameter value set.
 SelectQuery queryWithParameters(java.util.Map<java.lang.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(java.lang.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(java.lang.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)
          Sets query result type.
 void setFetchLimit(int fetchLimit)
          Sets the fetchLimit.
 void setFetchOffset(int fetchOffset)
           
 void setPageSize(int pageSize)
          Sets pageSize property.
 void setPrefetchTree(PrefetchTreeNode prefetchTree)
           
 void setStatementFetchSize(int size)
          Sets statement's fetch size (0 for no default size)
 
Methods inherited from class org.apache.cayenne.query.QualifiedQuery
andQualifier, getQualifier, orQualifier, setQualifier
 
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 java.lang.String DISTINCT_PROPERTY
See Also:
Constant Field Values

DISTINCT_DEFAULT

public static final boolean DISTINCT_DEFAULT
See Also:
Constant Field Values

orderings

protected java.util.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,
                   java.util.List<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(java.lang.Class<?> 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(java.lang.Class<?> 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(java.lang.Class<?> rootClass,
                   Expression qualifier,
                   java.util.List<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,
                   java.util.List<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(java.lang.String objEntityName)
Creates SelectQuery with objEntityName parameter.


SelectQuery

public SelectQuery(java.lang.String objEntityName,
                   Expression qualifier)
Creates SelectQuery with objEntityName and qualifier parameters.


SelectQuery

public SelectQuery(java.lang.String objEntityName,
                   Expression qualifier,
                   java.util.List<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

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(java.util.Map<java.lang.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 queryWithParameters(java.util.Map<java.lang.String,?> parameters)
A shortcut for queryWithParameters(Map, boolean)that prunes parts of qualifier that have no parameter value set.


queryWithParameters

public SelectQuery queryWithParameters(java.util.Map<java.lang.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 Query createQuery(java.util.Map<java.lang.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(java.util.List<Ordering> orderings)
Adds a list of orderings.


addOrdering

public void addOrdering(java.lang.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 java.util.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(java.lang.String path,
                            java.lang.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 PrefetchTreeNode addPrefetch(java.lang.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(java.lang.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)
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 java.lang.String[] getCacheGroups()
Since:
3.0

setCacheGroups

public void setCacheGroups(java.lang.String... cacheGroups)
Since:
3.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 no default size)

Since:
3.0

getStatementFetchSize

public int getStatementFetchSize()
Returns:
statement's fetch size
Since:
3.0


Copyright © 2001-2012 Apache Cayenne. All Rights Reserved.