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

# Class SelectById<T>

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

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

public class SelectById<T> extends IndirectQuery implements Select<T>
A query to select objects by id.

Since:
  4.0
See Also:
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static interface`
  `SelectById.IdSpec`
  `protected static class`
  `SelectById.MultiMapIdSpec`
  `protected static class`
  `SelectById.MultiScalarIdSpec`
  `protected static interface`
  `SelectById.QueryRoot`
  `protected static class`
  `SelectById.SingleMapIdSpec`
  `protected static class`
  `SelectById.SingleScalarIdSpec`

- ## Field Summary

  ### 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`
  `SelectById(SelectById.QueryRoot root, SelectById.IdSpec idSpec)`
  `protected`
  `SelectById(SelectById.QueryRoot root, SelectById.IdSpec idSpec, boolean fetchingDataRows)`

- ## 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.
  `SelectById<T>`
  `cacheGroup(String cacheGroup)`
  `SelectById<T>`
  `cacheStrategy(QueryCacheStrategy strategy)`
  `SelectById<T>`
  `cacheStrategy(QueryCacheStrategy strategy, String cacheGroup)`
  `protected Query`
  `createReplacementQuery(EntityResolver resolver)`
  Creates a substitute query.
  `static SelectById<DataRow>`
  `dataRowQuery(Class<?> entityType, Object id)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `dataRowQueryId(Class, Object)`
  `static SelectById<DataRow>`
  `dataRowQuery(Class<?> entityType, Object firstId, Object... otherIds)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `dataRowQueryIds(Class, Object...)`
  `static SelectById<DataRow>`
  `dataRowQuery(Class<?> entityType, Map<String,?> id)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `dataRowQueryMap(Class, Map)`
  `static SelectById<DataRow>`
  `dataRowQuery(Class<?> entityType, Map<String,?> firstId, Map<String,?>... otherIds)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `dataRowQueryMaps(Class, Map[])`
  `static SelectById<DataRow>`
  `dataRowQuery(ObjectId id)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `dataRowQueryObjectId(ObjectId)`
  `static SelectById<DataRow>`
  `dataRowQuery(ObjectId firstId, ObjectId... otherIds)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `dataRowQueryObjectIds(ObjectId...)`
  `static SelectById<DataRow>`
  `dataRowQueryId(Class<?> entityType, Object id)`
  `static SelectById<DataRow>`
  `dataRowQueryIds(Class<?> entityType, Object... ids)`
  `static SelectById<DataRow>`
  `dataRowQueryIdsCollection(Class<?> entityType, Collection<Object> ids)`
  `static SelectById<DataRow>`
  `dataRowQueryMap(Class<?> entityType, Map<String,?> id)`
  `static SelectById<DataRow>`
  `dataRowQueryMaps(Class<?> entityType, Map<String,?>... ids)`
  `static SelectById<DataRow>`
  `dataRowQueryMapsCollection(Class<?> entityType, Collection<Map<String,?>> ids)`
  `static SelectById<DataRow>`
  `dataRowQueryObjectId(ObjectId id)`
  `static SelectById<DataRow>`
  `dataRowQueryObjectIds(ObjectId... ids)`
  `static SelectById<DataRow>`
  `dataRowQueryObjectIdsCollection(Collection<ObjectId> ids)`
  `String`
  `getCacheGroup()`
  `QueryCacheStrategy`
  `getCacheStrategy()`
  `PrefetchTreeNode`
  `getPrefetches()`
  `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.
  `SelectById<T>`
  `localCache()`
  Instructs Cayenne to look for query results in the "local" cache when running the query.
  `SelectById<T>`
  `localCache(String cacheGroup)`
  Instructs Cayenne to look for query results in the "local" cache when running the query.
  `SelectById<T>`
  `prefetch(String path, int semantics)`
  Merges a prefetch path with specified semantics into the query prefetch tree.
  `SelectById<T>`
  `prefetch(PrefetchTreeNode prefetch)`
  Merges prefetch into the query prefetch tree.
  `static <T> SelectById<T>`
  `query(Class<T> entityType, Object id)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `queryId(Class, Object)`
  `static <T> SelectById<T>`
  `query(Class<T> entityType, Object firstId, Object... otherIds)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `queryIds(Class, Object...)`
  `static <T> SelectById<T>`
  `query(Class<T> entityType, Collection<Object> ids)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `queryIdsCollection(Class, Collection)`
  `static <T> SelectById<T>`
  `query(Class<T> entityType, Map<String,?> id)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `queryMap(Class, Map)`
  `static <T> SelectById<T>`
  `query(Class<T> entityType, Map<String,?> firstId, Map<String,?>... otherIds)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `queryMaps(Class, Map[])`
  `static <T> SelectById<T>`
  `query(Class<T> entityType, ObjectId id)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `queryObjectId(Class, ObjectId)`
  `static <T> SelectById<T>`
  `query(Class<T> entityType, ObjectId firstId, ObjectId... otherIds)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  since 5.0, use `queryObjectIds(Class, ObjectId...)`
  `static <T> SelectById<T>`
  `queryId(Class<T> entityType, Object id)`
  `static <T> SelectById<T>`
  `queryIds(Class<T> entityType, Object... ids)`
  `static <T> SelectById<T>`
  `queryIdsCollection(Class<T> entityType, Collection<Object> ids)`
  `static <T> SelectById<T>`
  `queryMap(Class<T> entityType, Map<String,?> id)`
  `static <T> SelectById<T>`
  `queryMaps(Class<T> entityType, Map<String,?>... ids)`
  `static <T> SelectById<T>`
  `queryMapsCollection(Class<T> entityType, Collection<Map<String,?>> ids)`
  `static <T> SelectById<T>`
  `queryObjectId(Class<T> entityType, ObjectId id)`
  `static <T> SelectById<T>`
  `queryObjectIds(Class<T> entityType, ObjectId... ids)`
  `static <T> SelectById<T>`
  `queryObjectIdsCollection(Class<T> entityType, Collection<ObjectId> ids)`
  `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.
  `SelectById<T>`
  `sharedCache()`
  Instructs Cayenne to look for query results in the "shared" cache when running the query.
  `SelectById<T>`
  `sharedCache(String cacheGroup)`
  Instructs Cayenne to look for query results in the "shared" cache when running the query.

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

- ## Constructor Details

  - ### SelectById

    protected SelectById(SelectById.QueryRoot root, SelectById.IdSpec idSpec, boolean fetchingDataRows)

  - ### SelectById

    protected SelectById(SelectById.QueryRoot root, SelectById.IdSpec idSpec)

- ## Method Details

  - ### queryId

    public static <T> SelectById<T> queryId(Class<T> entityType, Object id)
    Since:
      5.0

  - ### queryMap

    public static <T> SelectById<T> queryMap(Class<T> entityType, Map<String,?> id)
    Since:
      5.0

  - ### queryObjectId

    public static <T> SelectById<T> queryObjectId(Class<T> entityType, ObjectId id)
    Since:
      5.0

  - ### queryIds

    public static <T> SelectById<T> queryIds(Class<T> entityType, Object... ids)
    Since:
      5.0

  - ### queryIdsCollection

    public static <T> SelectById<T> queryIdsCollection(Class<T> entityType, Collection<Object> ids)
    Since:
      5.0

  - ### queryMaps

    @SafeVarargs public static <T> SelectById<T> queryMaps(Class<T> entityType, Map<String,?>... ids)
    Since:
      5.0

  - ### queryMapsCollection

    public static <T> SelectById<T> queryMapsCollection(Class<T> entityType, Collection<Map<String,?>> ids)
    Since:
      5.0

  - ### queryObjectIds

    public static <T> SelectById<T> queryObjectIds(Class<T> entityType, ObjectId... ids)
    Since:
      5.0

  - ### queryObjectIdsCollection

    public static <T> SelectById<T> queryObjectIdsCollection(Class<T> entityType, Collection<ObjectId> ids)
    Since:
      5.0

  - ### query

    @Deprecated(since="5.0", forRemoval=true) public static <T> SelectById<T> query(Class<T> entityType, Object id)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `queryId(Class, Object)`
    Since:
      4.2

  - ### query

    @Deprecated(since="5.0", forRemoval=true) public static <T> SelectById<T> query(Class<T> entityType, Map<String,?> id)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `queryMap(Class, Map)`
    Since:
      4.2

  - ### query

    @Deprecated(since="5.0", forRemoval=true) public static <T> SelectById<T> query(Class<T> entityType, ObjectId id)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `queryObjectId(Class, ObjectId)`
    Since:
      4.2

  - ### query

    @Deprecated(since="5.0", forRemoval=true) public static <T> SelectById<T> query(Class<T> entityType, Object firstId, Object... otherIds)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `queryIds(Class, Object...)`
    Since:
      4.2

  - ### query

    @Deprecated(since="5.0", forRemoval=true) public static <T> SelectById<T> query(Class<T> entityType, Collection<Object> ids)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `queryIdsCollection(Class, Collection)`
    Since:
      4.2

  - ### query

    @Deprecated(since="5.0", forRemoval=true) @SafeVarargs public static <T> SelectById<T> query(Class<T> entityType, Map<String,?> firstId, Map<String,?>... otherIds)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `queryMaps(Class, Map[])`
    Since:
      4.2

  - ### query

    @Deprecated(since="5.0", forRemoval=true) public static <T> SelectById<T> query(Class<T> entityType, ObjectId firstId, ObjectId... otherIds)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `queryObjectIds(Class, ObjectId...)`
    Since:
      4.2

  - ### dataRowQueryId

    public static SelectById<DataRow> dataRowQueryId(Class<?> entityType, Object id)
    Since:
      5.0

  - ### dataRowQueryMap

    public static SelectById<DataRow> dataRowQueryMap(Class<?> entityType, Map<String,?> id)
    Since:
      5.0

  - ### dataRowQueryObjectId

    public static SelectById<DataRow> dataRowQueryObjectId(ObjectId id)
    Since:
      5.0

  - ### dataRowQueryIds

    public static SelectById<DataRow> dataRowQueryIds(Class<?> entityType, Object... ids)
    Since:
      5.0

  - ### dataRowQueryIdsCollection

    public static SelectById<DataRow> dataRowQueryIdsCollection(Class<?> entityType, Collection<Object> ids)
    Since:
      5.0

  - ### dataRowQueryMaps

    @SafeVarargs public static SelectById<DataRow> dataRowQueryMaps(Class<?> entityType, Map<String,?>... ids)
    Since:
      5.0

  - ### dataRowQueryMapsCollection

    public static SelectById<DataRow> dataRowQueryMapsCollection(Class<?> entityType, Collection<Map<String,?>> ids)
    Since:
      5.0

  - ### dataRowQueryObjectIds

    public static SelectById<DataRow> dataRowQueryObjectIds(ObjectId... ids)
    Since:
      5.0

  - ### dataRowQueryObjectIdsCollection

    public static SelectById<DataRow> dataRowQueryObjectIdsCollection(Collection<ObjectId> ids)
    Since:
      5.0

  - ### dataRowQuery

    @Deprecated(since="5.0", forRemoval=true) public static SelectById<DataRow> dataRowQuery(Class<?> entityType, Object id)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `dataRowQueryId(Class, Object)`

  - ### dataRowQuery

    @Deprecated(since="5.0", forRemoval=true) public static SelectById<DataRow> dataRowQuery(Class<?> entityType, Map<String,?> id)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `dataRowQueryMap(Class, Map)`

  - ### dataRowQuery

    @Deprecated(since="5.0", forRemoval=true) public static SelectById<DataRow> dataRowQuery(ObjectId id)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `dataRowQueryObjectId(ObjectId)`

  - ### dataRowQuery

    @Deprecated(since="5.0", forRemoval=true) public static SelectById<DataRow> dataRowQuery(Class<?> entityType, Object firstId, Object... otherIds)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `dataRowQueryIds(Class, Object...)`
    Since:
      4.2

  - ### dataRowQuery

    @Deprecated(since="5.0", forRemoval=true) @SafeVarargs public static SelectById<DataRow> dataRowQuery(Class<?> entityType, Map<String,?> firstId, Map<String,?>... otherIds)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `dataRowQueryMaps(Class, Map[])`
    Since:
      4.2

  - ### dataRowQuery

    @Deprecated(since="5.0", forRemoval=true) public static SelectById<DataRow> dataRowQuery(ObjectId firstId, ObjectId... otherIds)
    Deprecated, for removal: This API element is subject to removal in a future version.
    since 5.0, use `dataRowQueryObjectIds(ObjectId...)`
    Since:
      4.2

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

  - ### localCache

    public SelectById<T> 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 SelectById<T> 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 SelectById<T> 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 SelectById<T> 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);

  - ### getCacheStrategy

    public QueryCacheStrategy getCacheStrategy()

  - ### cacheStrategy

    public SelectById<T> cacheStrategy(QueryCacheStrategy strategy)

  - ### cacheStrategy

    public SelectById<T> cacheStrategy(QueryCacheStrategy strategy, String cacheGroup)

  - ### getCacheGroup

    public String getCacheGroup()

  - ### cacheGroup

    public SelectById<T> cacheGroup(String cacheGroup)

  - ### isFetchingDataRows

    public boolean isFetchingDataRows()

  - ### prefetch

    public SelectById<T> prefetch(PrefetchTreeNode prefetch)
    Merges prefetch into the query prefetch tree.
    Returns:
      this object

  - ### prefetch

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

  - ### getPrefetches

    public PrefetchTreeNode getPrefetches()

  - ### 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.
    Specified by:
      `createReplacementQuery` in class `IndirectQuery`