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

static class

PreparedQuery.TooManyResultsException Indicates that too many results were found for asSingleEntity().

Method Summary

java.lang.Iterable<Entity>	asIterable() Equivalent to asIterable(FetchOptions.Builder.withChunkSize(FetchOptions.DEFAULT_CHUNK_SIZE).
java.lang.Iterable<Entity>	asIterable(FetchOptions fetchOptions) Retrieves the Query Entities as an Iterable using the provided FetchOptions.
java.util.Iterator<Entity>	asIterator() Equivalent to asIterator(FetchOptions.Builder.withChunkSize(FetchOptions.DEFAULT_CHUNK_SIZE).
java.util.Iterator<Entity>	asIterator(FetchOptions fetchOptions) Retrieves the Query Entities as an Iterator using the provided FetchOptions.
java.util.List<Entity>	asList(FetchOptions fetchOptions) Retrieves the Query Entities as a List using the provided .
Entity	asSingleEntity() Retrieves the one and only result for the Query.
int	countEntities() Retrieves the number of Entities that currently match this Query.

Method Detail

asList

java.util.List<Entity> asList(FetchOptions fetchOptions)

Retrieves the Query Entities as a List using the provided .

Note that if FetchOptions.getLimit() is greater than the number of Entities, they are all returned. In that case, 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 (offset and limit). FetchOptions.getChunkSize() is ignored since we fetch FetchOptions.getLimit() results all at once.

Returns:

The result of the PreparedQuery, represented as a List.

Throws:

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

See Also:

FetchOptions

asIterable

java.lang.Iterable<Entity> asIterable(FetchOptions fetchOptions)

Retrieves the Query Entities as an Iterable using the provided FetchOptions. Each use of iterator on the Iterable results in an entirely new and independent Iterator.

Parameters:

fetchOptions - The fetch options to apply (offset, limit, chunk size).

Returns:

The result of the PreparedQuery, represented as a Iterable.

Throws:

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

See Also:

FetchOptions

asIterable

java.lang.Iterable<Entity> asIterable()

Equivalent to asIterable(FetchOptions.Builder.withChunkSize(FetchOptions.DEFAULT_CHUNK_SIZE).

asIterator

java.util.Iterator<Entity> asIterator(FetchOptions fetchOptions)

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

Parameters:

fetchOptions - The fetch strategy to apply (offset, limit, and chunk size).

Returns:

The result of the PreparedQuery, represented as a Iterator.

Throws:

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

See Also:

FetchOptions

asIterator

java.util.Iterator<Entity> asIterator()

Equivalent to asIterator(FetchOptions.Builder.withChunkSize(FetchOptions.DEFAULT_CHUNK_SIZE).

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.

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

countEntities

int countEntities()

Retrieves the number of Entities that currently match this Query.

Returns:

a count >= 0

Throws:

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