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  */
  20 public class Results<T> implements Iterable<T>, Serializable {
  21   private static final long serialVersionUID = -8342630524311776674L;
  22
  23   private static final int MAX_RESULTS_TO_STRING = 10;
  24
  25   private final OperationResult operationResult;
  26   private final Collection<T> results;
  27   private final long numberFound;
  28   private final int numberReturned;
  29   private final Cursor cursor;
  30
  31   /**
  32    * Creates a {@link Results} by specifying a collection of search
  33    * results, the number of results found, and the number of results
  34    * returned.
  35    *
  36    * @param operationResult the result of the search operation
  37    * @param results a collection of results that resulted from the search
  38    * @param numberFound the number of results found by the search
  39    * @param numberReturned the number of results returned
  40    * @param cursor the {@link Cursor} if there are more results and user
  41    * requested it
  42    */
  43   protected Results(OperationResult operationResult, Collection<T> results,
  44       long numberFound, int numberReturned, Cursor cursor) {
  45     this.operationResult = Preconditions.checkNotNull(operationResult,
  46         "operation result cannot be null");
  47     this.results = Collections.unmodifiableCollection(
  48         Preconditions.checkNotNull(results, "search results cannot be null"));
  49     this.numberFound = numberFound;
  50     this.numberReturned = numberReturned;
  51     this.cursor = cursor;
  52   }
  53
  54   @Override
  55   public Iterator<T> iterator() {
  56     return results.iterator();
  57   }
  58
  59   /**
  60    * @return the result of the search operation
  61    */
  62   public OperationResult getOperationResult() {
  63     return operationResult;
  64   }
  65
  66   /**
  67    * The number of results found by the search.
  68    * If the value is less than or equal to the corresponding
  69    * {@link QueryOptions#getNumberFoundAccuracy()},
  70    * then it is accurate, otherwise it is an approximation
  71    *
  72    * @return the number of results found
  73    */
  74   public long getNumberFound() {
  75     return numberFound;
  76   }
  77
  78   /**
  79    * @return the number of results returned
  80    */
  81   public int getNumberReturned() {
  82     return numberReturned;
  83   }
  84
  85   /**
  86    * @return an unmodifiable collection of search results
  87    */
  88   public Collection<T> getResults() {
  89     return results;
  90   }
  91
  92   /**
  93    * A cursor to be used to continue the search after all the results
  94    * in this search response. For this field to be populated,
  95    * use {@link QueryOptions.Builder#setCursor} with a value of
  96    * {@code Cursor.newBuilder().build()}, otherwise {@link #getCursor}
  97    * will return null.
  98    *
  99    * @return cursor to be used to get the next set of results after the
 100    * end of these results. Can be {@code null}
 101    */
 102   public Cursor getCursor() {
 103     return cursor;
 104   }
 105
 106   @Override
 107   public String toString() {
 108     return String.format("Results(operationResult=%s, results=%s, numberFound=%d, " +
 109         "numberReturned=%d, cursor=%s)",
 110         operationResult, Util.iterableToString(results, MAX_RESULTS_TO_STRING),
 111         numberFound, numberReturned, cursor);
 112   }
 113 }