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

   1 // Copyright 2007 Google Inc. All rights reserved.
   2
   3 package com.google.appengine.api.datastore;
   4
   5 import java.util.List;
   6
   7 /**
   8  * Provides an abstraction for retrieving {@code Entity} objects in
   9  * arbitrarily-sized batches.
  10  *
  11  */
  12 interface QueryResultsSource {
  13   /**
  14    * Returns true when there maybe more {@code Entity} objects that
  15    * can be returned from this {@code QueryResultsSource}.
  16    */
  17   boolean hasMoreEntities();
  18
  19   /**
  20    * Load at least one {@code Entity} object if there are more entities.
  21    *
  22    * @param buffer An out parameter to which the requested entities will be added.
  23    * @param cursorBuffer An out parameter to which the requested entity cursors will be added.
  24    * @return the cursor that points to the {@link Entity} after the last {@link Entity}
  25    * returned or {@code null} (see {@link #loadMoreEntities(int, List, List)} for a description of
  26    * when this will be {@code null})
  27    */
  28   Cursor loadMoreEntities(List<Entity> buffer, List<Cursor> cursorBuffer);
  29
  30   /**
  31    * Load the specified number of {@code Entity} objects and add them to the
  32    * given buffer. This method will only return less than {@code numberToLoad} if
  33    * less than {@code numberToLoad} entities are present. However this method may
  34    * return more than {@code numberToLoad} entities at any time.
  35    *
  36    * Requesting 0 results to be loaded has the effect of ensuring any offset requested
  37    * has been satisfied but not requiring any results be loaded (although some might be.
  38    * This is usually needed before calling {@link #getNumSkipped()} or to get the first
  39    * {@link Cursor}.
  40    *
  41    * This will return {@code null} in any of the following conditions:
  42    * <ul>
  43    * <li>{@link #hasMoreEntities()} is false
  44    * <li>No results were requested and no offset needed to be satisfied.
  45    * <li>the query does not support the compile flag
  46    * <li>the compile flag was not set on the {@link FetchOptions} used to run the query
  47    * <ul>
  48    *
  49    * @param numberToLoad the number of entities to get.
  50    * @param buffer An out parameter to which the requested entities will be added.
  51    * @param cursorBuffer An out parameter to which the requested entity cursors will be added.
  52    * @return the cursor that points to the {@link Entity} after the last {@link Entity}
  53    * returned or {@code null}
  54    */
  55   Cursor loadMoreEntities(int numberToLoad, List<Entity> buffer, List<Cursor> cursorBuffer);
  56
  57   /**
  58    * Returns the number of entities that have been skipped so far.
  59    *
  60    * Entities are skipped when an offset has been set on the query.
  61    */
  62   int getNumSkipped();
  63
  64   /**
  65    * Get the indexes used to perform the query.
  66    * May sometimes return only the indexes used so far.
  67    *
  68    * @return A list of index ids, with no duplicates, or {@code null} if the
  69    * indexes are not known.
  70    */
  71   List<Index> getIndexList();
  72
  73 }