PreparedQuery (Google App Engine API for Java)

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 and Description
    static class	PreparedQuery.TooManyResultsException Indicates that too many results were found for asSingleEntity().

  • Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods 

    Modifier and Type	Method and Description
    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 (indirect) 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 (indirect) 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.