DATAMONGO-957 - Add support for query modifiers.

Using Meta allows to the define $comment, $maxScan, $maxTimeMS and $snapshot on query. When executed we add the meta information to the cursor in use.

We’ve introduced the @meta annotation that allows to the define $comment, $maxScan, $maxTimeMS and $snapshot on a repository finder method.
Added tests to verify proper invocation of template methods
Use DBCursor.copy() for CursorPreparer.

Original pull request: #216.

Author: christophstrobl

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

@@ -2030,6 +2030,7 @@ public FindCallback(DBObject query, DBObject fields) {
 		}
 
 		public DBCursor doInCollection(DBCollection collection) throws MongoException, DataAccessException {
+
 			if (fields == null || fields.toMap().isEmpty()) {
 				return collection.find(query);
 			} else {
@@ -2185,11 +2186,11 @@ public DBCursor prepare(DBCursor cursor) {
 			}
 
 			if (query.getSkip() <= 0 && query.getLimit() <= 0 && query.getSortObject() == null
-					&& !StringUtils.hasText(query.getHint())) {
+					&& !StringUtils.hasText(query.getHint()) && !query.getMeta().hasValues()) {
 				return cursor;
 			}
 
-			DBCursor cursorToUse = cursor;
+			DBCursor cursorToUse = cursor.copy();
 
 			try {
 				if (query.getSkip() > 0) {
@@ -2205,6 +2206,12 @@ public DBCursor prepare(DBCursor cursor) {
 				if (StringUtils.hasText(query.getHint())) {
 					cursorToUse = cursorToUse.hint(query.getHint());
 				}
+				if (query.getMeta().hasValues()) {
+					for (Entry<String, Object> entry : query.getMeta().values()) {
+						cursorToUse = cursorToUse.addSpecial(entry.getKey(), entry.getValue());
+					}
+				}
+
 			} catch (RuntimeException e) {
 				throw potentiallyConvertRuntimeException(e);
 			}

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

@@ -0,0 +1,193 @@
+/*
+ * Copyright 2014 the original author or authors.
+ *
+ * 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.
+ */
+package org.springframework.data.mongodb.core.query;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.concurrent.TimeUnit;
+
+import org.springframework.util.Assert;
+import org.springframework.util.ObjectUtils;
+import org.springframework.util.StringUtils;
+
+/**
+ * Meta-data for {@link Query} instances.
+ * 
+ * @author Christoph Strobl
+ * @author Oliver Gierke
+ * @since 1.6
+ */
+public class Meta {
+
+	private enum MetaKey {
+		MAX_TIME_MS("$maxTimeMS"), MAX_SCAN("$maxScan"), COMMENT("$comment"), SNAPSHOT("$snapshot");
+
+		private String key;
+
+		private MetaKey(String key) {
+			this.key = key;
+		}
+	}
+
+	private final Map<String, Object> values = new LinkedHashMap<String, Object>(2);
+
+	/**
+	 * @return {@literal null} if not set.
+	 */
+	public Long getMaxTimeMsec() {
+		return getValue(MetaKey.MAX_TIME_MS.key);
+	}
+
+	/**
+	 * Set the maximum time limit in milliseconds for processing operations.
+	 * 
+	 * @param maxTimeMsec
+	 */
+	public void setMaxTimeMsec(long maxTimeMsec) {
+		setMaxTime(maxTimeMsec, TimeUnit.MILLISECONDS);
+	}
+
+	/**
+	 * Set the maximum time limit for processing operations.
+	 * 
+	 * @param timeout
+	 * @param timeUnit
+	 */
+	public void setMaxTime(long timeout, TimeUnit timeUnit) {
+		setValue(MetaKey.MAX_TIME_MS.key, (timeUnit != null ? timeUnit : TimeUnit.MILLISECONDS).toMillis(timeout));
+	}
+
+	/**
+	 * @return {@literal null} if not set.
+	 */
+	public Long getMaxScan() {
+		return getValue(MetaKey.MAX_SCAN.key);
+	}
+
+	/**
+	 * Only scan the specified number of documents.
+	 * 
+	 * @param maxScan
+	 */
+	public void setMaxScan(long maxScan) {
+		setValue(MetaKey.MAX_SCAN.key, maxScan);
+	}
+
+	/**
+	 * Add a comment to the query.
+	 * 
+	 * @param comment
+	 */
+	public void setComment(String comment) {
+		setValue(MetaKey.COMMENT.key, comment);
+	}
+
+	/**
+	 * @return {@literal null} if not set.
+	 */
+	public String getComment() {
+		return getValue(MetaKey.COMMENT.key);
+	}
+
+	/**
+	 * Using snapshot prevents the cursor from returning a document more than once.
+	 * 
+	 * @param useSnapshot
+	 */
+	public void setSnapshot(boolean useSnapshot) {
+		setValue(MetaKey.SNAPSHOT.key, useSnapshot);
+	}
+
+	/**
+	 * @return {@literal null} if not set.
+	 */
+	public boolean getSnapshot() {
+		return getValue(MetaKey.SNAPSHOT.key, false);
+	}
+
+	/**
+	 * @return
+	 */
+	public boolean hasValues() {
+		return !this.values.isEmpty();
+	}
+
+	/**
+	 * Get {@link Iterable} of set meta values.
+	 * 
+	 * @return
+	 */
+	public Iterable<Entry<String, Object>> values() {
+		return Collections.unmodifiableSet(this.values.entrySet());
+	}
+
+	/**
+	 * Sets or removes the value in case of {@literal null} or empty {@link String}.
+	 * 
+	 * @param key must not be {@literal null} or empty.
+	 * @param value
+	 */
+	private void setValue(String key, Object value) {
+
+		Assert.hasText(key, "Meta key must not be 'null' or blank.");
+
+		if (value == null || (value instanceof String && !StringUtils.hasText((String) value))) {
+			this.values.remove(key);
+		}
+		this.values.put(key, value);
+	}
+
+	@SuppressWarnings("unchecked")
+	private <T> T getValue(String key) {
+		return (T) this.values.get(key);
+	}
+
+	private <T> T getValue(String key, T defaultValue) {
+
+		T value = getValue(key);
+		return value != null ? value : defaultValue;
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see java.lang.Object#hashCode()
+	 */
+	@Override
+	public int hashCode() {
+		return ObjectUtils.nullSafeHashCode(this.values);
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see java.lang.Object#equals(java.lang.Object)
+	 */
+	@Override
+	public boolean equals(Object obj) {
+
+		if (this == obj) {
+			return true;
+		}
+
+		if (!(obj instanceof Meta)) {
+			return false;
+		}
+
+		Meta other = (Meta) obj;
+		return ObjectUtils.nullSafeEquals(this.values, other.values);
+	}
+}

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

@@ -25,6 +25,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.concurrent.TimeUnit;
 
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
@@ -53,6 +54,8 @@ public class Query {
 	private int limit;
 	private String hint;
 
+	private Meta meta = new Meta();
+
 	/**
 	 * Static factory method to create a {@link Query} using the provided {@link CriteriaDefinition}.
 	 * 
@@ -275,6 +278,84 @@ public String getHint() {
 		return hint;
 	}
 
+	/**
+	 * @param maxTimeMsec
+	 * @return
+	 * @see Meta#setMaxTimeMsec(long)
+	 * @since 1.6
+	 */
+	public Query maxTimeMsec(long maxTimeMsec) {
+
+		meta.setMaxTimeMsec(maxTimeMsec);
+		return this;
+	}
+
+	/**
+	 * @param timeout
+	 * @param timeUnit
+	 * @return
+	 * @see Meta#setMaxTime(long, TimeUnit)
+	 * @since 1.6
+	 */
+	public Query maxTime(long timeout, TimeUnit timeUnit) {
+
+		meta.setMaxTime(timeout, timeUnit);
+		return this;
+	}
+
+	/**
+	 * @param maxScan
+	 * @return
+	 * @see Meta#setMaxScan(long)
+	 * @since 1.6
+	 */
+	public Query maxScan(long maxScan) {
+
+		meta.setMaxScan(maxScan);
+		return this;
+	}
+
+	/**
+	 * @param comment
+	 * @return
+	 * @see Meta#setComment(String)
+	 * @since 1.6
+	 */
+	public Query comment(String comment) {
+
+		meta.setComment(comment);
+		return this;
+	}
+
+	/**
+	 * @return
+	 * @see Meta#setSnapshot(boolean)
+	 * @since 1.6
+	 */
+	public Query useSnapshot() {
+
+		meta.setSnapshot(true);
+		return this;
+	}
+
+	/**
+	 * @return never {@literal null}.
+	 * @since 1.6
+	 */
+	public Meta getMeta() {
+		return meta;
+	}
+
+	/**
+	 * @param meta must not be {@literal null}.
+	 * @since 1.6
+	 */
+	public void setMeta(Meta meta) {
+
+		Assert.notNull(meta, "Query meta might be empty but must not be null.");
+		this.meta = meta;
+	}
+
 	protected List<CriteriaDefinition> getCriteria() {
 		return new ArrayList<CriteriaDefinition>(this.criteria.values());
 	}
@@ -312,8 +393,9 @@ public boolean equals(Object obj) {
 		boolean hintEqual = this.hint == null ? that.hint == null : this.hint.equals(that.hint);
 		boolean skipEqual = this.skip == that.skip;
 		boolean limitEqual = this.limit == that.limit;
+		boolean metaEqual = nullSafeEquals(this.meta, that.meta);
 
-		return criteriaEqual && fieldsEqual && sortEqual && hintEqual && skipEqual && limitEqual;
+		return criteriaEqual && fieldsEqual && sortEqual && hintEqual && skipEqual && limitEqual && metaEqual;
 	}
 
 	/* 
@@ -331,6 +413,7 @@ public int hashCode() {
 		result += 31 * nullSafeHashCode(hint);
 		result += 31 * skip;
 		result += 31 * limit;
+		result += 31 * nullSafeHashCode(meta);
 
 		return result;
 	}