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 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 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 protected Text(final Builder builder) {
137 assertNotEmpty(builder.mySearchTerm,
138 "The search term for a 'text' command must be a non-empty string.");
139
140 myLanguage = builder.myLanguage;
141 myLimit = builder.myLimit;
142 myQuery = builder.myQuery;
143 myReadPreference = builder.myReadPreference;
144 myReturnFields = builder.myReturnFields;
145 mySearchTerm = builder.mySearchTerm;
146 }
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 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 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 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 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 return myReturnFields;
198 }
199
200 /**
201 * Returns the search terms.
202 *
203 * @return The search terms.
204 */
205 public String getSearchTerm() {
206 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 public Builder() {
250 reset();
251 }
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 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 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 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 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 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 myLanguage = null;
340 myLimit = 0;
341 myQuery = null;
342 myReadPreference = null;
343 myReturnFields = null;
344 mySearchTerm = null;
345
346 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 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 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 myLanguage = language;
388 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 myLimit = limit;
401 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 if (query != null) {
415 myQuery = query.asDocument();
416 }
417 else {
418 myQuery = null;
419 }
420 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 myReadPreference = readPreference;
440 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 if (returnFields != null) {
452 myReturnFields = returnFields.asDocument();
453 }
454 else {
455 myReturnFields = null;
456 }
457 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 mySearchTerm = searchTerm;
469 return this;
470 }
471 }
472 }