java/src/main/com/google/appengine/api/search/Results.java

   1 // Copyright 2010 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.search;
   4
   5 import com.google.appengine.api.search.checkers.Preconditions;
   6
   7 import java.io.Serializable;
   8 import java.util.Collection;
   9 import java.util.Collections;
  10 import java.util.Iterator;
  11
  12 /**
  13  * Represents a result of executing a search.
  14  * The Results include an {@link OperationResult}, a collection of
  15  * results, and a number of found and returned results.
  16  *
  17  * @param <T> The type of search result.
  18  */
  19 public class Results<T> implements Iterable<T>, Serializable {
  20   private static final long serialVersionUID = -8342630524311776674L;
  21
  22   private static final int MAX_RESULTS_TO_STRING = 10;
  23
  24   private final OperationResult operationResult;
  25   private final Collection<T> results;
  26   private final long numberFound;
  27   private final int numberReturned;
  28   private final Cursor cursor;
  29
  30   /**
  31    * Creates a {@link Results} by specifying a collection of search
  32    * results, the number of results found, and the number of results
  33    * returned.
  34    *
  35    * @param operationResult the result of the search operation
  36    * @param results a collection of results that resulted from the search
  37    * @param numberFound the number of results found by the search
  38    * @param numberReturned the number of results returned
  39    * @param cursor the {@link Cursor} if there are more results and user
  40    * requested it
  41    */
  42   protected Results(OperationResult operationResult, Collection<T> results,
  43       long numberFound, int numberReturned, Cursor cursor) {
  44     this.operationResult = Preconditions.checkNotNull(operationResult,
  45         "operation result cannot be null");
  46     this.results = Collections.unmodifiableCollection(
  47         Preconditions.checkNotNull(results, "search results cannot be null"));
  48     this.numberFound = numberFound;
  49     this.numberReturned = numberReturned;
  50     this.cursor = cursor;
  51   }
  52
  53   @Override
  54   public Iterator<T> iterator() {
  55     return results.iterator();
  56   }
  57
  58   /**
  59    * @return the result of the search operation
  60    */
  61   public OperationResult getOperationResult() {
  62     return operationResult;
  63   }
  64
  65   /**
  66    * The number of results found by the search.
  67    * If the value is less than or equal to the corresponding
  68    * {@link QueryOptions#getNumberFoundAccuracy()},
  69    * then it is accurate, otherwise it is an approximation
  70    *
  71    * @return the number of results found
  72    */
  73   public long getNumberFound() {
  74     return numberFound;
  75   }
  76
  77   /**
  78    * @return the number of results returned
  79    */
  80   public int getNumberReturned() {
  81     return numberReturned;
  82   }
  83
  84   /**
  85    * @return an unmodifiable collection of search results
  86    */
  87   public Collection<T> getResults() {
  88     return results;
  89   }
  90
  91   /**
  92    * A cursor to be used to continue the search after all the results
  93    * in this search response. For this field to be populated,
  94    * use {@link QueryOptions.Builder#setCursor} with a value of
  95    * {@code Cursor.newBuilder().build()}, otherwise {@link #getCursor}
  96    * will return null.
  97    *
  98    * @return cursor to be used to get the next set of results after the
  99    * end of these results, or {@code null} if there are no more results
 100    * to be expected or if no cursor was configured in the {@code QueryOptions}.
 101    */
 102   public Cursor getCursor() {
 103     return cursor;
 104   }
 105
 106   @Override
 107   public String toString() {
 108     return new Util.ToStringHelper("Results")
 109         .addField("operationResult", operationResult)
 110         .addIterableField("results", results, MAX_RESULTS_TO_STRING)
 111         .addField("numberFound", numberFound)
 112         .addField("numberReturned", numberReturned)
 113         .addField("cursor", cursor)
 114         .finish();
 115   }
 116 }