1 /*
2 * #%L
3 * Count.java - mongodb-async-driver - Allanbank Consulting, Inc.
4 * %%
5 * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
6 * %%
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 * #L%
19 */
20
21 package com.allanbank.mongodb.builder;
22
23 import java.util.concurrent.TimeUnit;
24
25 import com.allanbank.mongodb.MongoCollection;
26 import com.allanbank.mongodb.ReadPreference;
27 import com.allanbank.mongodb.Version;
28 import com.allanbank.mongodb.bson.Document;
29 import com.allanbank.mongodb.bson.DocumentAssignable;
30
31 /**
32 * Count provides an immutable container for all of the options for a query to
33 * count documents.
34 *
35 * @api.yes This class is part of the driver's API. Public and protected members
36 * will be deprecated for at least 1 non-bugfix release (version
37 * numbers are <major>.<minor>.<bugfix>) before being
38 * removed or modified.
39 * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
40 */
41 public class Count {
42
43 /** An (empty) query document to find all documents. */
44 public static final Document ALL = MongoCollection.ALL;
45
46 /**
47 * The first version of MongoDB to support the {@code count} command with
48 * the ability to limit the execution time on the server.
49 */
50 public static final Version MAX_TIMEOUT_VERSION = Find.MAX_TIMEOUT_VERSION;
51
52 /**
53 * Creates a new builder for a {@link Count}.
54 *
55 * @return The builder to construct a {@link Count}.
56 */
57 public static Builder builder() {
58 return new Builder();
59 }
60
61 /** The maximum amount of time to allow the query to run. */
62 private final long myMaximumTimeMilliseconds;
63
64 /** The query document. */
65 private final Document myQuery;
66
67 /** The preference for which servers to use to retrieve the results. */
68 private final ReadPreference myReadPreference;
69
70 /**
71 * Creates a new Count.
72 *
73 * @param builder
74 * The builder to copy the query fields from.
75 */
76 protected Count(final Builder builder) {
77 myQuery = builder.myQuery;
78 myReadPreference = builder.myReadPreference;
79 myMaximumTimeMilliseconds = builder.myMaximumTimeMilliseconds;
80 }
81
82 /**
83 * Returns the maximum amount of time to allow the query to run on the
84 * Server before it is aborted.
85 *
86 * @return The maximum amount of time to allow the query to run on the
87 * Server before it is aborted.
88 *
89 * @since MongoDB 2.6
90 */
91 public long getMaximumTimeMilliseconds() {
92 return myMaximumTimeMilliseconds;
93 }
94
95 /**
96 * Returns the query document.
97 *
98 * @return The query document.
99 */
100 public Document getQuery() {
101 return myQuery;
102 }
103
104 /**
105 * Returns the preference for the servers to retrieve the results from. May
106 * be <code>null</code> in which case the default read preference should be
107 * used.
108 *
109 * @return The preference for the servers to retrieve the results from.
110 */
111 public ReadPreference getReadPreference() {
112 return myReadPreference;
113 }
114
115 /**
116 * Helper for creating immutable {@link Count} queries.
117 *
118 * @api.yes This class is part of the driver's API. Public and protected
119 * members will be deprecated for at least 1 non-bugfix release
120 * (version numbers are <major>.<minor>.<bugfix>)
121 * before being removed or modified.
122 * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
123 */
124 public static class Builder {
125
126 /** The maximum amount of time to allow the query to run. */
127 protected long myMaximumTimeMilliseconds;
128
129 /** The query document. */
130 protected Document myQuery;
131
132 /** The preference for which servers to use to retrieve the results. */
133 protected ReadPreference myReadPreference;
134
135 /**
136 * Creates a new Builder.
137 */
138 public Builder() {
139 reset();
140 }
141
142 /**
143 * Creates a new Builder.
144 *
145 * @param query
146 * The query document.
147 */
148 public Builder(final DocumentAssignable query) {
149 this();
150 myQuery = query.asDocument();
151 }
152
153 /**
154 * Constructs a new {@link Count} object from the state of the builder.
155 *
156 * @return The new {@link Count} object.
157 */
158 public Count build() {
159 return new Count(this);
160 }
161
162 /**
163 * Sets the maximum number of milliseconds to allow the query to run
164 * before aborting the request on the server.
165 * <p>
166 * This method equivalent to {@link #setMaximumTimeMilliseconds(long)
167 * setMaximumTimeMilliseconds(timeLimitUnits.toMillis(timeLimit)}.
168 * </p>
169 *
170 * @param timeLimit
171 * The new maximum amount of time to allow the query to run.
172 * @param timeLimitUnits
173 * The units for the maximum amount of time to allow the
174 * query to run.
175 *
176 * @return This {@link Builder} for method call chaining.
177 *
178 * @since MongoDB 2.6
179 */
180 public Builder maximumTime(final long timeLimit,
181 final TimeUnit timeLimitUnits) {
182 return setMaximumTimeMilliseconds(timeLimitUnits
183 .toMillis(timeLimit));
184 }
185
186 /**
187 * Sets the value of the query document to the new value.
188 * <p>
189 * This method delegates to {@link #setQuery(DocumentAssignable)}.
190 * </p>
191 *
192 * @param query
193 * The new value for the query document.
194 * @return This builder for chaining method calls.
195 */
196 public Builder query(final DocumentAssignable query) {
197 return setQuery(query);
198 }
199
200 /**
201 * Sets the preference for the set of servers to retrieve the results
202 * from.
203 * <p>
204 * This method delegates to {@link #setReadPreference(ReadPreference)}.
205 * </p>
206 *
207 * @param readPreference
208 * The new value for the preference of which server to return
209 * the results from.
210 * @return This builder for chaining method calls.
211 */
212 public Builder readPreference(final ReadPreference readPreference) {
213 return setReadPreference(readPreference);
214 }
215
216 /**
217 * Resets the builder back to its initial state for reuse.
218 *
219 * @return This builder for chaining method calls.
220 */
221 public Builder reset() {
222 myQuery = ALL;
223 myReadPreference = null;
224 myMaximumTimeMilliseconds = 0;
225
226 return this;
227 }
228
229 /**
230 * Sets the maximum number of milliseconds to allow the query to run
231 * before aborting the request on the server.
232 *
233 * @param maximumTimeMilliseconds
234 * The new maximum number of milliseconds to allow the query
235 * to run.
236 * @return This {@link Builder} for method call chaining.
237 *
238 * @since MongoDB 2.6
239 */
240 public Builder setMaximumTimeMilliseconds(
241 final long maximumTimeMilliseconds) {
242 myMaximumTimeMilliseconds = maximumTimeMilliseconds;
243 return this;
244 }
245
246 /**
247 * Sets the value of the query document to the new value.
248 *
249 * @param query
250 * The new value for the query document.
251 * @return This builder for chaining method calls.
252 */
253 public Builder setQuery(final DocumentAssignable query) {
254 myQuery = query.asDocument();
255 return this;
256 }
257
258 /**
259 * Sets the preference for the set of servers to retrieve the results
260 * from.
261 *
262 * @param readPreference
263 * The new value for the preference of which server to return
264 * the results from.
265 * @return This builder for chaining method calls.
266 */
267 public Builder setReadPreference(final ReadPreference readPreference) {
268 myReadPreference = readPreference;
269 return this;
270 }
271
272 }
273 }