View Javadoc
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 &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;)
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>&lt;name&gt;_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 }