Package com.google.appengine.api.datastore

Interface PreparedQuery

public interface PreparedQuery

Contains methods for fetching and returning entities from a Query. If the Query specified a sort order, Entities are returned in that order. Otherwise, the order is undefined.

A PreparedQuery does not cache results. Each use of PreparedQuery results in a new trip to the datastore.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	PreparedQuery.TooManyResultsException	Indicates that too many results were found for asSingleEntity().

Method Summary

Modifier and Type	Method	Description
Iterable<Entity>	asIterable()	Equivalent to asIterable(FetchOptions) but uses default FetchOptions.
Iterable<Entity>	asIterable(FetchOptions fetchOptions)	Retrieves the Query Entities as an Iterable using the provided FetchOptions.
Iterator<Entity>	asIterator()	Equivalent to asIterator(FetchOptions) but uses default FetchOptions.
Iterator<Entity>	asIterator(FetchOptions fetchOptions)	Retrieves the Query Entities as an Iterator using the provided FetchOptions.
List<Entity>	asList(FetchOptions fetchOptions)	Retrieves the Query Entities as a List using the provided FetchOptions.
QueryResultIterable<Entity>	asQueryResultIterable()	Similar to asIterable() except a QueryResultIterable is returned.
QueryResultIterable<Entity>	asQueryResultIterable(FetchOptions fetchOptions)	Similar to asIterable(FetchOptions) except a QueryResultIterable is returned.
QueryResultIterator<Entity>	asQueryResultIterator()	Similar to asIterator() except a QueryResultIterator is returned.
QueryResultIterator<Entity>	asQueryResultIterator(FetchOptions fetchOptions)	Similar to asIterator(FetchOptions) except a QueryResultIterator is returned.
QueryResultList<Entity>	asQueryResultList(FetchOptions fetchOptions)	Similar to asList(com.google.appengine.api.datastore.FetchOptions) except a QueryResultIterator is returned.
Entity	asSingleEntity()	Retrieves the one and only result for the Query.
int	countEntities()	Deprecated. Use countEntities(FetchOptions) instead.
int	countEntities(FetchOptions fetchOptions)	Retrieves the number of Entities that currently match this Query.

Method Details

asList

List<Entity> asList(FetchOptions fetchOptions)

Retrieves the Query Entities as a List using the provided FetchOptions.

Note that if FetchOptions.getLimit() is greater than the number of Entities, the length of the returned List will be smaller thanFetchOptions.getLimit().

To operate on large result sets, you should prefer asIterable(com.google.appengine.api.datastore.FetchOptions) and asIterator(com.google.appengine.api.datastore.FetchOptions), which stream the results from the datastore.

Parameters:

fetchOptions - The fetch options to apply.

Returns:

The result of the PreparedQuery, represented as a List.

Throws:

IllegalStateException - If the query being executed is associated with a Transaction that is not active.

See Also:

• FetchOptions

asQueryResultList

QueryResultList<Entity> asQueryResultList(FetchOptions fetchOptions)

Similar to asList(com.google.appengine.api.datastore.FetchOptions) except a QueryResultIterator is returned.

asIterable

Iterable<Entity> asIterable(FetchOptions fetchOptions)

Retrieves the Query Entities as an Iterable using the provided FetchOptions.

Each use of Iterable.iterator() results in an entirely new and independent Iterator.

Parameters:

fetchOptions - The fetch options to apply.

Returns:

The result of the PreparedQuery, represented as an Iterable.

Throws:

IllegalStateException - If the query being executed is associated with a Transaction that is not active.

See Also:

• FetchOptions

asIterable

Iterable<Entity> asIterable()

Equivalent to asIterable(FetchOptions) but uses default FetchOptions.

asQueryResultIterable

QueryResultIterable<Entity> asQueryResultIterable(FetchOptions fetchOptions)

Similar to asIterable(FetchOptions) except a QueryResultIterable is returned. Call this method to have (indirect) access to Cursors for your result set.

asQueryResultIterable

QueryResultIterable<Entity> asQueryResultIterable()

Similar to asIterable() except a QueryResultIterable is returned. Call this method to have (indirect) access to Cursors for your result set.

asIterator

Iterator<Entity> asIterator(FetchOptions fetchOptions)

Retrieves the Query Entities as an Iterator using the provided FetchOptions.

Parameters:

fetchOptions - The fetch strategy to apply.

Returns:

The result of the PreparedQuery, represented as an Iterator.

Throws:

IllegalStateException - If the query being executed is associated with a Transaction that is not active.

See Also:

• FetchOptions

asIterator

Iterator<Entity> asIterator()

Equivalent to asIterator(FetchOptions) but uses default FetchOptions.

asQueryResultIterator

QueryResultIterator<Entity> asQueryResultIterator(FetchOptions fetchOptions)

Similar to asIterator(FetchOptions) except a QueryResultIterator is returned. Call this method to have access to Cursors for your result set.

asQueryResultIterator

QueryResultIterator<Entity> asQueryResultIterator()

Similar to asIterator() except a QueryResultIterator is returned. Call this method to have access to Cursors for your result set.

asSingleEntity

Entity asSingleEntity()
               throws PreparedQuery.TooManyResultsException

Retrieves the one and only result for the Query.

Returns:

the single, matching result, or null if no entities match

Throws:

PreparedQuery.TooManyResultsException - if more than one result is returned from the Query.

IllegalStateException - If the query being executed is associated with a Transaction that is not active.

countEntities

int countEntities(FetchOptions fetchOptions)

Retrieves the number of Entities that currently match this Query.

Returns:

a count >= 0

Throws:

IllegalStateException - If the query being executed is associated with a Transaction that is not active.

countEntities

@Deprecated
int countEntities()

Deprecated.

Use countEntities(FetchOptions) instead. Calling this function imposes a maximum result limit of 1000.

Retrieves the number of Entities that currently match this Query.

Returns:

a count >= 0

Throws:

IllegalStateException - If the query being executed is associated with a Transaction that is not active.