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   private static final int MAX_FACET_RESULTS_TO_STRING = 10;
  24
  25   private final OperationResult operationResult;
  26   private final Collection<T> results;
  27   private final Collection<FacetResult> facets;
  28   private final long numberFound;
  29   private final int numberReturned;
  30   private final Cursor cursor;
  31
  32   /**
  33    * Creates a {@link Results} by specifying a collection of search
  34    * results, the number of results found, and the number of results
  35    * returned.
  36    *
  37    * @param operationResult the result of the search operation
  38    * @param results a collection of results that resulted from the search
  39    * @param numberFound the number of results found by the search
  40    * @param numberReturned the number of results returned
  41    * @param cursor the {@link Cursor} if there are more results and user
  42    * requested it
  43    */
  44   protected Results(OperationResult operationResult, Collection<T> results,
  45       long numberFound, int numberReturned, Cursor cursor) {
  46     this(operationResult, results, numberFound, numberReturned, cursor,
  47         Collections.<FacetResult>emptyList());
  48   }
  49
  50   /**
  51    * Creates a {@link Results} by specifying a collection of search
  52    * results, the number of results found, and the number of results
  53    * returned.
  54    *
  55    * @param operationResult the result of the search operation
  56    * @param results a collection of results that resulted from the search
  57    * @param numberFound the number of results found by the search
  58    * @param numberReturned the number of results returned
  59    * @param cursor the {@link Cursor} if there are more results and user
  60    * requested it
  61    * @param facets aggregated facets of this search results as a collection of {@link FacetResult}
  62    * from the search
  63    */
  64   protected Results(OperationResult operationResult, Collection<T> results,
  65       long numberFound, int numberReturned, Cursor cursor, Collection<FacetResult> facets) {
  66     this.operationResult = Preconditions.checkNotNull(operationResult,
  67         "operation result cannot be null");
  68     this.results = Collections.unmodifiableCollection(
  69         Preconditions.checkNotNull(results, "search results cannot be null"));
  70     this.facets = Collections.unmodifiableCollection(
  71         Preconditions.checkNotNull(facets, "facets cannot be null"));
  72     this.numberFound = numberFound;
  73     this.numberReturned = numberReturned;
  74     this.cursor = cursor;
  75   }
  76
  77   @Override
  78   public Iterator<T> iterator() {
  79     return results.iterator();
  80   }
  81
  82   /**
  83    * @return the result of the search operation
  84    */
  85   public OperationResult getOperationResult() {
  86     return operationResult;
  87   }
  88
  89   /**
  90    * The number of results found by the search.
  91    * If the value is less than or equal to the corresponding
  92    * {@link QueryOptions#getNumberFoundAccuracy()},
  93    * then it is accurate, otherwise it is an approximation
  94    *
  95    * @return the number of results found
  96    */
  97   public long getNumberFound() {
  98     return numberFound;
  99   }
 100
 101   /**
 102    * @return the number of results returned
 103    */
 104   public int getNumberReturned() {
 105     return numberReturned;
 106   }
 107
 108   /**
 109    * @return an unmodifiable collection of search results
 110    */
 111   public Collection<T> getResults() {
 112     return results;
 113   }
 114
 115   /**
 116    * @return an unmodifiable collection of aggregated facets for this search results
 117    */
 118   public Collection<FacetResult> getFacets() {
 119     return facets;
 120   }
 121
 122   /**
 123    * A cursor to be used to continue the search after all the results
 124    * in this search response. For this field to be populated,
 125    * use {@link QueryOptions.Builder#setCursor} with a value of
 126    * {@code Cursor.newBuilder().build()}, otherwise {@link #getCursor}
 127    * will return null.
 128    *
 129    * @return cursor to be used to get the next set of results after the
 130    * end of these results, or {@code null} if there are no more results
 131    * to be expected or if no cursor was configured in the {@code QueryOptions}.
 132    */
 133   public Cursor getCursor() {
 134     return cursor;
 135   }
 136
 137   @Override
 138   public String toString() {
 139     return new Util.ToStringHelper("Results")
 140         .addField("operationResult", operationResult)
 141         .addIterableField("results", results, MAX_RESULTS_TO_STRING)
 142         .addIterableField("facets", facets, MAX_FACET_RESULTS_TO_STRING)
 143         .addField("numberFound", numberFound)
 144         .addField("numberReturned", numberReturned)
 145         .addField("cursor", cursor)
 146         .finish();
 147   }
 148 }