View Javadoc
1   /*
2    * #%L
3    * BatchedAsyncMongoCollection.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.io.Closeable;
23  
24  import com.allanbank.mongodb.builder.BatchedWriteMode;
25  
26  /**
27   * BatchedAsyncMongoCollection provides the interface for submitting batched
28   * requests to the MongoDB server. The behavior of the batching is different
29   * based on the lowest version member of the MongoDB cluster.
30   * 
31   * <h4>Pre MongoDB 2.6</h4>
32   * <p>
33   * For MongoDB servers prior to 2.6 each command is sent to the server exactly
34   * as it would have been using the non-batched interface except that the
35   * commands are sent using a single logical connection. Queries using different,
36   * non-primary, {@link ReadPreference}s may use different physical connections.
37   * </p>
38   * 
39   * <h4>Post MongoDB 2.6</h4>
40   * <p>
41   * With the introduction of commands to batch inserts, updates and deletes we
42   * can now group each sequence of inserts, updates, and deletes within the
43   * batch. The actual logic for what writes can be grouped together is controlled
44   * by the {@link #setMode(BatchedWriteMode) mode}. Users should be sure that
45   * they have read and understand the {@link #setMode(BatchedWriteMode)} JavaDoc.
46   * Similar to the pre-2.6 case all of the operations are sent using a single
47   * logical connection. Queries using different, non-primary,
48   * {@link ReadPreference}s may use different physical connections.
49   * </p>
50   * <p>
51   * <b>Warning</b>: In the case of
52   * {@link BatchedWriteMode#SERIALIZE_AND_CONTINUE} and
53   * {@link BatchedWriteMode#REORDERED} it is impossible to determine the number
54   * of documents each update and/or delete touched. In these cases each update in
55   * the batch will be returned the number of documents touched by the batch as a
56   * whole. For this reason the batching of updates and deletes is disabled. It
57   * can be enabled by setting {@link #setBatchUpdates(boolean)} and
58   * {@link #setBatchDeletes(boolean)} to true. We have written a bug report (<a
59   * href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>) to have
60   * the additional information added to the responses so we can remove this
61   * restriction.
62   * </p>
63   * 
64   * @api.yes This interface is part of the driver's API. Public and protected
65   *          members will be deprecated for at least 1 non-bugfix release
66   *          (version numbers are &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;)
67   *          before being removed or modified.
68   * @copyright 2014, Allanbank Consulting, Inc., All Rights Reserved
69   * 
70   * @see AsyncMongoCollection
71   * @see MongoCollection
72   */
73  public interface BatchedAsyncMongoCollection extends AsyncMongoCollection,
74          Closeable {
75      /**
76       * Cancels the pending batch of operations without sending them to the
77       * server.
78       * <p>
79       * After canceling the current batch you may continue to accumulate
80       * additional operations to be sent in a different batch.
81       * </p>
82       * 
83       * @throws MongoDbException
84       *             If there is an error submitting the batched requests.
85       */
86      public void cancel() throws MongoDbException;
87  
88      /**
89       * Flushes the pending batch and submits all of the pending requests to the
90       * server.
91       * <p>
92       * This method is equivalent to {@link #flush()} and is only provided to
93       * implement the {@link Closeable} interface to support try-with-resource.
94       * </p>
95       * 
96       * @throws MongoDbException
97       *             If there is an error submitting the batched requests.
98       */
99      @Override
100     public void close() throws MongoDbException;
101 
102     /**
103      * Flushes the pending batch and submits all of the pending requests to the
104      * server.
105      * <p>
106      * After flushing the current batch you may continue to accumulate
107      * additional operations to be sent in a different batch.
108      * </p>
109      * 
110      * @throws MongoDbException
111      *             If there is an error submitting the batched requests.
112      */
113     public void flush() throws MongoDbException;
114 
115     /**
116      * Sets if deletes should be batched. Set to true to batch deletes.
117      * <p>
118      * Defaults to false since there is no way to determine how many documents
119      * each deletes removed when they are batched.
120      * </p>
121      * <p>
122      * This setting takes effect for a batch when it is {@link #close() closed}
123      * or {@link #flush() flushed}. Intermediate changes between flushes have no
124      * effect.
125      * </p>
126      * 
127      * @param batchDeletes
128      *            Set to true to batch deletes.
129      * @see <a
130      *      href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>
131      */
132     public void setBatchDeletes(boolean batchDeletes);
133 
134     /**
135      * Sets if updates should be batched. Set to true to batch updates.
136      * <p>
137      * Defaults to false since there is no way to determine how many documents
138      * each update touched when they are batched.
139      * </p>
140      * <p>
141      * This setting takes effect for a batch when it is {@link #close() closed}
142      * or {@link #flush() flushed}. Intermediate changes between flushes have no
143      * effect.
144      * </p>
145      * 
146      * @param batchUpdates
147      *            Set to true to batch updates.
148      * @see <a
149      *      href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>
150      */
151     public void setBatchUpdates(boolean batchUpdates);
152 
153     /**
154      * Sets the default mode for batching of writes. This is only applicable to
155      * situations where the server supports the MongoDB write command (i.e.,
156      * version 2.6 and later). There are two cases where the mode will be
157      * ignored:
158      * <ul>
159      * <li>
160      * All inserts with continueOnError set to true will be executed as distinct
161      * batches.</li>
162      * <li>
163      * Any change in the durability within the sequence of writes will case the
164      * writes to be broken across batches sent to the server. This does not
165      * apply to {@link Durability#ACK} and {@link Durability#NONE} writes and
166      * they may be grouped with other writes. Users should be aware that this
167      * may cause unexpected write concern failures in those cases.</li>
168      * </ul>
169      * <p>
170      * The default mode is {@link BatchedWriteMode#SERIALIZE_AND_CONTINUE}. This
171      * provides reasonable performance while maintaining the expected semantics.
172      * Note that this mode has the effect of coalescing sequences of inserts
173      * (where continueOnError is true), updates and deletes into single
174      * operations.
175      * </p>
176      * <p>
177      * The {@link BatchedWriteMode#SERIALIZE_AND_STOP} will cause each insert,
178      * update, and delete to be sent as independent commands.
179      * </p>
180      * <p>
181      * The {@link BatchedWriteMode#REORDERED} will cause each sequence of
182      * inserts, updates, and deletes without any other command or query to be
183      * groups together, reordered, and executed together. This includes the
184      * reordering writes within a type (one insert before another to better
185      * packet the messages) as well as reordering the writes across types (a
186      * delete before an insert to build larger batches).
187      * </p>
188      * <p>
189      * The mode setting takes effect for a batch when it is {@link #close()
190      * closed} or {@link #flush() flushed}. Intermediate changes between flushes
191      * have no effect.
192      * </p>
193      * <p>
194      * <b>Warning</b>: In the case of
195      * {@link BatchedWriteMode#SERIALIZE_AND_CONTINUE} and
196      * {@link BatchedWriteMode#REORDERED} it is impossible to determine the
197      * number of documents each update and/or delete touched. In these cases
198      * each update in the batch will be returned the number of documents touched
199      * by the batch as a whole. For this reason the batching of updates and
200      * deletes is disabled. It can be enabled by setting
201      * {@link #setBatchUpdates(boolean)} and {@link #setBatchDeletes(boolean)}
202      * to true. We have written a bug report (<a
203      * href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>) to
204      * have the additional information added to the responses so we can remove
205      * this restriction.
206      * </p>
207      * 
208      * @param mode
209      *            The default mode for
210      * @see <a
211      *      href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>
212      */
213     public void setMode(BatchedWriteMode mode);
214 }