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) but uses default FetchOptions.
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) but uses default FetchOptions.
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 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. Calling this function imposes a maximum result limit of 1000.
int	countEntities(FetchOptions fetchOptions) 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 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:

java.lang.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

java.lang.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:

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

See Also:

FetchOptions

asQueryResultIterable

QueryResultIterable<Entity> asQueryResultIterable(FetchOptions fetchOptions)

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

asIterable

java.lang.Iterable<Entity> asIterable()

Equivalent to asIterable(FetchOptions) but uses default FetchOptions.

asQueryResultIterable

QueryResultIterable<Entity> asQueryResultIterable()

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

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.

Returns:

The result of the PreparedQuery, represented as an 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) 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.

java.lang.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:

java.lang.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:

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