ObjectSelect (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne.query, class: ObjectSelect

# Class ObjectSelect<T>

java.lang.Object
org.apache.cayenne.query.CacheableQuery
org.apache.cayenne.query.AbstractQuery
org.apache.cayenne.query.FluentSelect<T, ObjectSelect<T>>
org.apache.cayenne.query.ObjectSelect<T>

All Implemented Interfaces:
  `Serializable, ParameterizedQuery, Query, Select<T>`

Direct Known Subclasses:
  `PrefetchSelectQuery`

public class ObjectSelect<T> extends FluentSelect<T, ObjectSelect<T>> implements ParameterizedQuery
A selecting query providing chainable API.

For example, the following is a convenient way to return a record:

    Artist a = ObjectSelect
         .query(Artist.class)
         .where(Artist.NAME.eq("Picasso"))
         .selectOne(context);

Since:
  4.0
See Also:
  - Serialized Form

- ## Field Summary

  ### Fields inherited from class FluentSelect

  `dbEntityName, distinct, entityName, entityType, having, havingExpressionIsActive, metaData, orderings, where`
  Modifier and Type
  Field
  Description
  `protected String`
  `dbEntityName`
  `protected boolean`
  `distinct`
  `protected String`
  `entityName`
  `protected Class<?>`
  `entityType`
  `protected Expression`
  `having`
  `protected boolean`
  `havingExpressionIsActive`
  `protected org.apache.cayenne.query.ObjectSelectMetadata`
  `metaData`
  `protected Collection<Ordering>`
  `orderings`
  `protected Expression`
  `where`

  ### Fields inherited from class AbstractQuery

  `root`
  Modifier and Type
  Field
  Description
  `protected Object`
  `root`
  The root object this query.

  ### Fields inherited from class CacheableQuery

  `logger`
  Modifier and Type
  Field
  Description
  `protected static final org.slf4j.Logger`
  `logger`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ObjectSelect()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<E> ColumnSelect<E>`
  `aggregate(BaseProperty<E> property, String function, Class<E> type)`
  Select result of some function, that aggregates values.
  `<E extends Number>
  ColumnSelect<E>`
  `avg(NumericProperty<E> property)`
  Select average value of property
  `<E> ColumnSelect<E>`
  `column(Property<E> property)`
  Select one specific property.
  `static ColumnSelect<Object[]>`
  `columnQuery(Class<?> entityType, Property<?>... columns)`
  Creates a ColumnSelect that will fetch multiple columns of a given `ObjEntity`
  `static <E> ColumnSelect<E>`
  `columnQuery(Class<?> entityType, Property<E> column)`
  Creates a ColumnSelect that will fetch single property that can be resolved against a given `ObjEntity` class.
  `ColumnSelect<Object[]>`
  `columns(Property<?>... properties)`
  Select only specific properties.
  `ColumnSelect<Long>`
  `count()`
  Select COUNT(*)
  `ColumnSelect<Long>`
  `count(BaseProperty<?> property)`
  Select COUNT(property)
  `protected org.apache.cayenne.query.ObjectSelectMetadata`
  `createMetadata()`
  `Query`
  `createQuery(Map<String,?> parameters)`
  This method is intended for internal use in a `MappedSelect`.
  `static ObjectSelect<DataRow>`
  `dataRowQuery(Class<?> entityType)`
  Creates a ObjectSelect that fetches data for an `ObjEntity` determined from a provided class.
  `static ObjectSelect<DataRow>`
  `dataRowQuery(Class<?> entityType, Expression expression)`
  Creates a ObjectSelect that fetches data for an `ObjEntity` determined from a provided class and uses provided expression for its qualifier.
  `static ObjectSelect<DataRow>`
  `dbQuery(String dbEntityName)`
  Creates a ObjectSelect that fetches DataRows for a `DbEntity` determined from provided "dbEntityName".
  `static ObjectSelect<DataRow>`
  `dbQuery(String dbEntityName, Expression expression)`
  Creates a ObjectSelect that fetches DataRows for a `DbEntity` determined from provided "dbEntityName" and uses provided expression for its qualifier.
  `ObjectSelect<T>`
  `distinct()`
  `ObjectSelect<DataRow>`
  `fetchDataRows()`
  Forces query to fetch DataRows.
  `protected org.apache.cayenne.query.ObjectSelectMetadata`
  `getBaseMetaData()`
  `QueryMetadata`
  `getMetaData(EntityResolver resolver)`
  Returns default select parameters.
  `ObjectSelect<T>`
  `having(String expressionString, Object... parameters)`
  Appends a having qualifier expression of this query, using provided expression String and an array of position parameters.
  `ObjectSelect<T>`
  `having(Expression expression)`
  Appends a having qualifier expression of this query.
  `<E> ColumnSelect<E>`
  `max(ComparableProperty<E> property)`
  Select maximum value of property
  `<E extends Number>
  ColumnSelect<E>`
  `max(NumericProperty<E> property)`
  Select maximum value of property
  `<E> ColumnSelect<E>`
  `min(ComparableProperty<E> property)`
  Select minimum value of property
  `<E extends Number>
  ColumnSelect<E>`
  `min(NumericProperty<E> property)`
  Select minimum value of property
  `static <T> ObjectSelect<T>`
  `query(Class<T> entityType)`
  Creates a ObjectSelect that selects objects of a given persistent class.
  `static <T> ObjectSelect<T>`
  `query(Class<T> resultType, String entityName)`
  Creates a ObjectSelect that fetches data for `ObjEntity` determined from provided "entityName", but fetches the result of a provided type.
  `static <T> ObjectSelect<T>`
  `query(Class<T> entityType, Expression expression)`
  Creates a ObjectSelect that selects objects of a given persistent class and uses provided expression for its qualifier.
  `static <T> ObjectSelect<T>`
  `query(Class<T> entityType, Expression expression, List<Ordering> orderings)`
  Creates a ObjectSelect that selects objects of a given persistent class and uses provided expression for its qualifier.
  `long`
  `selectCount(ObjectContext context)`
  Quick way to select count of records
  `T`
  `selectFirst(ObjectContext context)`
  Selects a single object using provided context.
  `<E extends Number>
  ColumnSelect<E>`
  `sum(NumericProperty<E> property)`
  Select sum of values

  ### Methods inherited from class FluentSelect

  `and, and, batchIterator, cacheGroup, cacheStrategy, cacheStrategy, castSelf, createSQLAction, dbEntityName, entityName, entityType, getActiveExpression, getColumns, getDbEntityName, getEntityName, getEntityType, getHaving, getLimit, getOffset, getOrderings, getPageSize, getPrefetches, getQueryTimeout, getStatementFetchSize, getWhere, initWithProperties, isDistinct, isFetchingDataRows, iterate, iterator, joinExpression, limit, localCache, localCache, offset, or, or, orderBy, orderBy, orderBy, orderBy, pageSize, prefetch, prefetch, queryTimeout, resolveRoot, route, routePrefetches, select, selectOne, setActiveExpression, sharedCache, sharedCache, statementFetchSize, where, where`
  Modifier and Type
  Method
  Description
  `ObjectSelect<T>`
  `and(Collection<Expression> expressions)`
  AND's provided expressions to the existing WHERE clause expression.
  `ObjectSelect<T>`
  `and(Expression... expressions)`
  AND's provided expressions to the existing WHERE clause expression.
  `ResultBatchIterator<T>`
  `batchIterator(ObjectContext context, int size)`
  Creates a ResultBatchIterator based on the provided context and batch size.
  `ObjectSelect<T>`
  `cacheGroup(String cacheGroup)`
  `ObjectSelect<T>`
  `cacheStrategy(QueryCacheStrategy strategy)`
  `ObjectSelect<T>`
  `cacheStrategy(QueryCacheStrategy strategy, String cacheGroup)`
  `protected <E> E`
  `castSelf()`
  Utility method to perform (re)cast this type, doesn't perform any checks, so use with caution.
  `SQLAction`
  `createSQLAction(SQLActionVisitor visitor)`
  A callback method invoked by Cayenne during the final execution phase of the query run.
  `ObjectSelect<T>`
  `dbEntityName(String dbEntityName)`
  Sets the `DbEntity` name to fetch without changing the return type of the query.
  `ObjectSelect<T>`
  `entityName(String entityName)`
  Sets the `ObjEntity` name to fetch without changing the return type of the query.
  `ObjectSelect<T>`
  `entityType(Class<?> entityType)`
  Sets the type of the entity to fetch without changing the return type of the query.
  `protected Expression`
  `getActiveExpression()`
  `Collection<Property<?>>`
  `getColumns()`
  `String`
  `getDbEntityName()`
  `String`
  `getEntityName()`
  `Class<?>`
  `getEntityType()`
  `Expression`
  `getHaving()`
  Returns a HAVING clause Expression of this query.
  `int`
  `getLimit()`
  `int`
  `getOffset()`
  `Collection<Ordering>`
  `getOrderings()`
  `int`
  `getPageSize()`
  `PrefetchTreeNode`
  `getPrefetches()`
  `int`
  `getQueryTimeout()`
  `int`
  `getStatementFetchSize()`
  `Expression`
  `getWhere()`
  Returns a WHERE clause Expression of this query.
  `void`
  `initWithProperties(Map<String,String> properties)`
  `boolean`
  `isDistinct()`
  `boolean`
  `isFetchingDataRows()`
  `void`
  `iterate(ObjectContext context, ResultIteratorCallback<T> callback)`
  Creates a ResultIterator based on the provided context and passes it to a callback for processing.
  `ResultIterator<T>`
  `iterator(ObjectContext context)`
  Creates a ResultIterator based on the provided context.
  `protected ObjectSelect<T>`
  `joinExpression(Collection<Expression> expressions, Function<Collection<Expression>, Expression> joiner)`
  `ObjectSelect<T>`
  `limit(int fetchLimit)`
  Resets query fetch limit - a parameter that defines max number of objects that should be ever be fetched from the database.
  `ObjectSelect<T>`
  `localCache()`
  Instructs Cayenne to look for query results in the "local" cache when running the query.
  `ObjectSelect<T>`
  `localCache(String cacheGroup)`
  Instructs Cayenne to look for query results in the "local" cache when running the query.
  `ObjectSelect<T>`
  `offset(int fetchOffset)`
  Resets query fetch offset - a parameter that defines how many objects should be skipped when reading data from the database.
  `ObjectSelect<T>`
  `or(Collection<Expression> expressions)`
  OR's provided expressions to the existing WHERE clause expression.
  `ObjectSelect<T>`
  `or(Expression... expressions)`
  OR's provided expressions to the existing WHERE clause expression.
  `ObjectSelect<T>`
  `orderBy(String property)`
  Add an ascending ordering on the given property.
  `ObjectSelect<T>`
  `orderBy(String property, SortOrder sortOrder)`
  Add an ordering on the given property.
  `ObjectSelect<T>`
  `orderBy(Collection<Ordering> orderings)`
  Adds a list of orderings to this query.
  `ObjectSelect<T>`
  `orderBy(Ordering... orderings)`
  Add one or more orderings to this query.
  `ObjectSelect<T>`
  `pageSize(int pageSize)`
  Resets query page size.
  `ObjectSelect<T>`
  `prefetch(String path, int semantics)`
  Merges a prefetch path with specified semantics into the query prefetch tree.
  `ObjectSelect<T>`
  `prefetch(PrefetchTreeNode prefetch)`
  Merges prefetch into the query prefetch tree.
  `ObjectSelect<T>`
  `queryTimeout(int timeout)`
  Sets query timeout of PreparedStatement generated for this query.
  `protected Object`
  `resolveRoot(EntityResolver resolver)`
  `void`
  `route(QueryRouter router, EntityResolver resolver, Query substitutedQuery)`
  Implements default routing mechanism relying on the EntityResolver to find DataMap based on the query root.
  `protected void`
  `routePrefetches(QueryRouter router, EntityResolver resolver)`
  `List<T>`
  `select(ObjectContext context)`
  Selects objects using provided context.
  `T`
  `selectOne(ObjectContext context)`
  Selects a single object using provided context.
  `protected void`
  `setActiveExpression(Expression exp)`
  `ObjectSelect<T>`
  `sharedCache()`
  Instructs Cayenne to look for query results in the "shared" cache when running the query.
  `ObjectSelect<T>`
  `sharedCache(String cacheGroup)`
  Instructs Cayenne to look for query results in the "shared" cache when running the query.
  `ObjectSelect<T>`
  `statementFetchSize(int size)`
  Sets fetch size of the PreparedStatement generated for this query.
  `ObjectSelect<T>`
  `where(String expressionString, Object... parameters)`
  Appends a qualifier expression of this query, using provided expression String and an array of position parameters.
  `ObjectSelect<T>`
  `where(Expression expression)`
  Appends a qualifier expression of this query.

  ### Methods inherited from class AbstractQuery

  `getRoot, setRoot, toString`
  Modifier and Type
  Method
  Description
  `Object`
  `getRoot()`
  Returns the root of this query.
  `void`
  `setRoot(Object value)`
  Sets the root of the query
  `String`
  `toString()`

  ### Methods inherited from class CacheableQuery

  `getCacheGroup, getCacheStrategy, setCacheGroup, setCacheStrategy, useLocalCache, useLocalCache, useSharedCache, useSharedCache`
  Modifier and Type
  Method
  Description
  `String`
  `getCacheGroup()`
  `QueryCacheStrategy`
  `getCacheStrategy()`
  `void`
  `setCacheGroup(String cacheGroup)`
  `void`
  `setCacheStrategy(QueryCacheStrategy strategy)`
  `void`
  `useLocalCache()`
  Instructs Cayenne to look for query results in the "local" cache when running the query.
  `void`
  `useLocalCache(String cacheGroup)`
  Instructs Cayenne to look for query results in the "local" cache when running the query.
  `void`
  `useSharedCache()`
  Instructs Cayenne to look for query results in the "shared" cache when running the query.
  `void`
  `useSharedCache(String cacheGroup)`
  Instructs Cayenne to look for query results in the "shared" cache when running the query.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### ObjectSelect

    protected ObjectSelect()

- ## Method Details

  - ### query

    public static <T> ObjectSelect<T> query(Class<T> entityType)
    Creates a ObjectSelect that selects objects of a given persistent class.

  - ### query

    public static <T> ObjectSelect<T> query(Class<T> entityType, Expression expression)
    Creates a ObjectSelect that selects objects of a given persistent class and uses provided expression for its qualifier.

  - ### query

    public static <T> ObjectSelect<T> query(Class<T> entityType, Expression expression, List<Ordering> orderings)
    Creates a ObjectSelect that selects objects of a given persistent class and uses provided expression for its qualifier.

  - ### dataRowQuery

    public static ObjectSelect<DataRow> dataRowQuery(Class<?> entityType)
    Creates a ObjectSelect that fetches data for an `ObjEntity` determined from a provided class.

  - ### dataRowQuery

    public static ObjectSelect<DataRow> dataRowQuery(Class<?> entityType, Expression expression)
    Creates a ObjectSelect that fetches data for an `ObjEntity` determined from a provided class and uses provided expression for its qualifier.

  - ### query

    public static <T> ObjectSelect<T> query(Class<T> resultType, String entityName)
    Creates a ObjectSelect that fetches data for `ObjEntity` determined from provided "entityName", but fetches the result of a provided type. This factory method is most often used with generic classes that by themselves are not enough to resolve the entity to fetch.

  - ### dbQuery

    public static ObjectSelect<DataRow> dbQuery(String dbEntityName)
    Creates a ObjectSelect that fetches DataRows for a `DbEntity` determined from provided "dbEntityName".

  - ### dbQuery

    public static ObjectSelect<DataRow> dbQuery(String dbEntityName, Expression expression)
    Creates a ObjectSelect that fetches DataRows for a `DbEntity` determined from provided "dbEntityName" and uses provided expression for its qualifier.
    Returns:
      this object

  - ### columnQuery

    public static <E> ColumnSelect<E> columnQuery(Class<?> entityType, Property<E> column)
    Creates a ColumnSelect that will fetch single property that can be resolved against a given `ObjEntity` class.
    Parameters:
      `entityType` - base persistent class that will be used as a root for this query
      `column` - single column to select

  - ### columnQuery

    public static ColumnSelect<Object[]> columnQuery(Class<?> entityType, Property<?>... columns)
    Creates a ColumnSelect that will fetch multiple columns of a given `ObjEntity`
    Parameters:
      `entityType` - base persistent class that will be used as a root for this query
      `columns` - columns to select

  - ### createMetadata

    protected org.apache.cayenne.query.ObjectSelectMetadata createMetadata()
    Specified by:
      `createMetadata` in class `FluentSelect<T, ObjectSelect<T>>`

  - ### having

    public ObjectSelect<T> having(Expression expression)
    Appends a having qualifier expression of this query. An equivalent to `FluentSelect.and(Expression...)` that can be used a syntactic sugar.
    Returns:
      this object
    Since:
      4.2

  - ### having

    public ObjectSelect<T> having(String expressionString, Object... parameters)
    Appends a having qualifier expression of this query, using provided expression String and an array of position parameters. This is an equivalent to calling "and".
    Returns:
      this object
    Since:
      4.2

  - ### fetchDataRows

    public ObjectSelect<DataRow> fetchDataRows()
    Forces query to fetch DataRows. This automatically changes whatever result type was set previously to "DataRow".
    Returns:
      this object

  - ### columns

    public ColumnSelect<Object[]> columns(Property<?>... properties)

    Select only specific properties.

    Can be any properties that can be resolved against root entity type (root entity's properties, function call expressions, properties of relationships, etc).

        List<Object[]> columns = ObjectSelect.query(Artist.class)
                                           .columns(Artist.ARTIST_NAME, Artist.DATE_OF_BIRTH)
                                           .select(context);

    Parameters:
      `properties` - array of properties to select
    See Also:
      - `column(Property)`

  - ### column

    public <E> ColumnSelect<E> column(Property<E> property)

    Select one specific property.

    Can be any property that can be resolved against root entity type (root entity's property, function call expression, property of relationships, etc)

    If you need several columns use `columns(Property[])` method.

        List<String> names = ObjectSelect.query(Artist.class)
                                         .column(Artist.ARTIST_NAME)
                                         .select(context);

    Parameters:
      `property` - single property to select
    See Also:
      - `columns(Property[])`

  - ### count

    public ColumnSelect<Long> count()
    Select COUNT(*)
    See Also:
      - `column(Property)`

  - ### count

    public ColumnSelect<Long> count(BaseProperty<?> property)

    Select COUNT(property)

    Can return different result than COUNT(*) as it will count only non null values

    See Also:
      - `count()`
      - `column(Property)`

  - ### min

    public <E> ColumnSelect<E> min(ComparableProperty<E> property)

    Select minimum value of property

    See Also:
      - `column(Property)`

  - ### min

    public <E extends Number> ColumnSelect<E> min(NumericProperty<E> property)

    Select minimum value of property

    See Also:
      - `column(Property)`

  - ### max

    public <E> ColumnSelect<E> max(ComparableProperty<E> property)

    Select maximum value of property

    See Also:
      - `column(Property)`

  - ### max

    public <E extends Number> ColumnSelect<E> max(NumericProperty<E> property)

    Select maximum value of property

    See Also:
      - `column(Property)`

  - ### avg

    public <E extends Number> ColumnSelect<E> avg(NumericProperty<E> property)

    Select average value of property

    See Also:
      - `column(Property)`

  - ### sum

    public <E extends Number> ColumnSelect<E> sum(NumericProperty<E> property)

    Select sum of values

    See Also:
      - `column(Property)`

  - ### aggregate

    public <E> ColumnSelect<E> aggregate(BaseProperty<E> property, String function, Class<E> type)

    Select result of some function, that aggregates values.

    Since:
      5.0
    See Also:
      - `column(Property)`

  - ### distinct

    public ObjectSelect<T> distinct()
    Returns:
      this
    Since:
      4.2

  - ### selectCount

    public long selectCount(ObjectContext context)

    Quick way to select count of records

    Usage:

            long count = ObjectSelect.query(Artist.class)
                             .where(Artist.ARTIST_NAME.like("a%"))
                             .selectCount(context);

    Parameters:
      `context` - to perform query
    Returns:
      count of rows

  - ### selectFirst

    public T selectFirst(ObjectContext context)
    Description copied from interface: `Select`
    Selects a single object using provided context. The query itself can match any number of objects, but will return only the first one. It returns null if no objects were matched.

    If it matched more than one object, the first object from the list is returned. This makes 'selectFirst' different from `Select.selectOne(ObjectContext)`, which would throw in this situation. 'selectFirst' is useful e.g. when the query is ordered and we only want to see the first object (e.g. "most recent news article"), etc.

    Selecting the first object via "Select.selectFirst(ObjectContext)" is more comprehensible than selecting via "ObjectContext.selectFirst(Select)", because implementations of "Select" set fetch size limit to one.

    Specified by:
      `selectFirst` in interface `Select<T>`

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

  - ### getBaseMetaData

    protected org.apache.cayenne.query.ObjectSelectMetadata getBaseMetaData()
    Specified by:
      `getBaseMetaData` in class `CacheableQuery`

  - ### createQuery

    public Query createQuery(Map<String,?> parameters)
    This method is intended for internal use in a `MappedSelect`.
    Specified by:
      `createQuery` in interface `ParameterizedQuery`
    Parameters:
      `parameters` - to apply
    Returns:
      this query with parameters applied to the where qualifier
    Since:
      4.2