Coverage Report

Coverage Report - com.allanbank.mongodb.BatchedAsyncMongoCollection

Classes in this File

 /*
  * #%L
  * BatchedAsyncMongoCollection.java - mongodb-async-driver - Allanbank Consulting, Inc.
  * %%
  * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  * 
  *      http://www.apache.org/licenses/LICENSE-2.0
  * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  * #L%
  */
 package com.allanbank.mongodb;
 
 import java.io.Closeable;
 
 import com.allanbank.mongodb.builder.BatchedWriteMode;
 
 /**
  * BatchedAsyncMongoCollection provides the interface for submitting batched
  * requests to the MongoDB server. The behavior of the batching is different
  * based on the lowest version member of the MongoDB cluster.
  * 
  * <h4>Pre MongoDB 2.6</h4>
  * <p>
  * For MongoDB servers prior to 2.6 each command is sent to the server exactly
  * as it would have been using the non-batched interface except that the
  * commands are sent using a single logical connection. Queries using different,
  * non-primary, {@link ReadPreference}s may use different physical connections.
  * </p>
  * 
  * <h4>Post MongoDB 2.6</h4>
  * <p>
  * With the introduction of commands to batch inserts, updates and deletes we
  * can now group each sequence of inserts, updates, and deletes within the
  * batch. The actual logic for what writes can be grouped together is controlled
  * by the {@link #setMode(BatchedWriteMode) mode}. Users should be sure that
  * they have read and understand the {@link #setMode(BatchedWriteMode)} JavaDoc.
  * Similar to the pre-2.6 case all of the operations are sent using a single
  * logical connection. Queries using different, non-primary,
  * {@link ReadPreference}s may use different physical connections.
  * </p>
  * <p>
  * <b>Warning</b>: In the case of
  * {@link BatchedWriteMode#SERIALIZE_AND_CONTINUE} and
  * {@link BatchedWriteMode#REORDERED} it is impossible to determine the number
  * of documents each update and/or delete touched. In these cases each update in
  * the batch will be returned the number of documents touched by the batch as a
  * whole. For this reason the batching of updates and deletes is disabled. It
  * can be enabled by setting {@link #setBatchUpdates(boolean)} and
  * {@link #setBatchDeletes(boolean)} to true. We have written a bug report (<a
  * href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>) to have
  * the additional information added to the responses so we can remove this
  * restriction.
  * </p>
  * 
  * @api.yes This interface is part of the driver's API. Public and protected
  *          members will be deprecated for at least 1 non-bugfix release
  *          (version numbers are &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;)
  *          before being removed or modified.
  * @copyright 2014, Allanbank Consulting, Inc., All Rights Reserved
  * 
  * @see AsyncMongoCollection
  * @see MongoCollection
  */
 public interface BatchedAsyncMongoCollection extends AsyncMongoCollection,
         Closeable {
     /**
      * Cancels the pending batch of operations without sending them to the
      * server.
      * <p>
      * After canceling the current batch you may continue to accumulate
      * additional operations to be sent in a different batch.
      * </p>
      * 
      * @throws MongoDbException
      *             If there is an error submitting the batched requests.
      */
     public void cancel() throws MongoDbException;
 
     /**
      * Flushes the pending batch and submits all of the pending requests to the
      * server.
      * <p>
      * This method is equivalent to {@link #flush()} and is only provided to
      * implement the {@link Closeable} interface to support try-with-resource.
      * </p>
      * 
      * @throws MongoDbException
      *             If there is an error submitting the batched requests.
      */
     @Override
     public void close() throws MongoDbException;
 
     /**
      * Flushes the pending batch and submits all of the pending requests to the
      * server.
      * <p>
      * After flushing the current batch you may continue to accumulate
      * additional operations to be sent in a different batch.
      * </p>
      * 
      * @throws MongoDbException
      *             If there is an error submitting the batched requests.
      */
     public void flush() throws MongoDbException;
 
     /**
      * Sets if deletes should be batched. Set to true to batch deletes.
      * <p>
      * Defaults to false since there is no way to determine how many documents
      * each deletes removed when they are batched.
      * </p>
      * <p>
      * This setting takes effect for a batch when it is {@link #close() closed}
      * or {@link #flush() flushed}. Intermediate changes between flushes have no
      * effect.
      * </p>
      * 
      * @param batchDeletes
      *            Set to true to batch deletes.
      * @see <a
      *      href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>
      */
     public void setBatchDeletes(boolean batchDeletes);
 
     /**
      * Sets if updates should be batched. Set to true to batch updates.
      * <p>
      * Defaults to false since there is no way to determine how many documents
      * each update touched when they are batched.
      * </p>
      * <p>
      * This setting takes effect for a batch when it is {@link #close() closed}
      * or {@link #flush() flushed}. Intermediate changes between flushes have no
      * effect.
      * </p>
      * 
      * @param batchUpdates
      *            Set to true to batch updates.
      * @see <a
      *      href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>
      */
     public void setBatchUpdates(boolean batchUpdates);
 
     /**
      * Sets the default mode for batching of writes. This is only applicable to
      * situations where the server supports the MongoDB write command (i.e.,
      * version 2.6 and later). There are two cases where the mode will be
      * ignored:
      * <ul>
      * <li>
      * All inserts with continueOnError set to true will be executed as distinct
      * batches.</li>
      * <li>
      * Any change in the durability within the sequence of writes will case the
      * writes to be broken across batches sent to the server. This does not
      * apply to {@link Durability#ACK} and {@link Durability#NONE} writes and
      * they may be grouped with other writes. Users should be aware that this
      * may cause unexpected write concern failures in those cases.</li>
      * </ul>
      * <p>
      * The default mode is {@link BatchedWriteMode#SERIALIZE_AND_CONTINUE}. This
      * provides reasonable performance while maintaining the expected semantics.
      * Note that this mode has the effect of coalescing sequences of inserts
      * (where continueOnError is true), updates and deletes into single
      * operations.
      * </p>
      * <p>
      * The {@link BatchedWriteMode#SERIALIZE_AND_STOP} will cause each insert,
      * update, and delete to be sent as independent commands.
      * </p>
      * <p>
      * The {@link BatchedWriteMode#REORDERED} will cause each sequence of
      * inserts, updates, and deletes without any other command or query to be
      * groups together, reordered, and executed together. This includes the
      * reordering writes within a type (one insert before another to better
      * packet the messages) as well as reordering the writes across types (a
      * delete before an insert to build larger batches).
      * </p>
      * <p>
      * The mode setting takes effect for a batch when it is {@link #close()
      * closed} or {@link #flush() flushed}. Intermediate changes between flushes
      * have no effect.
      * </p>
      * <p>
      * <b>Warning</b>: In the case of
      * {@link BatchedWriteMode#SERIALIZE_AND_CONTINUE} and
      * {@link BatchedWriteMode#REORDERED} it is impossible to determine the
      * number of documents each update and/or delete touched. In these cases
      * each update in the batch will be returned the number of documents touched
      * by the batch as a whole. For this reason the batching of updates and
      * deletes is disabled. It can be enabled by setting
      * {@link #setBatchUpdates(boolean)} and {@link #setBatchDeletes(boolean)}
      * to true. We have written a bug report (<a
      * href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>) to
      * have the additional information added to the responses so we can remove
      * this restriction.
      * </p>
      * 
      * @param mode
      *            The default mode for
      * @see <a
      *      href="https://jira.mongodb.org/browse/SERVER-12858">SERVER-12858</a>
      */
     public void setMode(BatchedWriteMode mode);
 }

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 <major>.<minor>.<bugfix>)
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		}