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

# Interface Select<T>

All Superinterfaces:
  `Query, Serializable`

All Known Implementing Classes:
  `ColumnSelect, FluentSelect, MappedSelect, ObjectSelect, PrefetchSelectQuery, SelectById, SQLSelect`

public interface Select<T> extends Query
A common interface for grouping together different kinds of queries that return results.

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

  ### Methods inherited from interface Query

  `createSQLAction, getMetaData, route`
  Modifier and Type
  Method
  Description
  `SQLAction`
  `createSQLAction(SQLActionVisitor visitor)`
  A callback method invoked by Cayenne during the final execution phase of the query run.
  `QueryMetadata`
  `getMetaData(EntityResolver resolver)`
  Returns query runtime parameters.
  `void`
  `route(QueryRouter router, EntityResolver resolver, Query substitutedQuery)`
  A callback method invoked by Cayenne during the routing phase of the query execution.

- ## Method Details

  - ### select

    List<T> select(ObjectContext context)
    Selects objects using provided context.

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

    Since:
      4.0

  - ### selectOne

    T selectOne(ObjectContext context)
    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)".

    Since:
      4.0

  - ### selectFirst

    T selectFirst(ObjectContext context)
    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 `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.

    Since:
      4.0

  - ### iterate

    void iterate(ObjectContext context, ResultIteratorCallback<T> callback)
    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)".

    Since:
      4.0

  - ### iterator

    ResultIterator<T> iterator(ObjectContext context)
    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 `iterate(ObjectContext, ResultIteratorCallback)` as an alternative.

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

    Since:
      4.0

  - ### batchIterator

    ResultBatchIterator<T> batchIterator(ObjectContext context, int size)
    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.
    Since:
      4.0