1 /*
2 * #%L
3 * MongoCollection.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 package com.allanbank.mongodb;
21
22 import java.util.Collection;
23
24 import com.allanbank.mongodb.bson.Document;
25 import com.allanbank.mongodb.bson.DocumentAssignable;
26 import com.allanbank.mongodb.bson.Element;
27 import com.allanbank.mongodb.bson.element.IntegerElement;
28 import com.allanbank.mongodb.builder.Aggregate;
29 import com.allanbank.mongodb.builder.BatchedWrite;
30 import com.allanbank.mongodb.builder.ConditionBuilder;
31 import com.allanbank.mongodb.builder.Count;
32 import com.allanbank.mongodb.builder.Distinct;
33 import com.allanbank.mongodb.builder.Find;
34 import com.allanbank.mongodb.builder.FindAndModify;
35 import com.allanbank.mongodb.builder.GroupBy;
36 import com.allanbank.mongodb.builder.MapReduce;
37 import com.allanbank.mongodb.builder.ParallelScan;
38
39 /**
40 * Interface for interacting with a MongoDB collection.
41 * <p>
42 * The asynchronous methods for interacting with a collection are declared as
43 * part of the {@link AsyncMongoCollection} interface (which this interface
44 * extends. The separation of the interfaces is to support the ability to batch
45 * requests to the server. This will take advantage of the batched write
46 * commands if the driver is only connected to @link {@link Version#VERSION_2_6
47 * 2.6} or above servers otherwise batching is similar in function to the
48 * {@link MongoClient#asSerializedClient() serialized client} capability.
49 * </p>
50 * <p>
51 * To use the batching capability you will need to call the
52 * {@link #startBatch()} method and then ensure that the
53 * {@link BatchedAsyncMongoCollection#close() close()} method is called to
54 * submit the batch of requests.
55 * </p>
56 *
57 * @api.yes This interface is part of the driver's API. Public and protected
58 * members will be deprecated for at least 1 non-bugfix release
59 * (version numbers are <major>.<minor>.<bugfix>)
60 * before being removed or modified.
61 * @copyright 2011-2013, Allanbank Consulting, Inc., All Rights Reserved
62 */
63 public interface MongoCollection extends AsyncMongoCollection {
64 /** An (empty) query document to find all documents. */
65 public static final Document ALL = AsyncMongoCollection.ALL;
66
67 /** An (empty) update document to perform no actual modifications. */
68 public static final Document NONE = AsyncMongoCollection.NONE;
69
70 /**
71 * Invokes a aggregate command on the server.
72 *
73 * @param command
74 * The details of the aggregation request.
75 * @return The aggregation results returned.
76 * @throws MongoDbException
77 * On an error executing the aggregate command.
78 */
79 public MongoIterator<Document> aggregate(Aggregate command)
80 throws MongoDbException;
81
82 /**
83 * Invokes a aggregate command on the server.
84 *
85 * @param command
86 * The details of the aggregation request.
87 * @return The aggregation results returned.
88 * @throws MongoDbException
89 * On an error executing the aggregate command.
90 */
91 public MongoIterator<Document> aggregate(Aggregate.Builder command)
92 throws MongoDbException;
93
94 /**
95 * Counts the set of documents in the collection.
96 * <p>
97 * This is equivalent to calling {@link #countAsync() countAsync().get()}
98 * </p>
99 *
100 * @return The number of documents in the collection.
101 * @throws MongoDbException
102 * On an error finding the documents.
103 */
104 public long count() throws MongoDbException;
105
106 /**
107 * Counts the set of documents matching the query document in the
108 * collection.
109 *
110 * @param count
111 * The count command.
112 * @return The count of the documents.
113 * @throws MongoDbException
114 * On an error counting the documents.
115 */
116 public long count(Count count) throws MongoDbException;
117
118 /**
119 * Counts the set of documents matching the query document in the
120 * collection.
121 *
122 * @param count
123 * The count command.
124 * @return The count of the documents.
125 * @throws MongoDbException
126 * On an error counting the documents.
127 */
128 public long count(Count.Builder count) throws MongoDbException;
129
130 /**
131 * Counts the set of documents matching the query document in the
132 * collection.
133 * <p>
134 * This is equivalent to calling {@link #countAsync(DocumentAssignable)
135 * countAsync(...).get()}
136 * </p>
137 *
138 * @param query
139 * The query document.
140 * @return The number of matching documents.
141 * @throws MongoDbException
142 * On an error finding the documents.
143 */
144 public long count(DocumentAssignable query) throws MongoDbException;
145
146 /**
147 * Counts the set of documents matching the query document in the
148 * collection.
149 *
150 * @param query
151 * The query document.
152 * @param readPreference
153 * The preference for which servers to use to retrieve the
154 * results.
155 * @return The number of matching documents.
156 * @throws MongoDbException
157 * On an error finding the documents.
158 */
159 public long count(DocumentAssignable query, ReadPreference readPreference)
160 throws MongoDbException;
161
162 /**
163 * Counts the set of documents in the collection.
164 * <p>
165 * This is equivalent to calling {@link #countAsync() countAsync().get()}
166 * </p>
167 *
168 * @param readPreference
169 * The preference for which servers to use to retrieve the
170 * results.
171 * @return The number of documents in the collection.
172 * @throws MongoDbException
173 * On an error finding the documents.
174 */
175 public long count(ReadPreference readPreference) throws MongoDbException;
176
177 /**
178 * Creates an index with a generated name, across the keys specified and if
179 * <tt>unique</tt> is true ensuring entries are unique.
180 * <p>
181 * This method is intended to be used with the
182 * {@link com.allanbank.mongodb.builder.Index} class's static methods:
183 * <blockquote>
184 *
185 * <pre>
186 * <code>
187 * import static {@link com.allanbank.mongodb.builder.Index#asc(String) com.allanbank.mongodb.builder.Index.asc};
188 * import static {@link com.allanbank.mongodb.builder.Index#desc(String) com.allanbank.mongodb.builder.Index.desc};
189 *
190 * MongoCollection collection = ...;
191 *
192 * collection.createIndex( true, asc("f"), desc("g") );
193 * ...
194 * </code>
195 * </pre>
196 *
197 * </blockquote>
198 *
199 * @param unique
200 * If true then the index created will enforce entries are
201 * unique.
202 * @param keys
203 * The keys to use for the index.
204 * @throws MongoDbException
205 * On a failure building the index.
206 */
207 public void createIndex(boolean unique, Element... keys)
208 throws MongoDbException;
209
210 /**
211 * Creates an index with a generated name, across the keys specified
212 * allowing duplicate entries.
213 * <p>
214 * This method is intended to be used with the
215 * {@link com.allanbank.mongodb.builder.Index} class's static methods:
216 * <blockquote>
217 *
218 * <pre>
219 * <code>
220 * import static {@link com.allanbank.mongodb.bson.builder.BuilderFactory#start com.allanbank.mongodb.bson.builder.BuilderFactory.start};
221 * import static {@link com.allanbank.mongodb.builder.Index#asc(String) com.allanbank.mongodb.builder.Index.asc};
222 * import static {@link com.allanbank.mongodb.builder.Index#desc(String) com.allanbank.mongodb.builder.Index.desc};
223 *
224 * MongoCollection collection = ...;
225 *
226 * collection.createIndex(start().add("sparse", true), asc("f") );
227 * ...
228 * </code>
229 * </pre>
230 *
231 * </blockquote>
232 *
233 * @param options
234 * The options for the index.
235 * @param keys
236 * The keys to use for the index.
237 * @throws MongoDbException
238 * On a failure building the index.
239 * @see <a
240 * href="http://www.mongodb.org/display/DOCS/Indexes#Indexes-CreationOptions">Index
241 * Options Documentation</a>
242 */
243 public void createIndex(DocumentAssignable options, Element... keys)
244 throws MongoDbException;
245
246 /**
247 * Creates an index with a generated name, across the keys specified
248 * allowing duplicate entries.
249 * <p>
250 * This method is intended to be used with the
251 * {@link com.allanbank.mongodb.builder.Index} class's static methods:
252 * <blockquote>
253 *
254 * <pre>
255 * <code>
256 * import static {@link com.allanbank.mongodb.builder.Index#asc(String) com.allanbank.mongodb.builder.Index.asc};
257 * import static {@link com.allanbank.mongodb.builder.Index#desc(String) com.allanbank.mongodb.builder.Index.desc};
258 *
259 * MongoCollection collection = ...;
260 *
261 * collection.createIndex( asc("f"), desc("g") );
262 * ...
263 * </code>
264 * </pre>
265 *
266 * </blockquote>
267 *
268 * @param keys
269 * The keys to use for the index.
270 * @throws MongoDbException
271 * On a failure building the index.
272 */
273 public void createIndex(Element... keys) throws MongoDbException;
274
275 /**
276 * Creates an index with the specified name, across the keys specified and
277 * if <tt>unique</tt> is true ensuring entries are unique.
278 * <p>
279 * This method is intended to be used with the
280 * {@link com.allanbank.mongodb.builder.Index} class's static methods:
281 * <blockquote>
282 *
283 * <pre>
284 * <code>
285 * import static {@link com.allanbank.mongodb.builder.Index#asc(String) com.allanbank.mongodb.builder.Index.asc};
286 * import static {@link com.allanbank.mongodb.builder.Index#desc(String) com.allanbank.mongodb.builder.Index.desc};
287 *
288 * MongoCollection collection = ...;
289 *
290 * collection.createIndex( "f_and_g", false, asc("f"), desc("g") );
291 * ...
292 * </code>
293 * </pre>
294 *
295 * </blockquote>
296 *
297 * @param name
298 * The name of the index. If <code>null</code> then a name is
299 * generated based on the keys.
300 * @param keys
301 * The keys to use for the index.
302 * @param unique
303 * If true then the index created will enforce entries are
304 * unique.
305 * @throws MongoDbException
306 * On a failure building the index.
307 */
308 public void createIndex(String name, boolean unique, Element... keys)
309 throws MongoDbException;
310
311 /**
312 * Creates an index with a generated name, across the keys specified
313 * allowing duplicate entries.
314 * <p>
315 * This method is intended to be used with the
316 * {@link com.allanbank.mongodb.builder.Index} class's static methods:
317 * <blockquote>
318 *
319 * <pre>
320 * <code>
321 * import static {@link com.allanbank.mongodb.bson.builder.BuilderFactory#start com.allanbank.mongodb.bson.builder.BuilderFactory.start};
322 * import static {@link com.allanbank.mongodb.builder.Index#asc(String) com.allanbank.mongodb.builder.Index.asc};
323 * import static {@link com.allanbank.mongodb.builder.Index#desc(String) com.allanbank.mongodb.builder.Index.desc};
324 *
325 * MongoCollection collection = ...;
326 *
327 * collection.createIndex("sparse_f", start().add("sparse", true), asc("f") );
328 * ...
329 * </code>
330 * </pre>
331 *
332 * </blockquote>
333 *
334 * @param name
335 * The name of the index. If <code>null</code> then a name is
336 * generated based on the keys.
337 * @param options
338 * The options for the index.
339 * @param keys
340 * The keys to use for the index.
341 * @throws MongoDbException
342 * On a failure building the index.
343 * @see <a
344 * href="http://www.mongodb.org/display/DOCS/Indexes#Indexes-CreationOptions">Index
345 * Options Documentation</a>
346 */
347 public void createIndex(String name, DocumentAssignable options,
348 Element... keys) throws MongoDbException;
349
350 /**
351 * Deletes a set of documents matching a query from the collection.
352 *
353 * @param query
354 * Query to locate the documents to be deleted.
355 * @return The results of the delete. If the durability of the operation is
356 * NONE then this will be -1.
357 * @throws MongoDbException
358 * On an error deleting the documents.
359 */
360 public long delete(DocumentAssignable query) throws MongoDbException;
361
362 /**
363 * Deletes a set of documents matching a query from the collection.
364 *
365 * @param query
366 * Query to locate the documents to be deleted.
367 * @param singleDelete
368 * If true then only a single document will be deleted. If
369 * running in a sharded environment then this field must be false
370 * or the query must contain the shard key.
371 * @return The results of the delete. If the durability of the operation is
372 * NONE then this will be -1.
373 * @throws MongoDbException
374 * On an error deleting the documents.
375 */
376 public long delete(DocumentAssignable query, boolean singleDelete)
377 throws MongoDbException;
378
379 /**
380 * Deletes a set of documents matching a query from the collection.
381 *
382 * @param query
383 * Query to locate the documents to be deleted.
384 * @param singleDelete
385 * If true then only a single document will be deleted. If
386 * running in a sharded environment then this field must be false
387 * or the query must contain the shard key.
388 * @param durability
389 * The durability for the delete.
390 * @return The results of the delete. If the durability of the operation is
391 * NONE then this will be -1.
392 * @throws MongoDbException
393 * On an error deleting the documents.
394 */
395 public long delete(DocumentAssignable query, boolean singleDelete,
396 Durability durability) throws MongoDbException;
397
398 /**
399 * Deletes a set of documents matching a query from the collection.
400 *
401 * @param query
402 * Query to locate the documents to be deleted.
403 * @param durability
404 * The durability for the delete.
405 * @return The results of the delete. If the durability of the operation is
406 * NONE then this will be -1.
407 * @throws MongoDbException
408 * On an error deleting the documents.
409 */
410 public long delete(DocumentAssignable query, Durability durability)
411 throws MongoDbException;
412
413 /**
414 * Invokes a distinct command on the server.
415 *
416 * @param command
417 * The details of the distinct request.
418 * @return The distinct results returned.
419 * @throws MongoDbException
420 * On an error finding the documents.
421 */
422 public MongoIterator<Element> distinct(Distinct command)
423 throws MongoDbException;
424
425 /**
426 * Invokes a distinct command on the server.
427 *
428 * @param command
429 * The details of the distinct request.
430 * @return The distinct results returned.
431 * @throws MongoDbException
432 * On an error finding the documents.
433 */
434 public MongoIterator<Element> distinct(Distinct.Builder command)
435 throws MongoDbException;
436
437 /**
438 * Drops the collection from the database.
439 *
440 * @return True if the collection was successfully dropped.
441 * @throws MongoDbException
442 * On an error dropping the collection.
443 */
444 public boolean drop() throws MongoDbException;
445
446 /**
447 * Deletes the indexes matching the keys specified.
448 * <p>
449 * This method is intended to be used with the
450 * {@link com.allanbank.mongodb.builder.Index} class's static methods:
451 * <blockquote>
452 *
453 * <pre>
454 * <code>
455 * import static {@link com.allanbank.mongodb.builder.Index#asc(String) com.allanbank.mongodb.builder.Index.asc};
456 * import static {@link com.allanbank.mongodb.builder.Index#desc(String) com.allanbank.mongodb.builder.Index.desc};
457 *
458 * MongoCollection collection = ...;
459 *
460 * collection.dropIndex( asc("f"), desc("g") );
461 * ...
462 * </code>
463 * </pre>
464 *
465 * </blockquote>
466 *
467 * @param keys
468 * The keys for the index to be dropped.
469 * @return If any indexes were removed.
470 * @throws MongoDbException
471 * On an error deleting the indexes.
472 */
473 public boolean dropIndex(IntegerElement... keys) throws MongoDbException;
474
475 /**
476 * Deletes the indexes with the provided name.
477 *
478 * @param name
479 * The name of the index.
480 * @return If any indexes were removed.
481 * @throws MongoDbException
482 * On an error deleting the indexes.
483 */
484 public boolean dropIndex(String name) throws MongoDbException;
485
486 /**
487 * Returns true if this collection already exists on the server.
488 * <p>
489 * This method is simply a helper name to check if this collection's name
490 * appears in the parent {@link MongoDatabase database's} list of
491 * collections.
492 * </p>
493 *
494 * @return True if the parent database returns this collection's name in its
495 * list of collection names.
496 * @throws MongoDbException
497 * On an error retrieving the list of collections.
498 */
499 public boolean exists() throws MongoDbException;
500
501 /**
502 * Explains the way that the aggregation will be performed.
503 * <p>
504 * This is equivalent to calling {@link #explainAsync(Aggregate)
505 * explainAsync(...).get()}
506 * </p>
507 *
508 * @param aggregation
509 * The aggregation details.
510 * @return The document describing the method used to execute the
511 * aggregation.
512 * @throws MongoDbException
513 * On an error finding the documents.
514 * @since MongoDB 2.6
515 */
516 public Document explain(Aggregate aggregation) throws MongoDbException;
517
518 /**
519 * Explains the way that the aggregation will be performed.
520 * <p>
521 * This is equivalent to calling {@link #explainAsync(Aggregate)
522 * explainAsync(...).get()}
523 * </p>
524 *
525 * @param aggregation
526 * The aggregation details.
527 * @return The document describing the method used to execute the
528 * aggregation.
529 * @throws MongoDbException
530 * On an error finding the documents.
531 * @since MongoDB 2.6
532 */
533 public Document explain(Aggregate.Builder aggregation)
534 throws MongoDbException;
535
536 /**
537 * Explains the way that the query will be performed.
538 *
539 * @param query
540 * The query document.
541 * @return The document describing the method used to execute the query.
542 * @throws MongoDbException
543 * On an error finding the documents.
544 */
545 public Document explain(DocumentAssignable query) throws MongoDbException;
546
547 /**
548 * Explains the way that the query will be performed.
549 * <p>
550 * This is equivalent to calling {@link #explainAsync(Find)
551 * explainAsync(...).get()}
552 * </p>
553 *
554 * @param query
555 * The query details.
556 * @return The document describing the method used to execute the query.
557 * @throws MongoDbException
558 * On an error finding the documents.
559 */
560 public Document explain(Find query) throws MongoDbException;
561
562 /**
563 * Explains the way that the query will be performed.
564 * <p>
565 * This is equivalent to calling {@link #explainAsync(Find)
566 * explainAsync(...).get()}
567 * </p>
568 *
569 * @param query
570 * The query details.
571 * @return The document describing the method used to execute the query.
572 * @throws MongoDbException
573 * On an error finding the documents.
574 */
575 public Document explain(Find.Builder query) throws MongoDbException;
576
577 /**
578 * Finds the set of documents matching the query document in the collection.
579 * <p>
580 * This is equivalent to calling {@link #findAsync(DocumentAssignable)
581 * findAsync(...).get()}
582 * </p>
583 *
584 * @param query
585 * The query document.
586 * @return The MongoIterator over the documents.
587 * @throws MongoDbException
588 * On an error finding the documents.
589 */
590 public MongoIterator<Document> find(DocumentAssignable query)
591 throws MongoDbException;
592
593 /**
594 * Finds the set of documents matching the query in the collection.
595 * <p>
596 * This is equivalent to calling {@link #findAsync(Find)
597 * findAsync(...).get()}
598 * </p>
599 *
600 * @param query
601 * The query details.
602 * @return The MongoIterator over the documents.
603 * @throws MongoDbException
604 * On an error finding the documents.
605 */
606 public MongoIterator<Document> find(Find query) throws MongoDbException;
607
608 /**
609 * Finds the set of documents matching the query in the collection.
610 * <p>
611 * This is equivalent to calling {@link #findAsync(Find)
612 * findAsync(...).get()}
613 * </p>
614 *
615 * @param query
616 * The query details.
617 * @return The MongoIterator over the documents.
618 * @throws MongoDbException
619 * On an error finding the documents.
620 */
621 public MongoIterator<Document> find(Find.Builder query)
622 throws MongoDbException;
623
624 /**
625 * Invokes a findAndModify command on the server. The <tt>query</tt> is used
626 * to locate a document to apply a set of <tt>update</tt>s to.
627 *
628 * @param command
629 * The details of the find and modify request.
630 * @return The found document.
631 * @throws MongoDbException
632 * On an error finding the documents.
633 */
634 public Document findAndModify(FindAndModify command)
635 throws MongoDbException;
636
637 /**
638 * Invokes a findAndModify command on the server. The <tt>query</tt> is used
639 * to locate a document to apply a set of <tt>update</tt>s to.
640 *
641 * @param command
642 * The details of the find and modify request.
643 * @return The found document.
644 * @throws MongoDbException
645 * On an error finding the documents.
646 */
647 public Document findAndModify(FindAndModify.Builder command)
648 throws MongoDbException;
649
650 /**
651 * Finds a single matching document in the collection.
652 *
653 * @param query
654 * The query document.
655 * @return The first found document.
656 * @throws MongoDbException
657 * On an error finding the document.
658 */
659 public Document findOne(DocumentAssignable query) throws MongoDbException;
660
661 /**
662 * Finds a single matching document in the collection.
663 * <p>
664 * Note that following options in the {@link Find} class do not make sense
665 * and are silently ignored by this method.
666 * <ul>
667 * <li> {@link Find#getBatchSize() Batch Size} - Automatically set to 1.</li>
668 * <li> {@link Find#getLimit() Limit} - Automatically set to 1.</li>
669 * <li> {@link Find#isTailable() Tailable} - This method only returns 1
670 * document.</li>
671 * </ul>
672 * </p>
673 *
674 * @param query
675 * The query details.
676 * @return The first found document.
677 * @throws MongoDbException
678 * On an error finding the document.
679 */
680 public Document findOne(Find query) throws MongoDbException;
681
682 /**
683 * Finds a single matching document in the collection.
684 * <p>
685 * Note that following options in the {@link Find} class do not make sense
686 * and are silently ignored by this method.
687 * <ul>
688 * <li> {@link Find#getBatchSize() Batch Size} - Automatically set to 1.</li>
689 * <li> {@link Find#getLimit() Limit} - Automatically set to 1.</li>
690 * <li> {@link Find#isTailable() Tailable} - This method only returns 1
691 * document.</li>
692 * </ul>
693 * </p>
694 *
695 * @param query
696 * The query details.
697 * @return The first found document.
698 * @throws MongoDbException
699 * On an error finding the document.
700 */
701 public Document findOne(Find.Builder query) throws MongoDbException;
702
703 /**
704 * Returns the name of the database.
705 *
706 * @return The name of the database.
707 */
708 public String getDatabaseName();
709
710 /**
711 * Returns the durability for write operations sent to the server from this
712 * {@link MongoCollection} instance.
713 * <p>
714 * Defaults to the {@link Durability} from the parent {@link MongoDatabase}
715 * instance.
716 * </p>
717 *
718 * @return The durability for write operations on the server.
719 *
720 * @see MongoDatabase#getDurability()
721 */
722 public Durability getDurability();
723
724 /**
725 * Returns the name of the collection.
726 *
727 * @return The name of the collection.
728 */
729 public String getName();
730
731 /**
732 * Returns the read preference for queries from this {@link MongoCollection}
733 * instance.
734 * <p>
735 * Defaults to {@link ReadPreference} from the parent {@link MongoDatabase}
736 * instance.
737 * </p>
738 *
739 * @return The default read preference for a query.
740 *
741 * @see MongoDatabase#getReadPreference()
742 */
743 public ReadPreference getReadPreference();
744
745 /**
746 * Invokes a group command on the server.
747 *
748 * @param command
749 * The details of the group request.
750 * @return The group results returned.
751 * @throws MongoDbException
752 * On an error finding the documents.
753 */
754 public MongoIterator<Element> groupBy(GroupBy command)
755 throws MongoDbException;
756
757 /**
758 * Invokes a group command on the server.
759 *
760 * @param command
761 * The details of the group request.
762 * @return The group results returned.
763 * @throws MongoDbException
764 * On an error finding the documents.
765 */
766 public MongoIterator<Element> groupBy(GroupBy.Builder command)
767 throws MongoDbException;
768
769 /**
770 * Inserts a set of documents into the collection.
771 * <p>
772 * This is equivalent to calling
773 * {@link #insertAsync(boolean, Durability, DocumentAssignable[])
774 * insertAsync(...).get()}
775 * </p>
776 *
777 * @param continueOnError
778 * If the insert should continue if one of the documents causes
779 * an error.
780 * @param documents
781 * The documents to add to the collection.
782 * @return Currently, returns zero. Once <a
783 * href="http://jira.mongodb.org/browse/SERVER-4381">SERVER-4381</a>
784 * is fixed then expected to return the number of documents
785 * inserted. If the durability is NONE then returns <code>-1</code>.
786 * @throws MongoDbException
787 * On an error inserting the documents.
788 */
789 public int insert(final boolean continueOnError,
790 DocumentAssignable... documents) throws MongoDbException;
791
792 /**
793 * Inserts a set of documents into the collection.
794 * <p>
795 * This is equivalent to calling
796 * {@link #insertAsync(boolean, Durability, DocumentAssignable[])
797 * insertAsync(...).get()}
798 * </p>
799 *
800 * @param continueOnError
801 * If the insert should continue if one of the documents causes
802 * an error.
803 * @param durability
804 * The durability for the insert.
805 * @param documents
806 * The documents to add to the collection.
807 * @return Currently, returns zero. Once <a
808 * href="http://jira.mongodb.org/browse/SERVER-4381">SERVER-4381</a>
809 * is fixed then expected to return the number of documents
810 * inserted. If the durability is NONE then returns <code>-1</code>.
811 * @throws MongoDbException
812 * On an error inserting the documents.
813 */
814 public int insert(final boolean continueOnError,
815 final Durability durability, DocumentAssignable... documents)
816 throws MongoDbException;
817
818 /**
819 * Inserts a set of documents into the collection.
820 * <p>
821 * This is equivalent to calling
822 * {@link #insertAsync(boolean, Durability, DocumentAssignable[])
823 * insertAsync(...).get()}
824 * </p>
825 *
826 * @param documents
827 * The documents to add to the collection.
828 * @return Currently, returns zero. Once <a
829 * href="http://jira.mongodb.org/browse/SERVER-4381">SERVER-4381</a>
830 * is fixed then expected to return the number of documents
831 * inserted. If the durability is NONE then returns <code>-1</code>.
832 * @throws MongoDbException
833 * On an error inserting the documents.
834 */
835 public int insert(DocumentAssignable... documents) throws MongoDbException;
836
837 /**
838 * Inserts a set of documents into the collection.
839 * <p>
840 * This is equivalent to calling
841 * {@link #insertAsync(boolean, Durability, DocumentAssignable[])
842 * insertAsync(...).get()}
843 * </p>
844 *
845 * @param durability
846 * The durability for the insert.
847 * @param documents
848 * The documents to add to the collection.
849 * @return Currently, returns zero. Once <a
850 * href="http://jira.mongodb.org/browse/SERVER-4381">SERVER-4381</a>
851 * is fixed then expected to return the number of documents
852 * inserted. If the durability is NONE then returns <code>-1</code>.
853 * @throws MongoDbException
854 * On an error inserting the documents.
855 */
856 public int insert(final Durability durability,
857 DocumentAssignable... documents) throws MongoDbException;
858
859 /**
860 * Returns true if the collection {@link #stats() statistics} indicate that
861 * the collection is a capped collection.
862 *
863 * @return True if the collection {@link #stats() statistics} indicate that
864 * the collection is a capped collection.
865 * @throws MongoDbException
866 * On an error collecting the collection statistics.
867 */
868 public boolean isCapped() throws MongoDbException;
869
870 /**
871 * Invokes a mapReduce command on the server.
872 *
873 * @param command
874 * The details of the map/reduce request.
875 * @return The map/reduce results returned. Note this might be empty if the
876 * output type is not inline.
877 * @throws MongoDbException
878 * On an error finding the documents.
879 */
880 public MongoIterator<Document> mapReduce(MapReduce command)
881 throws MongoDbException;
882
883 /**
884 * Invokes a mapReduce command on the server.
885 *
886 * @param command
887 * The details of the map/reduce request.
888 * @return The map/reduce results returned. Note this might be empty if the
889 * output type is not inline.
890 * @throws MongoDbException
891 * On an error finding the documents.
892 */
893 public MongoIterator<Document> mapReduce(MapReduce.Builder command)
894 throws MongoDbException;
895
896 /**
897 * Uses the {@code parallelCollectionScan} command to open multiple
898 * iterators over the collection each configured to scan a distinct regions
899 * of the collection. You may then use a separate thread to scan each region
900 * of the collection in parallel.
901 *
902 * @param parallelScan
903 * The details on the scan.
904 * @return The collection of iterators.
905 * @throws MongoDbException
906 * On an error initializing the parallel scan.
907 *
908 * @see <a
909 * href="http://docs.mongodb.org/manual/reference/command/parallelCollectionScan/">parallelCollectionScan
910 * Command</a>
911 */
912 public Collection<MongoIterator<Document>> parallelScan(
913 ParallelScan parallelScan) throws MongoDbException;
914
915 /**
916 * Uses the {@code parallelCollectionScan} command to open multiple
917 * iterators over the collection each configured to scan a distinct regions
918 * of the collection. You may then use a separate thread to scan each region
919 * of the collection in parallel.
920 *
921 * @param parallelScan
922 * The details on the scan.
923 * @return The collection of iterators.
924 * @throws MongoDbException
925 * On an error initializing the parallel scan.
926 *
927 * @see <a
928 * href="http://docs.mongodb.org/manual/reference/command/parallelCollectionScan/">parallelCollectionScan
929 * Command</a>
930 */
931 public Collection<MongoIterator<Document>> parallelScan(
932 ParallelScan.Builder parallelScan) throws MongoDbException;
933
934 /**
935 * Saves the {@code document} to the collection.
936 * <p>
937 * If the {@code document} does not contain an {@code _id} field then this
938 * method is equivalent to: {@link #insert(DocumentAssignable...)
939 * insert(document)}.
940 * </p>
941 * <p>
942 * If the {@code document} does contain an {@code _id} field then this
943 * method is equivalent to:
944 * {@link #update(DocumentAssignable, DocumentAssignable, boolean, boolean)
945 * update(BuilderFactory.start().add(document.get("_id")), document, false,
946 * true)}.
947 * </p>
948 *
949 * @param document
950 * The document to save to the collection.
951 * @return ListenableFuture that will be updated with the results of the
952 * save. If the durability of the operation is NONE then this will
953 * be -1.
954 * @throws MongoDbException
955 * On an error saving the documents.
956 */
957 public int save(DocumentAssignable document) throws MongoDbException;
958
959 /**
960 * Saves the {@code document} to the collection.
961 * <p>
962 * If the {@code document} does not contain an {@code _id} field then this
963 * method is equivalent to:
964 * {@link #insert(Durability, DocumentAssignable...) insert(durability,
965 * document)}.
966 * </p>
967 * <p>
968 * If the {@code document} does contain an {@code _id} field then this
969 * method is equivalent to:
970 * {@link #update(DocumentAssignable, DocumentAssignable, boolean, boolean, Durability)
971 * update(BuilderFactory.start().add(document.get("_id")), document, false,
972 * true, durability)}.
973 * </p>
974 *
975 * @param document
976 * The document to save to the collection.
977 * @param durability
978 * The durability for the save.
979 * @return ListenableFuture that will be updated with the results of the
980 * save. If the durability of the operation is NONE then this will
981 * be -1.
982 * @throws MongoDbException
983 * On an error saving the documents.
984 */
985 public int save(DocumentAssignable document, Durability durability)
986 throws MongoDbException;
987
988 /**
989 * Sets the durability for write operations from this
990 * {@link MongoCollection} instance.
991 * <p>
992 * Defaults to the {@link Durability} from the parent {@link MongoDatabase}
993 * instance if set to <code>null</code>.
994 * </p>
995 *
996 * @param durability
997 * The durability for write operations on the server.
998 *
999 * @see MongoDatabase#getDurability()
1000 */
1001 public void setDurability(final Durability durability);
1002
1003 /**
1004 * Sets the value of the read preference for a queries from this
1005 * {@link MongoCollection} instance.
1006 * <p>
1007 * Defaults to the {@link ReadPreference} from the parent
1008 * {@link MongoDatabase} instance if set to <code>null</code>.
1009 * </p>
1010 *
1011 * @param readPreference
1012 * The read preference for a query.
1013 *
1014 * @see MongoDatabase#getReadPreference()
1015 */
1016 public void setReadPreference(final ReadPreference readPreference);
1017
1018 /**
1019 * Starts a batch of requests to the server. The returned object will not
1020 * submit any requests to the server until the batch is closed.
1021 *
1022 * @return The interface for submitting batched requests. The
1023 * {@link BatchedAsyncMongoCollection#close()} method must be called
1024 * to submit the batch of requests.
1025 */
1026 public BatchedAsyncMongoCollection startBatch();
1027
1028 /**
1029 * Returns the statistics for the collection.
1030 *
1031 * @return The results document with the collection statistics.
1032 * @throws MongoDbException
1033 * On an error collecting the collection statistics.
1034 * @see <a
1035 * href="http://docs.mongodb.org/manual/reference/command/collStats/">collStats
1036 * Command Reference</a>
1037 */
1038 public Document stats() throws MongoDbException;
1039
1040 /**
1041 * Invokes a {@code text} command on the server.
1042 *
1043 * @param command
1044 * The details of the {@code text} request.
1045 * @return The {@code text} results returned.
1046 * @throws MongoDbException
1047 * On an error executing the {@code text} command.
1048 * @see <a
1049 * href="http://docs.mongodb.org/manual/release-notes/2.4/#text-queries">
1050 * MongoDB Text Queries</a>
1051 * @since MongoDB 2.4
1052 * @deprecated Support for the {@code text} command was deprecated in the
1053 * 2.6 version of MongoDB. Use the
1054 * {@link ConditionBuilder#text(String) $text} query operator
1055 * instead. This method will not be removed until two releases
1056 * after the MongoDB 2.6 release (e.g. 2.10 if the releases are
1057 * 2.8 and 2.10).
1058 */
1059 @Deprecated
1060 public MongoIterator<com.allanbank.mongodb.builder.TextResult> textSearch(
1061 com.allanbank.mongodb.builder.Text command) throws MongoDbException;
1062
1063 /**
1064 * Invokes a {@code text} command on the server.
1065 *
1066 * @param command
1067 * The details of the {@code text} request.
1068 * @return The {@code text} results returned.
1069 * @throws MongoDbException
1070 * On an error executing the {@code text} command.
1071 * @see <a
1072 * href="http://docs.mongodb.org/manual/release-notes/2.4/#text-queries">
1073 * MongoDB Text Queries</a>
1074 * @since MongoDB 2.4
1075 * @deprecated Support for the {@code text} command was deprecated in the
1076 * 2.6 version of MongoDB. Use the
1077 * {@link ConditionBuilder#text(String) $text} query operator
1078 * instead. This method will not be removed until two releases
1079 * after the MongoDB 2.6 release (e.g. 2.10 if the releases are
1080 * 2.8 and 2.10).
1081 */
1082 @Deprecated
1083 public MongoIterator<com.allanbank.mongodb.builder.TextResult> textSearch(
1084 com.allanbank.mongodb.builder.Text.Builder command)
1085 throws MongoDbException;
1086
1087 /**
1088 * Applies updates to a set of documents within the collection. The
1089 * documents to update are selected by the <tt>query</tt> and the updates
1090 * are describe by the <tt>update</tt> document.
1091 *
1092 * @param query
1093 * The query to select the documents to update.
1094 * @param update
1095 * The updates to apply to the selected documents.
1096 * @return The number of documents updated. If the durability of the
1097 * operation is NONE then this will be -1.
1098 * @throws MongoDbException
1099 * On an error updating the documents.
1100 */
1101 public long update(DocumentAssignable query, DocumentAssignable update)
1102 throws MongoDbException;
1103
1104 /**
1105 * Applies updates to a set of documents within the collection. The
1106 * documents to update are selected by the <tt>query</tt> and the updates
1107 * are describe by the <tt>update</tt> document.
1108 *
1109 * @param query
1110 * The query to select the documents to update.
1111 * @param update
1112 * The updates to apply to the selected documents.
1113 * @param multiUpdate
1114 * If true then the update is applied to all of the matching
1115 * documents, otherwise only the first document found is updated.
1116 * @param upsert
1117 * If true then if no document is found then a new document is
1118 * created and updated, otherwise no operation is performed.
1119 * @return The number of documents updated. If the durability of the
1120 * operation is NONE then this will be -1.
1121 * @throws MongoDbException
1122 * On an error updating the documents.
1123 */
1124 public long update(DocumentAssignable query, DocumentAssignable update,
1125 final boolean multiUpdate, final boolean upsert)
1126 throws MongoDbException;
1127
1128 /**
1129 * Applies updates to a set of documents within the collection. The
1130 * documents to update are selected by the <tt>query</tt> and the updates
1131 * are describe by the <tt>update</tt> document.
1132 *
1133 * @param query
1134 * The query to select the documents to update.
1135 * @param update
1136 * The updates to apply to the selected documents.
1137 * @param multiUpdate
1138 * If true then the update is applied to all of the matching
1139 * documents, otherwise only the first document found is updated.
1140 * @param upsert
1141 * If true then if no document is found then a new document is
1142 * created and updated, otherwise no operation is performed.
1143 * @param durability
1144 * The durability for the insert.
1145 * @return The number of documents updated. If the durability of the
1146 * operation is NONE then this will be -1.
1147 * @throws MongoDbException
1148 * On an error updating the documents.
1149 */
1150 public long update(DocumentAssignable query, DocumentAssignable update,
1151 final boolean multiUpdate, final boolean upsert,
1152 final Durability durability) throws MongoDbException;
1153
1154 /**
1155 * Applies updates to a set of documents within the collection. The
1156 * documents to update are selected by the <tt>query</tt> and the updates
1157 * are describe by the <tt>update</tt> document.
1158 *
1159 * @param query
1160 * The query to select the documents to update.
1161 * @param update
1162 * The updates to apply to the selected documents.
1163 * @param durability
1164 * The durability for the update.
1165 * @return The number of documents updated. If the durability of the
1166 * operation is NONE then this will be -1.
1167 * @throws MongoDbException
1168 * On an error updating the documents.
1169 */
1170 public long update(DocumentAssignable query, DocumentAssignable update,
1171 final Durability durability) throws MongoDbException;
1172
1173 /**
1174 * Updates the collection's options or flags using the {@code collMod}
1175 * command. The return value is the response from the MongoDB server and
1176 * normally contains a <code><name>_old</code> field for each
1177 * successfully set option on the collection. <blockquote>
1178 *
1179 * <pre>
1180 * <code>
1181 * MongoCollection collection = ...;
1182 *
1183 * collection.updateOptions( BuilderFactory.start().add( "usePowerOf2Sizes", true ) );
1184 * </code>
1185 * </pre>
1186 *
1187 * </blockquote>
1188 *
1189 * @param options
1190 * The collection options to be set.
1191 * @return The results document from the database.
1192 * @throws MongoDbException
1193 * On an error validating the collection.
1194 * @see <a
1195 * href="http://docs.mongodb.org/manual/reference/command/collMod/">collMod
1196 * Command Reference</a>
1197 */
1198 public Document updateOptions(DocumentAssignable options)
1199 throws MongoDbException;
1200
1201 /**
1202 * Validates the collections contents.
1203 *
1204 * @param mode
1205 * The validation mode to use.
1206 * @return The results document from the database.
1207 * @throws MongoDbException
1208 * On an error validating the collection.
1209 * @see <a
1210 * href="http://docs.mongodb.org/manual/reference/command/validate/">validate
1211 * Command Reference</a>
1212 */
1213 public Document validate(ValidateMode mode) throws MongoDbException;
1214
1215 /**
1216 * Constructs the appropriate set of write commands to send to the server.
1217 * <p>
1218 * If connected to a cluster where all servers can accept write commands
1219 * then the operations will be sent to the server using the write commands.
1220 * If the cluster does not support the write command then the operations
1221 * will be converted to a series of native write operations.
1222 * </p>
1223 * <p>
1224 * Since this method may use the write commands a {@link Durability} of
1225 * {@link Durability#NONE} will be changed to {@link Durability#ACK}.
1226 * </p>
1227 *
1228 * @param write
1229 * The batched writes
1230 * @return The results of the inserts, updates, and deletes. If this method
1231 * falls back to the native write commands then the notice for the
1232 * {@code return} for the {@link #insert(DocumentAssignable...)}
1233 * method applies.
1234 * @throws MongoDbException
1235 * On an error submitting the write operations.
1236 *
1237 * @since MongoDB 2.6
1238 * @see BatchedWrite#REQUIRED_VERSION
1239 */
1240 public long write(final BatchedWrite write) throws MongoDbException;
1241
1242 /**
1243 * Constructs the appropriate set of write commands to send to the server.
1244 * <p>
1245 * If connected to a cluster where all servers can accept write commands
1246 * then the operations will be sent to the server using the write commands.
1247 * If the cluster does not support the write command then the operations
1248 * will be converted to a series of native write operations.
1249 * </p>
1250 * <p>
1251 * Since this method may use the write commands a {@link Durability} of
1252 * {@link Durability#NONE} will be changed to {@link Durability#ACK}.
1253 * </p>
1254 *
1255 * @param write
1256 * The batched writes
1257 * @return The results of the inserts, updates, and deletes. If this method
1258 * falls back to the native write commands then the notice for the
1259 * {@code return} for the {@link #insert(DocumentAssignable...)}
1260 * method applies.
1261 * @throws MongoDbException
1262 * On an error submitting the write operations.
1263 *
1264 * @since MongoDB 2.6
1265 * @see BatchedWrite#REQUIRED_VERSION
1266 */
1267 public long write(final BatchedWrite.Builder write) throws MongoDbException;
1268
1269 /**
1270 * ValidateMode provides an enumeration of the validation modes.
1271 *
1272 * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
1273 */
1274 public static enum ValidateMode {
1275
1276 /** Validates the data and indexes performing all checks. */
1277 FULL,
1278
1279 /** Validates the indexes only and not the collection data. */
1280 INDEX_ONLY,
1281
1282 /** Validates the data and indexes but skips some checks. */
1283 NORMAL;
1284 }
1285 }