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

# Class FluentSelect<T, S extends FluentSelect<T,S>>

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

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

Direct Known Subclasses:
  `ColumnSelect, ObjectSelect`

public abstract class FluentSelect<T, S extends FluentSelect<T,S>> extends AbstractQuery implements Select<T>
Base class for `ObjectSelect` and `ColumnSelect`

Since:
  4.0
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  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`
  `FluentSelect()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `S`
  `and(Collection<Expression> expressions)`
  AND's provided expressions to the existing WHERE clause expression.
  `S`
  `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.
  `S`
  `cacheGroup(String cacheGroup)`
  `S`
  `cacheStrategy(QueryCacheStrategy strategy)`
  `S`
  `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.
  `protected abstract org.apache.cayenne.query.ObjectSelectMetadata`
  `createMetadata()`
  `SQLAction`
  `createSQLAction(SQLActionVisitor visitor)`
  A callback method invoked by Cayenne during the final execution phase of the query run.
  `S`
  `dbEntityName(String dbEntityName)`
  Sets the `DbEntity` name to fetch without changing the return type of the query.
  `S`
  `entityName(String entityName)`
  Sets the `ObjEntity` name to fetch without changing the return type of the query.
  `S`
  `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 S`
  `joinExpression(Collection<Expression> expressions, Function<Collection<Expression>, Expression> joiner)`
  `S`
  `limit(int fetchLimit)`
  Resets query fetch limit - a parameter that defines max number of objects that should be ever be fetched from the database.
  `S`
  `localCache()`
  Instructs Cayenne to look for query results in the "local" cache when running the query.
  `S`
  `localCache(String cacheGroup)`
  Instructs Cayenne to look for query results in the "local" cache when running the query.
  `S`
  `offset(int fetchOffset)`
  Resets query fetch offset - a parameter that defines how many objects should be skipped when reading data from the database.
  `S`
  `or(Collection<Expression> expressions)`
  OR's provided expressions to the existing WHERE clause expression.
  `S`
  `or(Expression... expressions)`
  OR's provided expressions to the existing WHERE clause expression.
  `S`
  `orderBy(String property)`
  Add an ascending ordering on the given property.
  `S`
  `orderBy(String property, SortOrder sortOrder)`
  Add an ordering on the given property.
  `S`
  `orderBy(Collection<Ordering> orderings)`
  Adds a list of orderings to this query.
  `S`
  `orderBy(Ordering... orderings)`
  Add one or more orderings to this query.
  `S`
  `pageSize(int pageSize)`
  Resets query page size.
  `S`
  `prefetch(String path, int semantics)`
  Merges a prefetch path with specified semantics into the query prefetch tree.
  `S`
  `prefetch(PrefetchTreeNode prefetch)`
  Merges prefetch into the query prefetch tree.
  `S`
  `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)`
  `S`
  `sharedCache()`
  Instructs Cayenne to look for query results in the "shared" cache when running the query.
  `S`
  `sharedCache(String cacheGroup)`
  Instructs Cayenne to look for query results in the "shared" cache when running the query.
  `S`
  `statementFetchSize(int size)`
  Sets fetch size of the PreparedStatement generated for this query.
  `S`
  `where(String expressionString, Object... parameters)`
  Appends a qualifier expression of this query, using provided expression String and an array of position parameters.
  `S`
  `where(Expression expression)`
  Appends a qualifier expression of this query.

  ### Methods inherited from class AbstractQuery

  `getMetaData, getRoot, setRoot, toString`
  Modifier and Type
  Method
  Description
  `QueryMetadata`
  `getMetaData(EntityResolver resolver)`
  Returns default select parameters.
  `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

  `getBaseMetaData, getCacheGroup, getCacheStrategy, setCacheGroup, setCacheStrategy, useLocalCache, useLocalCache, useSharedCache, useSharedCache`
  Modifier and Type
  Method
  Description
  `protected abstract org.apache.cayenne.query.BaseQueryMetadata`
  `getBaseMetaData()`
  `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`

  ### Methods inherited from interface Select

  `selectFirst`
  Modifier and Type
  Method
  Description
  `T`
  `selectFirst(ObjectContext context)`
  Selects a single object using provided context.

- ## Field Details

  - ### entityType

    protected Class<?> entityType

  - ### entityName

    protected String entityName

  - ### dbEntityName

    protected String dbEntityName

  - ### where

    protected Expression where

  - ### having

    protected Expression having

  - ### havingExpressionIsActive

    protected boolean havingExpressionIsActive

  - ### orderings

    protected Collection<Ordering> orderings

  - ### distinct

    protected boolean distinct

  - ### metaData

    protected org.apache.cayenne.query.ObjectSelectMetadata metaData

- ## Constructor Details

  - ### FluentSelect

    protected FluentSelect()

- ## Method Details

  - ### createMetadata

    protected abstract org.apache.cayenne.query.ObjectSelectMetadata createMetadata()

  - ### resolveRoot

    protected Object resolveRoot(EntityResolver resolver)

  - ### entityType

    public S entityType(Class<?> entityType)
    Sets the type of the entity to fetch without changing the return type of the query.
    Returns:
      this object

  - ### entityName

    public S entityName(String entityName)
    Sets the `ObjEntity` name to fetch without changing the return type of the query. This form is most often used for generic entities that don't map to a distinct class.
    Returns:
      this object

  - ### dbEntityName

    public S dbEntityName(String dbEntityName)
    Sets the `DbEntity` name to fetch without changing the return type of the query. This form is most often used for generic entities that don't map to a distinct class.
    Returns:
      this object

  - ### where

    public S where(Expression expression)
    Appends a qualifier expression of this query. An equivalent to `and(Expression...)` that can be used a syntactic sugar.
    Returns:
      this object

  - ### where

    public S where(String expressionString, Object... parameters)
    Appends a 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

  - ### and

    public S and(Expression... expressions)
    AND's provided expressions to the existing WHERE clause expression.
    Returns:
      this object

  - ### and

    public S and(Collection<Expression> expressions)
    AND's provided expressions to the existing WHERE clause expression.
    Returns:
      this object

  - ### joinExpression

    protected S joinExpression(Collection<Expression> expressions, Function<Collection<Expression>, Expression> joiner)

  - ### or

    public S or(Expression... expressions)
    OR's provided expressions to the existing WHERE clause expression.
    Returns:
      this object

  - ### or

    public S or(Collection<Expression> expressions)
    OR's provided expressions to the existing WHERE clause expression.
    Returns:
      this object

  - ### orderBy

    public S orderBy(String property)
    Add an ascending ordering on the given property. If there is already an ordering on this query then add this ordering with a lower priority.
    Parameters:
      `property` - the property to sort on
    Returns:
      this object

  - ### orderBy

    public S orderBy(String property, SortOrder sortOrder)
    Add an ordering on the given property. If there is already an ordering on this query then add this ordering with a lower priority.
    Parameters:
      `property` - the property to sort on
      `sortOrder` - the direction of the ordering
    Returns:
      this object

  - ### orderBy

    public S orderBy(Ordering... orderings)
    Add one or more orderings to this query.
    Returns:
      this object

  - ### orderBy

    public S orderBy(Collection<Ordering> orderings)
    Adds a list of orderings to this query.
    Returns:
      this object

  - ### prefetch

    public S prefetch(PrefetchTreeNode prefetch)
    Merges prefetch into the query prefetch tree.
    Returns:
      this object

  - ### prefetch

    public S prefetch(String path, int semantics)
    Merges a prefetch path with specified semantics into the query prefetch tree.
    Returns:
      this object

  - ### limit

    public S limit(int fetchLimit)
    Resets query fetch limit - a parameter that defines max number of objects that should be ever be fetched from the database.

  - ### offset

    public S offset(int fetchOffset)
    Resets query fetch offset - a parameter that defines how many objects should be skipped when reading data from the database.

  - ### pageSize

    public S pageSize(int pageSize)
    Resets query page size. A non-negative page size enables query result pagination that saves memory and processing time for large lists if only parts of the result are ever going to be accessed.

  - ### statementFetchSize

    public S statementFetchSize(int size)
    Sets fetch size of the PreparedStatement generated for this query. Only non-negative values would change the default size.
    See Also:
      - `Statement.setFetchSize(int)`

  - ### queryTimeout

    public S queryTimeout(int timeout)
    Sets query timeout of PreparedStatement generated for this query.
    See Also:
      - `Statement.setQueryTimeout(int)`

  - ### cacheStrategy

    public S cacheStrategy(QueryCacheStrategy strategy)

  - ### cacheStrategy

    public S cacheStrategy(QueryCacheStrategy strategy, String cacheGroup)

  - ### cacheGroup

    public S cacheGroup(String cacheGroup)

  - ### localCache

    public S localCache(String cacheGroup)
    Instructs Cayenne to look for query results in the "local" cache when running the query. This is a short-hand notation for:

        query.cacheStrategy(QueryCacheStrategy.LOCAL_CACHE, cacheGroup);

  - ### localCache

    public S localCache()
    Instructs Cayenne to look for query results in the "local" cache when running the query. This is a short-hand notation for:

        query.cacheStrategy(QueryCacheStrategy.LOCAL_CACHE);

  - ### sharedCache

    public S sharedCache(String cacheGroup)
    Instructs Cayenne to look for query results in the "shared" cache when running the query. This is a short-hand notation for:

        query.cacheStrategy(QueryCacheStrategy.SHARED_CACHE, cacheGroup);

  - ### sharedCache

    public S sharedCache()
    Instructs Cayenne to look for query results in the "shared" cache when running the query. This is a short-hand notation for:

        query.cacheStrategy(QueryCacheStrategy.SHARED_CACHE);

  - ### getStatementFetchSize

    public int getStatementFetchSize()

  - ### getQueryTimeout

    public int getQueryTimeout()
    Since:
      4.2

  - ### getPageSize

    public int getPageSize()

  - ### getLimit

    public int getLimit()

  - ### getOffset

    public int getOffset()

  - ### getEntityType

    public Class<?> getEntityType()

  - ### getEntityName

    public String getEntityName()

  - ### getDbEntityName

    public String getDbEntityName()

  - ### getWhere

    public Expression getWhere()
    Returns a WHERE clause Expression of this query.

  - ### getHaving

    public Expression getHaving()
    Returns a HAVING clause Expression of this query.

  - ### getOrderings

    public Collection<Ordering> getOrderings()

  - ### getPrefetches

    public PrefetchTreeNode getPrefetches()

  - ### setActiveExpression

    protected void setActiveExpression(Expression exp)

  - ### getActiveExpression

    protected Expression getActiveExpression()

  - ### select

    public List<T> select(ObjectContext context)
    Description copied from interface: `Select`
    Selects objects using provided context.

    Essentially the inversion of "ObjectContext.select(Select)".

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

  - ### selectOne

    public T selectOne(ObjectContext context)
    Description copied from interface: `Select`
    Selects a single object using provided context. The query is expected to match zero or one object. It returns null if no objects were matched. If query matched more than one object, `CayenneRuntimeException` is thrown.

    Essentially the inversion of "ObjectContext.selectOne(Select)".

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

  - ### iterate

    public void iterate(ObjectContext context, ResultIteratorCallback<T> callback)
    Description copied from interface: `Select`
    Creates a ResultIterator based on the provided context and passes it to a callback for processing. The caller does not need to worry about closing the iterator. This method takes care of it.

    Essentially the inversion of "ObjectContext.iterate(Select, ResultIteratorCallback)".

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

  - ### iterator

    public ResultIterator<T> iterator(ObjectContext context)
    Description copied from interface: `Select`
    Creates a ResultIterator based on the provided context. It is usually backed by an open result set and is useful for processing of large data sets, preserving a constant memory footprint. The caller must wrap iteration in try/finally (or try-with-resources for Java 1.7 and higher) and close the ResultIterator explicitly. Or use `Select.iterate(ObjectContext, ResultIteratorCallback)` as an alternative.

    Essentially the inversion of "ObjectContext.iterator(Select)".

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

  - ### batchIterator

    public ResultBatchIterator<T> batchIterator(ObjectContext context, int size)
    Description copied from interface: `Select`
    Creates a ResultBatchIterator based on the provided context and batch size. It is usually backed by an open result set and is useful for processing of large data sets, preserving a constant memory footprint. The caller must wrap iteration in try/finally (or try-with-resources for Java 1.7 and higher) and close the ResultBatchIterator explicitly.
    Specified by:
      `batchIterator` in interface `Select<T>`

  - ### createSQLAction

    public SQLAction createSQLAction(SQLActionVisitor visitor)
    Description copied from interface: `Query`
    A callback method invoked by Cayenne during the final execution phase of the query run. A concrete query implementation is given a chance to decide how it should be handled. Implementors can pick an appropriate method of the SQLActionVisitor to handle itself, create a custom SQLAction of its own, or substitute itself with another query that should be used for SQLAction construction.
    Specified by:
      `createSQLAction` in interface `Query`
    Specified by:
      `createSQLAction` in class `AbstractQuery`

  - ### route

    public void route(QueryRouter router, EntityResolver resolver, Query substitutedQuery)
    Description copied from class: `AbstractQuery`
    Implements default routing mechanism relying on the EntityResolver to find DataMap based on the query root. This mechanism should be sufficient for most queries that "know" their root.
    Specified by:
      `route` in interface `Query`
    Overrides:
      `route` in class `AbstractQuery`

  - ### isFetchingDataRows

    public boolean isFetchingDataRows()

  - ### routePrefetches

    protected void routePrefetches(QueryRouter router, EntityResolver resolver)

  - ### getColumns

    public Collection<Property<?>> getColumns()
    Since:
      4.2

  - ### isDistinct

    public boolean isDistinct()
    Since:
      4.2

  - ### initWithProperties

    public void initWithProperties(Map<String,String> properties)
    Since:
      4.2

  - ### castSelf

    protected <E> E castSelf()
    Utility method to perform (re)cast this type, doesn't perform any checks, so use with caution.
    Type Parameters:
      `E` - type to cast to
    Returns:
      `this` casted to the type E
    Since:
      5.0