DATAMONGO-1311 - Polishing.

Update Javadoc and add reference documentation.
Alter @meta batchSize default to zero, as negative values bear a special meaning.
Along the lines remove deprecated driver method usage and add deprecations for options about the be removed in subsequent MongoDB server releases.

Original Pull Request: spring-projects#575

Author: christophstrobl

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

@@ -3281,8 +3281,7 @@ public FindIterable<Document> prepare(FindIterable<Document> cursor) {
 
 			Meta meta = query.getMeta();
 			if (query.getSkip() <= 0 && query.getLimit() <= 0 && ObjectUtils.isEmpty(query.getSortObject())
-					&& !StringUtils.hasText(query.getHint()) && !meta.hasValues()
-					&& !query.getCollation().isPresent()) {
+					&& !StringUtils.hasText(query.getHint()) && !meta.hasValues() && !query.getCollation().isPresent()) {
 				return cursor;
 			}
 
@@ -3302,15 +3301,30 @@ public FindIterable<Document> prepare(FindIterable<Document> cursor) {
 					cursorToUse = cursorToUse.sort(sort);
 				}
 
-				Document metaDocument = new Document();
 				if (StringUtils.hasText(query.getHint())) {
-					metaDocument.put("$hint", query.getHint());
+					cursorToUse = cursorToUse.hint(Document.parse(query.getHint()));
 				}
 
 				if (meta.hasValues()) {
 
-					for (Entry<String, Object> entry : meta.values()) {
-						metaDocument.put(entry.getKey(), entry.getValue());
+					if (StringUtils.hasText(meta.getComment())) {
+						cursorToUse = cursorToUse.comment(meta.getComment());
+					}
+
+					if (meta.getSnapshot()) {
+						cursorToUse = cursorToUse.snapshot(meta.getSnapshot());
+					}
+
+					if (meta.getMaxScan() != null) {
+						cursorToUse = cursorToUse.maxScan(meta.getMaxScan());
+					}
+
+					if (meta.getMaxTimeMsec() != null) {
+						cursorToUse = cursorToUse.maxTime(meta.getMaxTimeMsec(), TimeUnit.MILLISECONDS);
+					}
+
+					if (meta.getCursorBatchSize() != null) {
+						cursorToUse = cursorToUse.batchSize(meta.getCursorBatchSize());
 					}
 
 					for (Meta.CursorOption option : meta.getFlags()) {
@@ -3327,13 +3341,8 @@ public FindIterable<Document> prepare(FindIterable<Document> cursor) {
 								throw new IllegalArgumentException(String.format("%s is no supported flag.", option));
 						}
 					}
-
-					if (meta.getCursorBatchSize() != null) {
-						cursorToUse = cursorToUse.batchSize(meta.getCursorBatchSize());
-					}
 				}
 
-				cursorToUse = cursorToUse.modifiers(metaDocument);
 			} catch (RuntimeException e) {
 				throw potentiallyConvertRuntimeException(e, exceptionTranslator);
 			}
@@ -3464,149 +3473,6 @@ public MongoDbFactory getMongoDbFactory() {
 		return mongoDbFactory;
 	}
 
-	/**
-	 * {@link BatchAggregationLoader} is a little helper that can process cursor results returned by an aggregation
-	 * command execution. On presence of a {@literal nextBatch} indicated by presence of an {@code id} field in the
-	 * {@code cursor} another {@code getMore} command gets executed reading the next batch of documents until all results
-	 * are loaded.
-	 *
-	 * @author Christoph Strobl
-	 * @since 1.10
-	 */
-	static class BatchAggregationLoader {
-
-		private static final String CURSOR_FIELD = "cursor";
-		private static final String RESULT_FIELD = "result";
-		private static final String BATCH_SIZE_FIELD = "batchSize";
-		private static final String FIRST_BATCH = "firstBatch";
-		private static final String NEXT_BATCH = "nextBatch";
-		private static final String SERVER_USED = "serverUsed";
-		private static final String OK = "ok";
-
-		private final MongoTemplate template;
-		private final ReadPreference readPreference;
-		private final int batchSize;
-
-		BatchAggregationLoader(MongoTemplate template, ReadPreference readPreference, int batchSize) {
-
-			this.template = template;
-			this.readPreference = readPreference;
-			this.batchSize = batchSize;
-		}
-
-		/**
-		 * Run aggregation command and fetch all results.
-		 */
-		Document aggregate(String collectionName, Aggregation aggregation, AggregationOperationContext context) {
-
-			Document command = prepareAggregationCommand(collectionName, aggregation, context, batchSize);
-
-			if (LOGGER.isDebugEnabled()) {
-				LOGGER.debug("Executing aggregation: {}", serializeToJsonSafely(command));
-			}
-
-			return mergeAggregationResults(aggregateBatched(command, collectionName, batchSize));
-		}
-
-		/**
-		 * Pre process the aggregation command sent to the server by adding {@code cursor} options to match execution on
-		 * different server versions.
-		 */
-		private static Document prepareAggregationCommand(String collectionName, Aggregation aggregation,
-				@Nullable AggregationOperationContext context, int batchSize) {
-
-			AggregationOperationContext rootContext = context == null ? Aggregation.DEFAULT_CONTEXT : context;
-			Document command = aggregation.toDocument(collectionName, rootContext);
-
-			if (!aggregation.getOptions().isExplain()) {
-				command.put(CURSOR_FIELD, new Document(BATCH_SIZE_FIELD, batchSize));
-			}
-
-			return command;
-		}
-
-		private List<Document> aggregateBatched(Document command, String collectionName, int batchSize) {
-
-			List<Document> results = new ArrayList<>();
-
-			Document commandResult = template.executeCommand(command, readPreference);
-			results.add(postProcessResult(commandResult));
-
-			while (hasNext(commandResult)) {
-
-				Document getMore = new Document("getMore", getNextBatchId(commandResult)) //
-						.append("collection", collectionName) //
-						.append(BATCH_SIZE_FIELD, batchSize);
-
-				commandResult = template.executeCommand(getMore, this.readPreference);
-				results.add(postProcessResult(commandResult));
-			}
-
-			return results;
-		}
-
-		private static Document postProcessResult(Document commandResult) {
-
-			if (!commandResult.containsKey(CURSOR_FIELD)) {
-				return commandResult;
-			}
-
-			Document resultObject = new Document(SERVER_USED, commandResult.get(SERVER_USED));
-			resultObject.put(OK, commandResult.get(OK));
-
-			Document cursor = (Document) commandResult.get(CURSOR_FIELD);
-			if (cursor.containsKey(FIRST_BATCH)) {
-				resultObject.put(RESULT_FIELD, cursor.get(FIRST_BATCH));
-			} else {
-				resultObject.put(RESULT_FIELD, cursor.get(NEXT_BATCH));
-			}
-
-			return resultObject;
-		}
-
-		private static Document mergeAggregationResults(List<Document> batchResults) {
-
-			if (batchResults.size() == 1) {
-				return batchResults.iterator().next();
-			}
-
-			Document commandResult = new Document();
-			List<Object> allResults = new ArrayList<>();
-
-			for (Document batchResult : batchResults) {
-
-				Collection documents = (Collection<?>) batchResult.get(RESULT_FIELD);
-				if (!CollectionUtils.isEmpty(documents)) {
-					allResults.addAll(documents);
-				}
-			}
-
-			// take general info from first batch
-			commandResult.put(SERVER_USED, batchResults.iterator().next().get(SERVER_USED));
-			commandResult.put(OK, batchResults.iterator().next().get(OK));
-
-			// and append the merged batchResults
-			commandResult.put(RESULT_FIELD, allResults);
-
-			return commandResult;
-		}
-
-		private static boolean hasNext(Document commandResult) {
-
-			if (!commandResult.containsKey(CURSOR_FIELD)) {
-				return false;
-			}
-
-			Object next = getNextBatchId(commandResult);
-			return next != null && ((Number) next).longValue() != 0L;
-		}
-
-		@Nullable
-		private static Object getNextBatchId(Document commandResult) {
-			return ((Document) commandResult.get(CURSOR_FIELD)).get("id");
-		}
-	}
-
 	/**
 	 * {@link MongoTemplate} extension bound to a specific {@link ClientSession} that is applied when interacting with the
 	 * server through the driver API.

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

@@ -116,7 +116,6 @@
 import org.springframework.util.ResourceUtils;
 import org.springframework.util.StringUtils;
 
-import com.mongodb.BasicDBObject;
 import com.mongodb.ClientSessionOptions;
 import com.mongodb.CursorType;
 import com.mongodb.DBCollection;
@@ -3237,25 +3236,34 @@ public <T> FindPublisher<T> prepare(FindPublisher<T> findPublisher) {
 					Document sort = type != null ? getMappedSortObject(query, type) : query.getSortObject();
 					findPublisherToUse = findPublisherToUse.sort(sort);
 				}
-				BasicDBObject modifiers = new BasicDBObject();
 
 				if (StringUtils.hasText(query.getHint())) {
-					modifiers.append("$hint", query.getHint());
+					findPublisherToUse = findPublisherToUse.hint(Document.parse(query.getHint()));
 				}
 
 				if (meta.hasValues()) {
-					for (Entry<String, Object> entry : meta.values()) {
-						modifiers.append(entry.getKey(), entry.getValue());
+
+					if (StringUtils.hasText(meta.getComment())) {
+						findPublisherToUse = findPublisherToUse.comment(meta.getComment());
+					}
+
+					if (meta.getSnapshot()) {
+						findPublisherToUse = findPublisherToUse.snapshot(meta.getSnapshot());
+					}
+
+					if (meta.getMaxScan() != null) {
+						findPublisherToUse = findPublisherToUse.maxScan(meta.getMaxScan());
+					}
+
+					if (meta.getMaxTimeMsec() != null) {
+						findPublisherToUse = findPublisherToUse.maxTime(meta.getMaxTimeMsec(), TimeUnit.MILLISECONDS);
 					}
 
 					if (meta.getCursorBatchSize() != null) {
 						findPublisherToUse = findPublisherToUse.batchSize(meta.getCursorBatchSize());
 					}
 				}
 
-				if (!modifiers.isEmpty()) {
-					findPublisherToUse = findPublisherToUse.modifiers(modifiers);
-				}
 			} catch (RuntimeException e) {
 				throw potentiallyConvertRuntimeException(e, exceptionTranslator);
 			}

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

@@ -164,13 +164,14 @@ private void applyPropertySpecs(String path, Document source, Class<?> probeType
 			if (exampleSpecAccessor.hasPropertySpecifier(mappedPropertyPath)) {
 
 				PropertyValueTransformer valueTransformer = exampleSpecAccessor.getValueTransformerForPath(mappedPropertyPath);
-				value = valueTransformer.convert(value);
-				if (value == null) {
+				Optional converted = valueTransformer.apply(Optional.ofNullable(value));
+
+				if(!converted.isPresent()) {
 					iter.remove();
 					continue;
 				}
 
-				entry.setValue(value);
+				entry.setValue(converted.get());
 			}
 
 			if (entry.getValue() instanceof String) {

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

@@ -15,6 +15,7 @@
  */
 package org.springframework.data.mongodb.core.query;
 
+import java.time.Duration;
 import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
@@ -66,19 +67,33 @@ public Long getMaxTimeMsec() {
 	 * @param maxTimeMsec
 	 */
 	public void setMaxTimeMsec(long maxTimeMsec) {
-		setMaxTime(maxTimeMsec, TimeUnit.MILLISECONDS);
+		setMaxTime(Duration.ofMillis(maxTimeMsec));
 	}
 
 	/**
 	 * Set the maximum time limit for processing operations.
 	 *
 	 * @param timeout
 	 * @param timeUnit
+	 * @deprecated since 2.1. Use {@link #setMaxTime(Duration)} instead.
 	 */
+	@Deprecated
 	public void setMaxTime(long timeout, @Nullable TimeUnit timeUnit) {
 		setValue(MetaKey.MAX_TIME_MS.key, (timeUnit != null ? timeUnit : TimeUnit.MILLISECONDS).toMillis(timeout));
 	}
 
+	/**
+	 * Set the maximum time limit for processing operations.
+	 *
+	 * @param timeout must not be {@literal null}.
+	 * @since 2.1
+	 */
+	public void setMaxTime(Duration timeout) {
+
+		Assert.notNull(timeout, "Timeout must not be null!");
+		setValue(MetaKey.MAX_TIME_MS.key, timeout.toMillis());
+	}
+
 	/**
 	 * @return {@literal null} if not set.
 	 */
@@ -91,13 +106,15 @@ public Long getMaxScan() {
 	 * Only scan the specified number of documents.
 	 *
 	 * @param maxScan
+	 * @deprecated since 2.1 due to deprecation in MongoDB 4.0.
 	 */
+	@Deprecated
 	public void setMaxScan(long maxScan) {
 		setValue(MetaKey.MAX_SCAN.key, maxScan);
 	}
 
 	/**
-	 * Add a comment to the query.
+	 * Add a comment to the query that is propagated to the profile log.
 	 *
 	 * @param comment
 	 */
@@ -117,7 +134,9 @@ public String getComment() {
 	 * Using snapshot prevents the cursor from returning a document more than once.
 	 *
 	 * @param useSnapshot
+	 * @deprecated since 2.1 due to deprecation as of MongoDB 3.6
 	 */
+	@Deprecated
 	public void setSnapshot(boolean useSnapshot) {
 		setValue(MetaKey.SNAPSHOT.key, useSnapshot);
 	}
@@ -139,9 +158,11 @@ public Integer getCursorBatchSize() {
 	}
 
 	/**
-	 * Apply the batch size for a query.
+	 * Apply the batch size (number of documents to return in each response) for a query. <br />
+	 * Use {@literal 0 (zero)} for no limit. A <strong>negative limit</strong> closes the cursor after returning a single
+	 * batch indicating to the server that the client will not ask for a subsequent one.
 	 *
-	 * @param cursorBatchSize
+	 * @param cursorBatchSize The number of documents to return per batch.
 	 * @since 2.1
 	 */
 	public void setCursorBatchSize(int cursorBatchSize) {