Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.objectstyle.cayenne.query
Class SelectQuery

    java.lang.Object
      org.objectstyle.cayenne.query.AbstractQuery
          org.objectstyle.cayenne.query.QualifiedQuery
              org.objectstyle.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.objectstyle.cayenne.query.QualifiedQuery
`qualifier`

Fields inherited from class org.objectstyle.cayenne.query.AbstractQuery
`name, root`

Fields inherited from interface org.objectstyle.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.objectstyle.cayenne.query.QualifiedQuery
`andQualifier, getQualifier, orQualifier, setQualifier`

Methods inherited from class org.objectstyle.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.objectstyle.cayenne.query.Query
`getName, getRoot, setName, setRoot`

Methods inherited from interface org.objectstyle.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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2006 ObjectStyle.org All Rights Reserved.