org.apache.cayenne.query
Class SelectQuery

java.lang.Object
  org.apache.cayenne.query.AbstractQuery
      org.apache.cayenne.query.QualifiedQuery
          org.apache.cayenne.query.SelectQuery

All Implemented Interfaces:

java.io.Serializable, GenericSelectQuery, ParameterizedQuery, Query, XMLSerializable

Direct Known Subclasses:

EOQuery, PrefetchSelectQuery

public class SelectQuery
extends QualifiedQuery
implements GenericSelectQuery, 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.

Author:

Andrei Adamchik

See Also:

Serialized Form

Field Summary

protected java.util.List	customDbAttributes
protected boolean	distinct
static boolean	DISTINCT_DEFAULT
static java.lang.String	DISTINCT_PROPERTY
protected java.util.List	orderings
protected java.lang.String	parentObjEntityName
protected Expression	parentQualifier

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

qualifier

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

name, root

Fields inherited from interface org.apache.cayenne.query.GenericSelectQuery

CACHE_POLICY_DEFAULT, CACHE_POLICY_PROPERTY, FETCH_LIMIT_DEFAULT, FETCH_LIMIT_PROPERTY, FETCHING_DATA_ROWS_DEFAULT, FETCHING_DATA_ROWS_PROPERTY, LOCAL_CACHE, NO_CACHE, PAGE_SIZE_DEFAULT, PAGE_SIZE_PROPERTY, REFRESHING_OBJECTS_DEFAULT, REFRESHING_OBJECTS_PROPERTY, RESOLVING_INHERITED_DEFAULT, RESOLVING_INHERITED_PROPERTY, SHARED_CACHE

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(DbEntity root)
Creates a SelectQuery for the specifed DbEntity.

SelectQuery(DbEntity root, Expression qualifier)
Creates a SelectQuery for the specifed DbEntity with the given qualifier.

SelectQuery(ObjEntity root)
Creates a SelectQuery with null qualifier, for the specifed ObjEntity

SelectQuery(ObjEntity root, Expression qualifier)
Creates a SelectQuery for the specifed ObjEntity with the given qualifier

SelectQuery(java.lang.String objEntityName)
Creates SelectQuery with objEntityName parameter.

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

Method Summary

void	addCustomDbAttribute(java.lang.String attributePath) Adds a path to the DbAttribute that should be included in the results of this query.
void	addCustomDbAttributes(java.util.List attrPaths)
void	addOrdering(Ordering ordering) Adds ordering specification to this query orderings.
void	addOrdering(java.lang.String sortPathSpec, boolean isAscending) Adds ordering specification to this query orderings.
void	addOrdering(java.lang.String sortPathSpec, boolean isAscending, boolean ignoreCase) Adds ordering specification to this query orderings.
void	addOrderings(java.util.List orderings) Adds a list of orderings.
PrefetchTreeNode	addPrefetch(java.lang.String prefetchPath) Adds a prefetch with specified relationship path to the query.
void	addPrefetches(java.util.Collection prefetches) Deprecated. since 1.2
void	andParentQualifier(Expression e) Adds specified parent entity qualifier to the existing parent entity qualifier joining it using "AND".
void	clearOrderings() Clears all configured orderings.
void	clearPrefetches() Clears all stored prefetch paths.
Query	createQuery(java.util.Map 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	getCachePolicy() Returns query cache policy, which can be one of GenericSelectQuery.NO_CACHE, GenericSelectQuery.LOCAL_CACHE, or GenericSelectQuery.SHARED_CACHE.
java.util.List	getCustomDbAttributes() Returns a list of attributes that will be included in the results of this query.
int	getFetchLimit() Returns the fetchLimit.
QueryMetadata	getMetaData(EntityResolver resolver) Returns default select parameters.
java.util.List	getOrderings() Returns a list of orderings used by this query.
int	getPageSize() Returns pageSize property.
java.lang.String	getParentObjEntityName() Returns the name of parent ObjEntity.
Expression	getParentQualifier() Getter for query parent entity qualifier.
java.util.Collection	getPrefetches() Deprecated. since 1.2 use 'getPrefetchTree' to explore prefetches.
PrefetchTreeNode	getPrefetchTree() Returns a root node of prefetch tree used by this query, or null of no prefetches are configured.
void	initWithProperties(java.util.Map properties) Initializes query parameters using a set of properties.
boolean	isDistinct() Returns true if this query returns distinct rows.
boolean	isFetchingCustomAttributes() Returns true if there is at least one custom query attribute specified, otherwise returns false for the case when the query results will contain only the root entity attributes.
boolean	isFetchingDataRows() Returns true if this query should produce a list of data rows as opposed to DataObjects, false for DataObjects.
boolean	isQualifiedOnParent() Returns true if this query has an extra qualifier that uses a parent entity of the query root entity for additional result filtering.
boolean	isRefreshingObjects() Returns refresh policy of this query.
boolean	isResolvingInherited() Returns true if objects fetched via this query should be fully resolved according to the inheritance hierarchy.
void	orParentQualifier(Expression e) Adds specified parent entity qualifier to the existing qualifier joining it using "OR".
SelectQuery	queryWithParameters(java.util.Map parameters) A shortcut for queryWithParameters(Map, boolean)that prunes parts of qualifier that have no parameter value set.
SelectQuery	queryWithParameters(java.util.Map 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	setCachePolicy(java.lang.String policy)
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	setPageSize(int pageSize) Sets pageSize property.
void	setParentObjEntityName(java.lang.String parentObjEntityName) Sets the name of parent ObjEntity.
void	setParentQualifier(Expression parentQualifier) Setter for query's parent entity qualifier.
void	setPrefetchTree(PrefetchTreeNode prefetchTree)
void	setRefreshingObjects(boolean flag)
void	setResolvingInherited(boolean b) Sets whether the objects fetched via this query should be fully resolved according to the inheritance hierarchy.

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

andQualifier, getQualifier, orQualifier, setQualifier

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

getName, getRoot, 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

getName, getRoot, setName, setRoot

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

getName, getRoot, setName, setRoot

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

customDbAttributes

protected java.util.List customDbAttributes

orderings

protected java.util.List orderings

distinct

protected boolean distinct

parentQualifier

protected Expression parentQualifier

parentObjEntityName

protected java.lang.String parentObjEntityName

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

SelectQuery

public SelectQuery(DbEntity root)

Creates a SelectQuery for the specifed DbEntity.

Parameters:

root - the DbEntity this SelectQuery is for.

Since:

1.1

SelectQuery

public SelectQuery(DbEntity root,
                   Expression qualifier)

Creates a SelectQuery for the specifed 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(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.

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 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 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 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 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 orderings)

Adds a list of orderings.

addOrdering

public void addOrdering(java.lang.String sortPathSpec,
                        boolean isAscending)

Adds ordering specification to this query orderings.

addOrdering

public void addOrdering(java.lang.String sortPathSpec,
                        boolean isAscending,
                        boolean ignoreCase)

Adds ordering specification to this query orderings.

removeOrdering

public void removeOrdering(Ordering ordering)

Removes ordering.

Since:

1.1

getOrderings

public java.util.List 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.

getCustomDbAttributes

public java.util.List getCustomDbAttributes()

Returns a list of attributes that will be included in the results of this query.

addCustomDbAttribute

public void addCustomDbAttribute(java.lang.String attributePath)

Adds a path to the DbAttribute that should be included in the results of this query. Valid paths would look like ARTIST_NAME, PAINTING_ARRAY.PAINTING_ID, etc.

addCustomDbAttributes

public void addCustomDbAttributes(java.util.List attrPaths)

isFetchingCustomAttributes

public boolean isFetchingCustomAttributes()

Returns true if there is at least one custom query attribute specified, otherwise returns false for the case when the query results will contain only the root entity attributes.

Note that queries that are fetching custom attributes always return data rows instead of DataObjects.

getPrefetches

public java.util.Collection getPrefetches()

Deprecated. since 1.2 use 'getPrefetchTree' to explore prefetches.

Returns a collection of String paths indicating relationships to objects that are prefetched together with this query.

getPrefetchTree

public PrefetchTreeNode getPrefetchTree()

Description copied from interface: GenericSelectQuery

Returns a root node of prefetch tree used by this query, or null of no prefetches are configured.

Specified by:

getPrefetchTree in interface GenericSelectQuery

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.

addPrefetches

public void addPrefetches(java.util.Collection prefetches)

Deprecated. since 1.2

Adds all prefetches to the internal prefetch set.

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.

Specified by:

isFetchingDataRows in interface GenericSelectQuery

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 isFetchingCustAttributes() returns true, this setting has no effect, and data rows are always fetched.

isRefreshingObjects

public boolean isRefreshingObjects()

Returns refresh policy of this query. Default is true.

Specified by:

isRefreshingObjects in interface GenericSelectQuery

Since:

1.1

setRefreshingObjects

public void setRefreshingObjects(boolean flag)

Since:

1.1

getCachePolicy

public java.lang.String getCachePolicy()

Description copied from interface: GenericSelectQuery

Returns query cache policy, which can be one of GenericSelectQuery.NO_CACHE, GenericSelectQuery.LOCAL_CACHE, or GenericSelectQuery.SHARED_CACHE. NO_CACHE is generally a default policy.

Specified by:

getCachePolicy in interface GenericSelectQuery

Since:

1.1

setCachePolicy

public void setCachePolicy(java.lang.String policy)

Since:

1.1

getFetchLimit

public int getFetchLimit()

Returns the fetchLimit.

Specified by:

getFetchLimit in interface GenericSelectQuery

Returns:

int

setFetchLimit

public void setFetchLimit(int fetchLimit)

Sets the fetchLimit.

Parameters:

fetchLimit - The fetchLimit to set

setParentQualifier

public void setParentQualifier(Expression parentQualifier)

Setter for query's parent entity qualifier.

getParentQualifier

public Expression getParentQualifier()

Getter for query parent entity qualifier.

andParentQualifier

public void andParentQualifier(Expression e)

Adds specified parent entity qualifier to the existing parent entity qualifier joining it using "AND".

orParentQualifier

public void orParentQualifier(Expression e)

Adds specified parent entity qualifier to the existing qualifier joining it using "OR".

getParentObjEntityName

public java.lang.String getParentObjEntityName()

Returns the name of parent ObjEntity.

Returns:

String

setParentObjEntityName

public void setParentObjEntityName(java.lang.String parentObjEntityName)

Sets the name of parent ObjEntity. If query's root ObjEntity maps to a derived entity in the DataMap, this query qualifier will resolve to a HAVING clause of an SQL statement. To allow fine tuning the query before applying GROUP BY and HAVING, callers can setup the name of parent ObjEntity and parent qualifier that will be used to create WHERE clause preceeding GROUP BY.

For instance this is helpful to qualify the fetch on a related entity attributes, since HAVING does not allow joins.

Parameters:

parentObjEntityName - The parentObjEntityName to set

isQualifiedOnParent

public boolean isQualifiedOnParent()

Returns true if this query has an extra qualifier that uses a parent entity of the query root entity for additional result filtering.

getPageSize

public int getPageSize()

Returns pageSize property. Page size is a hint telling Cayenne QueryEngine that query result should use paging instead of reading the whole result in the memory.

Specified by:

getPageSize in interface GenericSelectQuery

Returns:

int

setPageSize

public void setPageSize(int pageSize)

Sets pageSize property.

Parameters:

pageSize - The pageSize to set

isResolvingInherited

public boolean isResolvingInherited()

Returns true if objects fetched via this query should be fully resolved according to the inheritance hierarchy.

Specified by:

isResolvingInherited in interface GenericSelectQuery

Since:

1.1

setResolvingInherited

public void setResolvingInherited(boolean b)

Sets whether the objects fetched via this query should be fully resolved according to the inheritance hierarchy.

Since:

1.1