1 // Copyright 2008 Google Inc. All Rights Reserved.
3 package com
.google
.appengine
.api
.datastore
;
5 import java
.util
.Iterator
;
9 * Contains methods for fetching and returning entities
10 * from a {@link Query}. If the {@link Query} specified
11 * a sort order, {@link Entity Entities} are returned in that order.
12 * Otherwise, the order is undefined.
14 * A {@link PreparedQuery} does not cache results. Each
15 * use of {@link PreparedQuery} results in a new trip to the
18 public interface PreparedQuery
{
20 * Retrieves the {@link Query} {@link Entity Entities} as a {@link List}
21 * using the provided {@link FetchOptions}.
23 * Note that if {@link FetchOptions#getLimit()} is greater than the number of
24 * {@link Entity Entities}, the length of the returned {@link List}
25 * will be smaller than{@link FetchOptions#getLimit()}.
27 * To operate on large result sets, you should prefer {@link #asIterable}
28 * and {@link #asIterator}, which stream the results from the
31 * @param fetchOptions The fetch options to apply.
32 * @return The result of the PreparedQuery, represented as a {@link List}.
34 * @throws IllegalStateException If the query being executed is associated
35 * with a {@link Transaction} that is not active.
39 List
<Entity
> asList(FetchOptions fetchOptions
);
42 * Similar to {@link #asList} except a {@link QueryResultIterator} is returned.
44 QueryResultList
<Entity
> asQueryResultList(FetchOptions fetchOptions
);
47 * Retrieves the {@link Query} {@link Entity Entities} as an {@link Iterable}
48 * using the provided {@link FetchOptions}.
50 * Each use of {@link Iterable#iterator} results in an entirely new and
51 * independent {@link Iterator}.
53 * @param fetchOptions The fetch options to apply.
55 * @return The result of the PreparedQuery, represented as an {@link Iterable}.
57 * @throws IllegalStateException If the query being executed is associated
58 * with a {@link Transaction} that is not active.
62 Iterable
<Entity
> asIterable(FetchOptions fetchOptions
);
65 * Similar to {@link #asIterable(FetchOptions)} except a {@link QueryResultIterable} is returned.
66 * Call this method to have (indirect) access to {@link Cursor}s for your result set.
68 QueryResultIterable
<Entity
> asQueryResultIterable(FetchOptions fetchOptions
);
71 * Equivalent to {@link #asIterable(FetchOptions)} but uses default {@link FetchOptions}.
73 Iterable
<Entity
> asIterable();
76 * Similar to {@link #asIterable()} except a {@link QueryResultIterable} is returned.
77 * Call this method to have (indirect) access to {@link Cursor}s for your result set.
79 QueryResultIterable
<Entity
> asQueryResultIterable();
82 * Retrieves the {@link Query} {@link Entity Entities} as an {@link Iterator}
83 * using the provided {@link FetchOptions}.
85 * @param fetchOptions The fetch strategy to apply.
87 * @return The result of the PreparedQuery, represented as an {@link Iterator}.
89 * @throws IllegalStateException If the query being executed is associated
90 * with a {@link Transaction} that is not active.
94 Iterator
<Entity
> asIterator(FetchOptions fetchOptions
);
97 * Equivalent to {@link #asIterator(FetchOptions)} but uses default {@link FetchOptions}.
99 Iterator
<Entity
> asIterator();
102 * Similar to {@link #asIterator(FetchOptions)} except a {@link QueryResultIterator} is returned.
103 * Call this method to have access to {@link Cursor}s for your result set.
105 QueryResultIterator
<Entity
> asQueryResultIterator(FetchOptions fetchOptions
);
108 * Similar to {@link #asIterator()} except a {@link QueryResultIterator} is returned.
109 * Call this method to have access to {@link Cursor}s for your result set.
111 QueryResultIterator
<Entity
> asQueryResultIterator();
114 * Retrieves the one and only result for the {@link Query}.
116 * @throws TooManyResultsException if more than one result is returned
117 * from the {@link Query}.
119 * @return the single, matching result, or {@code null} if no entities match
121 * @throws IllegalStateException If the query being executed is associated
122 * with a {@link Transaction} that is not active.
125 Entity
asSingleEntity() throws TooManyResultsException
;
128 * Retrieves the number of {@link Entity Entities} that currently
129 * match this {@link Query}.
131 * @return a count {@literal >= 0}
133 * @throws IllegalStateException If the query being executed is associated
134 * with a {@link Transaction} that is not active.
136 int countEntities(FetchOptions fetchOptions
);
139 * Retrieves the number of {@link Entity Entities} that currently
140 * match this {@link Query}.
142 * @return a count {@literal >= 0}
144 * @throws IllegalStateException If the query being executed is associated
145 * with a {@link Transaction} that is not active.
147 * @deprecated Use {@link #countEntities(FetchOptions)} instead. Calling
148 * this function imposes a maximum result limit of 1000.
154 * Indicates that too many results were found for
155 * {@link PreparedQuery#asSingleEntity}.
157 class TooManyResultsException
extends RuntimeException
{ }