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:
    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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `distinct`
    `static boolean` | `DISTINCT_DEFAULT`
    `static String` | `DISTINCT_PROPERTY`
    `protected 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

    Constructors
    Constructor and Description
    `SelectQuery()` Creates an empty SelectQuery.
    `SelectQuery(Class<?> rootClass)` Creates a SelectQuery that selects all objects of a given persistent class.
    `SelectQuery(Class<?> rootClass, Expression qualifier)` Creates a SelectQuery that selects objects of a given persistent class that match supplied qualifier.
    `SelectQuery(Class<?> rootClass, Expression qualifier, 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, 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, List<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<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(List<Ordering> orderings)` Adds a list of orderings.
    `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` | `clearOrderings()` Clears all configured orderings.
    `void` | `clearPrefetches()` Clears all stored prefetch paths.
    `Query` | `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.
    `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()`
    `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.
    `SelectQuery` | `queryWithParameters(Map<String,?> parameters)` A shortcut for `queryWithParameters(Map, boolean)`that prunes parts of qualifier that have no parameter value set.
    `SelectQuery` | `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)` 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 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 String DISTINCT_PROPERTY

      See Also:
        Constant Field Values

    - #### DISTINCT_DEFAULT

          public static final boolean DISTINCT_DEFAULT

      See Also:
        Constant Field Values

    - #### 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<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<?> 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<?> 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<?> rootClass,
                     Expression qualifier,
                     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,
                     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(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<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(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 queryWithParameters(Map<String,?> parameters)

      A shortcut for `queryWithParameters(Map, boolean)`that prunes parts of qualifier that have no parameter value set.

    - #### queryWithParameters

          public SelectQuery 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 Query 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(List<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 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)

      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

    - #### 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

Copyright © 2001–2014 Apache Cayenne. All rights reserved.