java/src/main/com/google/appengine/api/datastore/PreparedQuery.java

   1 // Copyright 2008 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.datastore;
   4
   5 import java.util.Iterator;
   6 import java.util.List;
   7
   8 /**
   9  * Contains methods for fetching and returning entities
  10  * from a {@link Query}. If the {@link Query} specified
  11  * a sort order, {@link Entity Entities} are returned in that order.
  12  * Otherwise, the order is undefined.
  13  * <p>
  14  * A {@link PreparedQuery} does not cache results. Each
  15  * use of {@link PreparedQuery} results in a new trip to the
  16  * datastore.
  17  */
  18 public interface PreparedQuery {
  19   /**
  20    * Retrieves the {@link Query} {@link Entity Entities} as a {@link List}
  21    * using the provided {@link FetchOptions}.
  22    * <p>
  23    * Note that if {@link FetchOptions#getLimit()} is greater than the number of
  24    * {@link Entity Entities}, the length of the returned {@link List}
  25    * will be smaller than{@link FetchOptions#getLimit()}.
  26    * <p>
  27    * To operate on large result sets, you should prefer {@link #asIterable}
  28    * and {@link #asIterator}, which stream the results from the
  29    * datastore.
  30    *
  31    * @param fetchOptions The fetch options to apply.
  32    * @return The result of the PreparedQuery, represented as a {@link List}.
  33    *
  34    * @throws IllegalStateException If the query being executed is associated
  35    * with a {@link Transaction} that is not active.
  36    *
  37    * @see FetchOptions
  38    */
  39   List<Entity> asList(FetchOptions fetchOptions);
  40
  41   /**
  42    * Similar to {@link #asList} except a {@link QueryResultIterator} is returned.
  43    */
  44   QueryResultList<Entity> asQueryResultList(FetchOptions fetchOptions);
  45
  46   /**
  47    * Retrieves the {@link Query} {@link Entity Entities} as an {@link Iterable}
  48    * using the provided {@link FetchOptions}.
  49    *
  50    * Each use of {@link Iterable#iterator} results in an entirely new and
  51    * independent {@link Iterator}.
  52    *
  53    * @param fetchOptions The fetch options to apply.
  54    *
  55    * @return The result of the PreparedQuery, represented as an {@link Iterable}.
  56    *
  57    * @throws IllegalStateException If the query being executed is associated
  58    * with a {@link Transaction} that is not active.
  59    *
  60    * @see FetchOptions
  61    */
  62   Iterable<Entity> asIterable(FetchOptions fetchOptions);
  63
  64   /**
  65    * Similar to {@link #asIterable(FetchOptions)} except a {@link QueryResultIterable} is returned.
  66    * Call this method to have (indirect) access to {@link Cursor}s for your result set.
  67    */
  68   QueryResultIterable<Entity> asQueryResultIterable(FetchOptions fetchOptions);
  69
  70   /**
  71    * Equivalent to {@link #asIterable(FetchOptions)} but uses default {@link FetchOptions}.
  72    */
  73   Iterable<Entity> asIterable();
  74
  75   /**
  76    * Similar to {@link #asIterable()} except a {@link QueryResultIterable} is returned.
  77    * Call this method to have (indirect) access to {@link Cursor}s for your result set.
  78    */
  79   QueryResultIterable<Entity> asQueryResultIterable();
  80
  81   /**
  82    * Retrieves the {@link Query} {@link Entity Entities} as an {@link Iterator}
  83    * using the provided {@link FetchOptions}.
  84    *
  85    * @param fetchOptions The fetch strategy to apply.
  86    *
  87    * @return The result of the PreparedQuery, represented as an {@link Iterator}.
  88    *
  89    * @throws IllegalStateException If the query being executed is associated
  90    * with a {@link Transaction} that is not active.
  91    *
  92    * @see FetchOptions
  93    */
  94   Iterator<Entity> asIterator(FetchOptions fetchOptions);
  95
  96   /**
  97    * Equivalent to {@link #asIterator(FetchOptions)} but uses default {@link FetchOptions}.
  98    */
  99   Iterator<Entity> asIterator();
 100
 101   /**
 102    * Similar to {@link #asIterator(FetchOptions)} except a {@link QueryResultIterator} is returned.
 103    * Call this method to have access to {@link Cursor}s for your result set.
 104    */
 105   QueryResultIterator<Entity> asQueryResultIterator(FetchOptions fetchOptions);
 106
 107   /**
 108    * Similar to {@link #asIterator()} except a {@link QueryResultIterator} is returned.
 109    * Call this method to have access to {@link Cursor}s for your result set.
 110    */
 111   QueryResultIterator<Entity> asQueryResultIterator();
 112
 113   /**
 114    * Retrieves the one and only result for the {@link Query}.
 115    *
 116    * @throws TooManyResultsException if more than one result is returned
 117    * from the {@link Query}.
 118    *
 119    * @return the single, matching result, or {@code null} if no entities match
 120    *
 121    * @throws IllegalStateException If the query being executed is associated
 122    * with a {@link Transaction} that is not active.
 123    *
 124    */
 125   Entity asSingleEntity() throws TooManyResultsException;
 126
 127   /**
 128    * Retrieves the number of {@link Entity Entities} that currently
 129    * match this {@link Query}.
 130    *
 131    * @return a count >= 0
 132    *
 133    * @throws IllegalStateException If the query being executed is associated
 134    * with a {@link Transaction} that is not active.
 135    */
 136   int countEntities(FetchOptions fetchOptions);
 137
 138   /**
 139    * Retrieves the number of {@link Entity Entities} that currently
 140    * match this {@link Query}.
 141    *
 142    * @return a count >= 0
 143    *
 144    * @throws IllegalStateException If the query being executed is associated
 145    * with a {@link Transaction} that is not active.
 146    *
 147    * @deprecated Use {@link #countEntities(FetchOptions)} instead. Calling
 148    * this function imposes a maximum result limit of 1000.
 149    */
 150   @Deprecated
 151   int countEntities();
 152
 153   /**
 154    * Indicates that too many results were found for
 155    * {@link PreparedQuery#asSingleEntity}.
 156    */
 157   class TooManyResultsException extends RuntimeException { }
 158 }