Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Text |
|
| 1.0869565217391304;1.087 | ||||
Text$Builder |
|
| 1.0869565217391304;1.087 |
1 | /* | |
2 | * #%L | |
3 | * Text.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 static com.allanbank.mongodb.util.Assertions.assertNotEmpty; | |
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 | * Text provides a wrapper for a {@code text} command to query a collection with | |
33 | * a {@link Index#text(String) text index}. | |
34 | * <p> | |
35 | * The result of a {@code text} command is a document that looks like the | |
36 | * following:<blockquote> | |
37 | * | |
38 | * <pre> | |
39 | * <code> | |
40 | * > db.collection.runCommand( { "text": "collection" , search: "coffee magic" } ) | |
41 | * { | |
42 | * "queryDebugString" : "coffe|magic||||||", | |
43 | * "language" : "english", | |
44 | * "results" : [ | |
45 | * { | |
46 | * "score" : 2.25, | |
47 | * "obj" : { | |
48 | * "_id" : ObjectId("51376ab8602c316554cfe248"), | |
49 | * "content" : "Coffee is full of magical powers." | |
50 | * } | |
51 | * }, | |
52 | * { | |
53 | * "score" : 0.625, | |
54 | * "obj" : { | |
55 | * "_id" : ObjectId("51376a80602c316554cfe246"), | |
56 | * "content" : "Now is the time to drink all of the coffee." | |
57 | * } | |
58 | * } | |
59 | * ], | |
60 | * "stats" : { | |
61 | * "nscanned" : 3, | |
62 | * "nscannedObjects" : 0, | |
63 | * "n" : 2, | |
64 | * "nfound" : 2, | |
65 | * "timeMicros" : 97 | |
66 | * }, | |
67 | * "ok" : 1 | |
68 | * } | |
69 | * </code> | |
70 | * </pre> | |
71 | * | |
72 | * </blockquote> | |
73 | * </p> | |
74 | * <p> | |
75 | * The {@link TextResult} class wraps a single entry from the {@code results} | |
76 | * array. | |
77 | * </p> | |
78 | * | |
79 | * @api.no <b>This class is NOT part of the Public API.</b> This class may be | |
80 | * mutated in incompatible ways between any two releases of the driver. | |
81 | * This class <b>WILL</b>, eventually, be part of the driver's API. | |
82 | * Until MongoDB Inc. finalizes the text query interface we are keeping | |
83 | * this class out of the Public API so we can track any changes more | |
84 | * closely. | |
85 | * @see <a | |
86 | * href="http://docs.mongodb.org/manual/release-notes/2.4/#text-queries"> | |
87 | * MongoDB Text Queries</a> | |
88 | * @since MongoDB 2.4 | |
89 | * @deprecated Support for the {@code text} command was deprecated in the 2.6 | |
90 | * version of MongoDB. Use the {@link ConditionBuilder#text(String) | |
91 | * $text} query operator instead. This class will not be removed | |
92 | * until two releases after the MongoDB 2.6 release (e.g. 2.10 if | |
93 | * the releases are 2.8 and 2.10). | |
94 | * @copyright 2013-2014, Allanbank Consulting, Inc., All Rights Reserved | |
95 | */ | |
96 | @Deprecated | |
97 | public class Text { | |
98 | /** The first version of MongoDB to support the text command. */ | |
99 | 1 | public static final Version REQUIRED_VERSION = Version.VERSION_2_4; |
100 | ||
101 | /** | |
102 | * Creates a new builder for a {@link Text} command. | |
103 | * | |
104 | * @return The builder to construct a {@link Text} command. | |
105 | */ | |
106 | public static Builder builder() { | |
107 | 8 | return new Builder(); |
108 | } | |
109 | ||
110 | /** The language to use when stemming the search terms. */ | |
111 | private final String myLanguage; | |
112 | ||
113 | /** Maximum number of document to return. */ | |
114 | private final int myLimit; | |
115 | ||
116 | /** A standard MongoDB query document to limit the final results. */ | |
117 | private final Document myQuery; | |
118 | ||
119 | /** The read preference to use. */ | |
120 | private final ReadPreference myReadPreference; | |
121 | ||
122 | /** The fields to return from the query. */ | |
123 | private final Document myReturnFields; | |
124 | ||
125 | /** The search terms. */ | |
126 | private final String mySearchTerm; | |
127 | ||
128 | /** | |
129 | * Creates a new Text. | |
130 | * | |
131 | * @param builder | |
132 | * The builder containing the state of the text command. | |
133 | * @throws IllegalArgumentException | |
134 | * On the search term not being set. | |
135 | */ | |
136 | 10 | protected Text(final Builder builder) { |
137 | 10 | assertNotEmpty(builder.mySearchTerm, |
138 | "The search term for a 'text' command must be a non-empty string."); | |
139 | ||
140 | 8 | myLanguage = builder.myLanguage; |
141 | 8 | myLimit = builder.myLimit; |
142 | 8 | myQuery = builder.myQuery; |
143 | 8 | myReadPreference = builder.myReadPreference; |
144 | 8 | myReturnFields = builder.myReturnFields; |
145 | 8 | mySearchTerm = builder.mySearchTerm; |
146 | 8 | } |
147 | ||
148 | /** | |
149 | * Returns the language to use when stemming the search terms. | |
150 | * | |
151 | * @return The language to use when stemming the search terms. | |
152 | */ | |
153 | public String getLanguage() { | |
154 | 9 | return myLanguage; |
155 | } | |
156 | ||
157 | /** | |
158 | * Returns the maximum number of document to return. | |
159 | * | |
160 | * @return The maximum number of document to return. | |
161 | */ | |
162 | public int getLimit() { | |
163 | 9 | return myLimit; |
164 | } | |
165 | ||
166 | /** | |
167 | * Returns the query document to limit the final results. | |
168 | * | |
169 | * @return The query document to limit the final results. | |
170 | */ | |
171 | public Document getQuery() { | |
172 | 9 | return myQuery; |
173 | } | |
174 | ||
175 | /** | |
176 | * Returns the {@link ReadPreference} specifying which servers may be used | |
177 | * to execute the {@link Text} command. | |
178 | * <p> | |
179 | * If <code>null</code> then the {@link MongoCollection} instance's | |
180 | * {@link ReadPreference} will be used. | |
181 | * </p> | |
182 | * | |
183 | * @return The read preference to use. | |
184 | * | |
185 | * @see MongoCollection#getReadPreference() | |
186 | */ | |
187 | public ReadPreference getReadPreference() { | |
188 | 8 | return myReadPreference; |
189 | } | |
190 | ||
191 | /** | |
192 | * Returns the fields to return from the query. | |
193 | * | |
194 | * @return The fields to return from the query. | |
195 | */ | |
196 | public Document getReturnFields() { | |
197 | 9 | return myReturnFields; |
198 | } | |
199 | ||
200 | /** | |
201 | * Returns the search terms. | |
202 | * | |
203 | * @return The search terms. | |
204 | */ | |
205 | public String getSearchTerm() { | |
206 | 8 | return mySearchTerm; |
207 | } | |
208 | ||
209 | /** | |
210 | * Builder provides a builder for Text commands. | |
211 | * | |
212 | * @api.no <b>This class is NOT part of the Public API.</b> This class may | |
213 | * be mutated in incompatible ways between any two releases of the | |
214 | * driver. This class <b>WILL</b>, eventually, be part of the | |
215 | * driver's API. Until MongoDB Inc. finalizes the text query | |
216 | * interface we are keeping this class out of the Public API so we | |
217 | * can track any changes more closely. | |
218 | * @copyright 2013, Allanbank Consulting, Inc., All Rights Reserved | |
219 | * @deprecated Support for the {@code text} command was deprecated in the | |
220 | * 2.6 version of MongoDB. Use the | |
221 | * {@link ConditionBuilder#text(String) $text} query operator | |
222 | * instead. This class will not be removed until two releases | |
223 | * after the MongoDB 2.6 release (e.g. 2.10 if the releases are | |
224 | * 2.8 and 2.10). | |
225 | */ | |
226 | @Deprecated | |
227 | public static class Builder { | |
228 | /** The language to use when stemming the search terms. */ | |
229 | protected String myLanguage; | |
230 | ||
231 | /** Maximum number of document to return. */ | |
232 | protected int myLimit; | |
233 | ||
234 | /** A standard MongoDB query document to limit the final results. */ | |
235 | protected Document myQuery; | |
236 | ||
237 | /** The read preference to use. */ | |
238 | protected ReadPreference myReadPreference; | |
239 | ||
240 | /** The fields to return from the query. */ | |
241 | protected Document myReturnFields; | |
242 | ||
243 | /** The search terms. */ | |
244 | protected String mySearchTerm; | |
245 | ||
246 | /** | |
247 | * Creates a new Builder. | |
248 | */ | |
249 | 8 | public Builder() { |
250 | 8 | reset(); |
251 | 8 | } |
252 | ||
253 | /** | |
254 | * Creates a new {@link Text} based on the current state of the builder. | |
255 | * | |
256 | * @return A new {@link Text} based on the current state of the builder. | |
257 | * @throws IllegalArgumentException | |
258 | * On the search term not being set. | |
259 | */ | |
260 | public Text build() { | |
261 | 10 | return new Text(this); |
262 | } | |
263 | ||
264 | /** | |
265 | * Sets the language to use when stemming the search terms to the new | |
266 | * value. | |
267 | * <p> | |
268 | * This method delegates to {@link #setLanguage(String)} | |
269 | * </p> | |
270 | * | |
271 | * @param language | |
272 | * The new value for the language to use when stemming the | |
273 | * search terms. | |
274 | * @return This {@link Builder} for method call chaining. | |
275 | */ | |
276 | public Builder language(final String language) { | |
277 | 5 | return setLanguage(language); |
278 | } | |
279 | ||
280 | /** | |
281 | * Sets the maximum number of document to return to the new value. | |
282 | * <p> | |
283 | * This method delegates to {@link #setLimit(int)} | |
284 | * </p> | |
285 | * | |
286 | * @param limit | |
287 | * The new value for the maximum number of document to | |
288 | * return. | |
289 | * @return This {@link Builder} for method call chaining. | |
290 | */ | |
291 | public Builder limit(final int limit) { | |
292 | 4 | return setLimit(limit); |
293 | } | |
294 | ||
295 | /** | |
296 | * Sets the standard MongoDB query document to limit the final results | |
297 | * to the new value. | |
298 | * <p> | |
299 | * This method delegates to {@link #setQuery(DocumentAssignable)} | |
300 | * </p> | |
301 | * | |
302 | * @param query | |
303 | * The new value for the standard MongoDB query document to | |
304 | * limit the final results. | |
305 | * @return This {@link Builder} for method call chaining. | |
306 | */ | |
307 | public Builder query(final DocumentAssignable query) { | |
308 | 5 | return setQuery(query); |
309 | } | |
310 | ||
311 | /** | |
312 | * Sets the {@link ReadPreference} specifying which servers may be used | |
313 | * to execute the {@link Text} command. | |
314 | * <p> | |
315 | * If not set or set to <code>null</code> then the | |
316 | * {@link MongoCollection} instance's {@link ReadPreference} will be | |
317 | * used. | |
318 | * </p> | |
319 | * <p> | |
320 | * This method delegates to {@link #setReadPreference(ReadPreference)}. | |
321 | * </p> | |
322 | * | |
323 | * @param readPreference | |
324 | * The read preferences specifying which servers may be used. | |
325 | * @return This builder for chaining method calls. | |
326 | * | |
327 | * @see MongoCollection#getReadPreference() | |
328 | */ | |
329 | public Builder readPreference(final ReadPreference readPreference) { | |
330 | 5 | return setReadPreference(readPreference); |
331 | } | |
332 | ||
333 | /** | |
334 | * Resets the builder back to its initial state. | |
335 | * | |
336 | * @return This {@link Builder} for method call chaining. | |
337 | */ | |
338 | public Builder reset() { | |
339 | 9 | myLanguage = null; |
340 | 9 | myLimit = 0; |
341 | 9 | myQuery = null; |
342 | 9 | myReadPreference = null; |
343 | 9 | myReturnFields = null; |
344 | 9 | mySearchTerm = null; |
345 | ||
346 | 9 | return this; |
347 | } | |
348 | ||
349 | /** | |
350 | * Sets the fields to return from the query to the new value. | |
351 | * <p> | |
352 | * This method delegates to {@link #setReturnFields(DocumentAssignable)} | |
353 | * </p> | |
354 | * | |
355 | * @param returnFields | |
356 | * The new value for the fields to return from the query. | |
357 | * @return This {@link Builder} for method call chaining. | |
358 | */ | |
359 | public Builder returnFields(final DocumentAssignable returnFields) { | |
360 | 5 | return setReturnFields(returnFields); |
361 | } | |
362 | ||
363 | /** | |
364 | * Sets the search term to the new value. | |
365 | * <p> | |
366 | * This method delegates to {@link #setSearchTerm(String)} | |
367 | * </p> | |
368 | * | |
369 | * @param searchTerm | |
370 | * The new value for the search terms. | |
371 | * @return This {@link Builder} for method call chaining. | |
372 | */ | |
373 | public Builder searchTerm(final String searchTerm) { | |
374 | 8 | return setSearchTerm(searchTerm); |
375 | } | |
376 | ||
377 | /** | |
378 | * Sets the language to use when stemming the search terms to the new | |
379 | * value. | |
380 | * | |
381 | * @param language | |
382 | * The new value for the language to use when stemming the | |
383 | * search terms. | |
384 | * @return This {@link Builder} for method call chaining. | |
385 | */ | |
386 | public Builder setLanguage(final String language) { | |
387 | 5 | myLanguage = language; |
388 | 5 | return this; |
389 | } | |
390 | ||
391 | /** | |
392 | * Sets the maximum number of document to return to the new value. | |
393 | * | |
394 | * @param limit | |
395 | * The new value for the maximum number of document to | |
396 | * return. | |
397 | * @return This {@link Builder} for method call chaining. | |
398 | */ | |
399 | public Builder setLimit(final int limit) { | |
400 | 4 | myLimit = limit; |
401 | 4 | return this; |
402 | } | |
403 | ||
404 | /** | |
405 | * Sets the standard MongoDB query document to limit the final results | |
406 | * to the new value. | |
407 | * | |
408 | * @param query | |
409 | * The new value for the standard MongoDB query document to | |
410 | * limit the final results. | |
411 | * @return This {@link Builder} for method call chaining. | |
412 | */ | |
413 | public Builder setQuery(final DocumentAssignable query) { | |
414 | 5 | if (query != null) { |
415 | 4 | myQuery = query.asDocument(); |
416 | } | |
417 | else { | |
418 | 1 | myQuery = null; |
419 | } | |
420 | 5 | return this; |
421 | } | |
422 | ||
423 | /** | |
424 | * Sets the {@link ReadPreference} specifying which servers may be used | |
425 | * to execute the {@link Text} command. | |
426 | * <p> | |
427 | * If not set or set to <code>null</code> then the | |
428 | * {@link MongoCollection} instance's {@link ReadPreference} will be | |
429 | * used. | |
430 | * </p> | |
431 | * | |
432 | * @param readPreference | |
433 | * The read preferences specifying which servers may be used. | |
434 | * @return This builder for chaining method calls. | |
435 | * | |
436 | * @see MongoCollection#getReadPreference() | |
437 | */ | |
438 | public Builder setReadPreference(final ReadPreference readPreference) { | |
439 | 5 | myReadPreference = readPreference; |
440 | 5 | return this; |
441 | } | |
442 | ||
443 | /** | |
444 | * Sets the fields to return from the query to the new value. | |
445 | * | |
446 | * @param returnFields | |
447 | * The new value for the fields to return from the query. | |
448 | * @return This {@link Builder} for method call chaining. | |
449 | */ | |
450 | public Builder setReturnFields(final DocumentAssignable returnFields) { | |
451 | 5 | if (returnFields != null) { |
452 | 4 | myReturnFields = returnFields.asDocument(); |
453 | } | |
454 | else { | |
455 | 1 | myReturnFields = null; |
456 | } | |
457 | 5 | return this; |
458 | } | |
459 | ||
460 | /** | |
461 | * Sets the search term to the new value. | |
462 | * | |
463 | * @param searchTerm | |
464 | * The new value for the search terms. | |
465 | * @return This {@link Builder} for method call chaining. | |
466 | */ | |
467 | public Builder setSearchTerm(final String searchTerm) { | |
468 | 8 | mySearchTerm = searchTerm; |
469 | 8 | return this; |
470 | } | |
471 | } | |
472 | } |