1 // Copyright 2010 Google Inc. All Rights Reserved.
3 package com
.google
.appengine
.api
.search
;
5 import com
.google
.appengine
.api
.search
.checkers
.Preconditions
;
7 import java
.io
.Serializable
;
8 import java
.util
.Collection
;
9 import java
.util
.Collections
;
10 import java
.util
.Iterator
;
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.
17 * @param <T> The type of search result.
19 public class Results
<T
> implements Iterable
<T
>, Serializable
{
20 private static final long serialVersionUID
= -8342630524311776674L;
22 private static final int MAX_RESULTS_TO_STRING
= 10;
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
;
31 * Creates a {@link Results} by specifying a collection of search
32 * results, the number of results found, and the number of results
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
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
;
54 public Iterator
<T
> iterator() {
55 return results
.iterator();
59 * @return the result of the search operation
61 public OperationResult
getOperationResult() {
62 return operationResult
;
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
71 * @return the number of results found
73 public long getNumberFound() {
78 * @return the number of results returned
80 public int getNumberReturned() {
81 return numberReturned
;
85 * @return an unmodifiable collection of search results
87 public Collection
<T
> getResults() {
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}
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}.
102 public Cursor
getCursor() {
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
)