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

# Class MappedSelect<T>

java.lang.Object
org.apache.cayenne.query.IndirectQuery
org.apache.cayenne.query.AbstractMappedQuery
org.apache.cayenne.query.MappedSelect<T>

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

public class MappedSelect<T> extends AbstractMappedQuery implements Select<T>
A query that represents a named parameterized selecting query stored in the mapping. The actual query is resolved during execution.

Since:
  4.0
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Integer`
  `fetchLimit`
  `protected Integer`
  `fetchOffset`
  `protected boolean`
  `forceNoCache`
  `protected Integer`
  `pageSize`
  `protected Integer`
  `queryTimeout`
  `protected Class<T>`
  `resultClass`
  `protected Integer`
  `statementFetchSize`

  ### Fields inherited from class AbstractMappedQuery

  `params, queryName`
  Modifier and Type
  Field
  Description
  `protected Map<String,Object>`
  `params`
  `protected String`
  `queryName`

  ### Fields inherited from class IndirectQuery

  `dataMap, lastResolver, name, replacementQuery`
  Modifier and Type
  Field
  Description
  `protected DataMap`
  `dataMap`
  `protected EntityResolver`
  `lastResolver`
  `protected String`
  `name`
  `protected Query`
  `replacementQuery`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `MappedSelect(String queryName)`
  `protected`
  `MappedSelect(String queryName, Class<T> resultClass)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ResultBatchIterator<T>`
  `batchIterator(ObjectContext context, int size)`
  Creates a ResultBatchIterator based on the provided context and batch size.
  `protected Query`
  `createReplacementQuery(EntityResolver resolver)`
  Creates a substitute query.
  `MappedSelect<T>`
  `forceNoCache()`
  Forces query cache to be refreshed during the execution of this query.
  `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.
  `MappedSelect<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.
  `MappedSelect<T>`
  `offset(int fetchOffset)`
  Resets query fetch offset - a parameter that defines how many objects should be skipped when reading data from the database.
  `MappedSelect<T>`
  `pageSize(int pageSize)`
  Resets query page size.
  `MappedSelect<T>`
  `param(String name, Object value)`
  `MappedSelect<T>`
  `params(Map<String,?> parameters)`
  `static MappedSelect<?>`
  `query(String queryName)`
  Loads query with the given name from the mapping configuration.
  `static <T> MappedSelect<T>`
  `query(String queryName, Class<T> rootClass)`
  Loads query with the given name, which selects objects of a given persistent class, from the mapping configuration.
  `MappedSelect<T>`
  `queryTimeout(int timeout)`
  Sets query timeout for the PreparedStatement generated for this query.
  `List<T>`
  `select(ObjectContext context)`
  Selects objects using provided context.
  `T`
  `selectFirst(ObjectContext context)`
  Selects a single object using provided context.
  `T`
  `selectOne(ObjectContext context)`
  Selects a single object using provided context.
  `MappedSelect<T>`
  `statementFetchSize(int statementFetchSize)`
  Sets fetch size of the PreparedStatement generated for this query.

  ### Methods inherited from class AbstractMappedQuery

  `name`
  Modifier and Type
  Method
  Description
  `AbstractMappedQuery`
  `name(String queryName)`

  ### Methods inherited from class IndirectQuery

  `createSQLAction, getMetaData, getReplacementQuery, route`
  Modifier and Type
  Method
  Description
  `SQLAction`
  `createSQLAction(SQLActionVisitor visitor)`
  Throws an exception as indirect query should not be executed directly.
  `QueryMetadata`
  `getMetaData(EntityResolver resolver)`
  Returns the metadata obtained from the replacement query.
  `protected Query`
  `getReplacementQuery(EntityResolver resolver)`
  Returns a replacement query, creating it on demand and caching it for reuse.
  `void`
  `route(QueryRouter router, EntityResolver resolver, Query substitutedQuery)`
  Delegates routing to a replacement query.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### resultClass

    protected Class<T> resultClass

  - ### fetchLimit

    protected Integer fetchLimit

  - ### fetchOffset

    protected Integer fetchOffset

  - ### statementFetchSize

    protected Integer statementFetchSize

  - ### queryTimeout

    protected Integer queryTimeout

  - ### pageSize

    protected Integer pageSize

  - ### forceNoCache

    protected boolean forceNoCache

- ## Constructor Details

  - ### MappedSelect

    protected MappedSelect(String queryName)

  - ### MappedSelect

    protected MappedSelect(String queryName, Class<T> resultClass)

- ## Method Details

  - ### query

    public static <T> MappedSelect<T> query(String queryName, Class<T> rootClass)
    Loads query with the given name, which selects objects of a given persistent class, from the mapping configuration.
    Parameters:
      `queryName` - name of the mapped query
      `rootClass` - the Class of objects fetched by this query

  - ### query

    public static MappedSelect<?> query(String queryName)
    Loads query with the given name from the mapping configuration.
    Parameters:
      `queryName` - name of the mapped query

  - ### limit

    public MappedSelect<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.

  - ### offset

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

  - ### statementFetchSize

    public MappedSelect<T> statementFetchSize(int statementFetchSize)
    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 MappedSelect<T> queryTimeout(int timeout)
    Sets query timeout for the PreparedStatement generated for this query.
    Since:
      4.2
    See Also:
      - `Statement.setQueryTimeout(int)`

  - ### pageSize

    public MappedSelect<T> 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.

  - ### forceNoCache

    public MappedSelect<T> forceNoCache()
    Forces query cache to be refreshed during the execution of this query.

  - ### params

    public MappedSelect<T> params(Map<String,?> parameters)
    Overrides:
      `params` in class `AbstractMappedQuery`

  - ### param

    public MappedSelect<T> param(String name, Object value)
    Overrides:
      `param` in class `AbstractMappedQuery`

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

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

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

  - ### createReplacementQuery

    protected Query createReplacementQuery(EntityResolver resolver)
    Description copied from class: `IndirectQuery`
    Creates a substitute query. An implementor is free to provide an arbitrary replacement query.
    Overrides:
      `createReplacementQuery` in class `AbstractMappedQuery`