DATAMONGO-934 - Polishing.

Polished JavaDoc and implementation as well as tests. Extracted Tuple to Spring Data Commons. Moved exception translation into MongoExceptionTranslator.

Changed implementation of DefaultBulkOperations to consider the WriteConcernResolver of the underlying MongoTemplate to avoid exposing the WriteConcern on execution.

Original pull request: spring-projects#327.
Related tickets: DATACMNS-790.

Author: odrotbohm

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/BulkOperationException.java

@@ -27,16 +27,28 @@
  * Is thrown when errors occur during bulk operations.
  * 
  * @author Tobias Trelle
+ * @author Oliver Gierke
+ * @since 1.9
  */
 public class BulkOperationException extends DataAccessException {
+
 	private static final long serialVersionUID = 73929601661154421L;
+
 	private final List<BulkWriteError> errors;
 	private final BulkWriteResult result;
-	
-	public BulkOperationException(String msg, BulkWriteException e) {
-		super(msg, e);
-		this.errors = e.getWriteErrors();
-		this.result = e.getWriteResult();
+
+	/**
+	 * Creates a new {@link BulkOperationException} with the given message and source {@link BulkWriteException}.
+	 * 
+	 * @param message must not be {@literal null}.
+	 * @param source must not be {@literal null}.
+	 */
+	public BulkOperationException(String message, BulkWriteException source) {
+
+		super(message, source);
+
+		this.errors = source.getWriteErrors();
+		this.result = source.getWriteResult();
 	}
 
 	public List<BulkWriteError> getErrors() {
@@ -46,5 +58,4 @@ public List<BulkWriteError> getErrors() {
 	public BulkWriteResult getResult() {
 		return result;
 	}
-	
 }

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/BulkOperations.java

@@ -17,26 +17,27 @@
 
 import java.util.List;
 
-import org.springframework.data.mongodb.BulkOperationException;
 import org.springframework.data.mongodb.core.query.Query;
 import org.springframework.data.mongodb.core.query.Update;
-import org.springframework.data.mongodb.util.Tuple;
+import org.springframework.data.util.Tuple;
 
 import com.mongodb.BulkWriteResult;
-import com.mongodb.WriteConcern;
 
 /**
- * Bulk operations for insert/update/remove actions on a collection.
- * <p/>
- * These bulks operation are available since MongoDB 2.6 and make use of low level bulk commands on the protocol level.
- * <p/>
- * This interface defines a fluent API add multiple single operations or list of similar operations in sequence.
+ * Bulk operations for insert/update/remove actions on a collection. These bulks operation are available since MongoDB
+ * 2.6 and make use of low level bulk commands on the protocol level. This interface defines a fluent API to add
+ * multiple single operations or list of similar operations in sequence which can then eventually be executed by calling
+ * {@link #execute()}.
  * 
  * @author Tobias Trelle
+ * @author Oliver Gierke
+ * @since 1.9
  */
 public interface BulkOperations {
 
-	/** Mode for bulk operation. */
+	/**
+	 * Mode for bulk operation.
+	 **/
 	public enum BulkMode {
 
 		/** Perform bulk operations in sequence. The first error will cancel processing. */
@@ -45,44 +46,37 @@ public enum BulkMode {
 		/** Perform bulk operations in parallel. Processing will continue on errors. */
 		UNORDERED
 	};
+
 	/**
 	 * Add a single insert to the bulk operation.
 	 * 
-	 * @param documents List of documents to insert.
-	 * 
-	 * @return The bulk operation.
-	 * 
-	 * @throws BulkOperationException if an error occured during bulk processing.
+	 * @param documents the document to insert, must not be {@literal null}.
+	 * @return the current {@link BulkOperations} instance with the insert added, will never be {@literal null}.
 	 */
-	BulkOperations insert(Object documents);	
-	
+	BulkOperations insert(Object documents);
+
 	/**
 	 * Add a list of inserts to the bulk operation.
 	 * 
-	 * @param documents List of documents to insert.
-	 * 
-	 * @return The bulk operation.
-	 * 
-	 * @throws BulkOperationException if an error occured during bulk processing.
+	 * @param documents List of documents to insert, must not be {@literal null}.
+	 * @return the current {@link BulkOperations} instance with the insert added, will never be {@literal null}.
 	 */
 	BulkOperations insert(List<? extends Object> documents);
 
 	/**
-	 * Add a single update to the bulk operation.	For the update request, only the first matching document is updated.
+	 * Add a single update to the bulk operation. For the update request, only the first matching document is updated.
 	 * 
-	 * @param query Update criteria.
-	 * @param update Update operation to perform.
-	 * 
-	 * @return The bulk operation.
+	 * @param query update criteria, must not be {@literal null}.
+	 * @param update {@link Update} operation to perform, must not be {@literal null}.
+	 * @return the current {@link BulkOperations} instance with the update added, will never be {@literal null}.
 	 */
-	BulkOperations updateOne(Query query, Update update);	
-	
+	BulkOperations updateOne(Query query, Update update);
+
 	/**
-	 * Add a list of updates to the bulk operation.	For each update request, only the first matching document is updated.
+	 * Add a list of updates to the bulk operation. For each update request, only the first matching document is updated.
 	 * 
 	 * @param updates Update operations to perform.
-	 * 
-	 * @return The bulk operation.
+	 * @return the current {@link BulkOperations} instance with the update added, will never be {@literal null}.
 	 */
 	BulkOperations updateOne(List<Tuple<Query, Update>> updates);
 
@@ -91,17 +85,16 @@ public enum BulkMode {
 	 * 
 	 * @param query Update criteria.
 	 * @param update Update operation to perform.
-	 *  
-	 * @return The bulk operation.
+	 * @return the current {@link BulkOperations} instance with the update added, will never be {@literal null}.
 	 */
 	BulkOperations updateMulti(Query query, Update update);
-	
+
 	/**
 	 * Add a list of updates to the bulk operation. For each update request, all matching documents are updated.
 	 * 
 	 * @param updates Update operations to perform.
-	 * 
 	 * @return The bulk operation.
+	 * @return the current {@link BulkOperations} instance with the update added, will never be {@literal null}.
 	 */
 	BulkOperations updateMulti(List<Tuple<Query, Update>> updates);
 
@@ -111,57 +104,42 @@ public enum BulkMode {
 	 * 
 	 * @param query Update criteria.
 	 * @param update Update operation to perform.
-	 * 
 	 * @return The bulk operation.
+	 * @return the current {@link BulkOperations} instance with the update added, will never be {@literal null}.
 	 */
-	BulkOperations upsert(Query query, Update update);	
-	
+	BulkOperations upsert(Query query, Update update);
+
 	/**
-	 * Add a list of upserts to the bulk operation. An upsert is an update if the set of matching documents is not empty, else an
-	 * insert.
+	 * Add a list of upserts to the bulk operation. An upsert is an update if the set of matching documents is not empty,
+	 * else an insert.
 	 * 
 	 * @param updates Updates/insert operations to perform.
-	 * 
 	 * @return The bulk operation.
+	 * @return the current {@link BulkOperations} instance with the update added, will never be {@literal null}.
 	 */
 	BulkOperations upsert(List<Tuple<Query, Update>> updates);
 
 	/**
 	 * Add a single remove operation to the bulk operation.
 	 * 
-	 * @param remove operations to perform.
-	 * 
-	 * @return The bulk operation.
+	 * @param remove the {@link Query} to select the documents to be removed, must not be {@literal null}.
+	 * @return the current {@link BulkOperations} instance with the removal added, will never be {@literal null}.
 	 */
-	BulkOperations remove(Query remove);	
-	
+	BulkOperations remove(Query remove);
+
 	/**
 	 * Add a list of remove operations to the bulk operation.
 	 * 
-	 * @param remove operations to perform.
-	 * 
-	 * @return The bulk operation.
+	 * @param removes the remove operations to perform, must not be {@literal null}.
+	 * @return the current {@link BulkOperations} instance with the removal added, will never be {@literal null}.
 	 */
 	BulkOperations remove(List<Query> removes);
 
 	/**
 	 * Execute all bulk operations using the default write concern.
 	 * 
 	 * @return Result of the bulk operation providing counters for inserts/updates etc.
-	 * 
-	 * @throws BulkOperationException if errors occur during the exection of the bulk operations.
+	 * @throws {@link BulkOperationException} if an error occurred during bulk processing.
 	 */
-	BulkWriteResult executeBulk();
-
-	/**
-	 * Execute all bulk operations using the given write concern.
-	 * 
-	 * @param writeConcern Write concern to use.
-	 * 
-	 * @return Result of the bulk operation providing counters for inserts/updates etc.
-	 * 
-	 * @throws BulkOperationException if errors occur during the exection of the bulk operations.
-	 */
-	BulkWriteResult executeBulk(WriteConcern writeConcern);
-
+	BulkWriteResult execute();
 }