DATAMONGO-1854 - Add collation option to @document and @query annotation.

We now allow to specify the collation via the @query annotation.

public interface PersonRepository extends MongoRepository<Person, String> {

	@query(collation = "en_US")
	List<Person> findByFirstname(String firstname);

	@query(collation = "{ 'locale' : 'en_US' }")
	List<Person> findPersonByFirstname(String firstname);

	@query(collation = "?1")
	List<Person> findByFirstname(String firstname, Object collation);

	@query(collation = "{ 'locale' : '?1' }")
	List<Person> findByFirstname(String firstname, String collation);

	List<Person> findByFirstname(String firstname, Collation collation);
}

We now make sure to include collation information derived from the Query method if the collation is a fixed value.

Original pull request: #644.

Author: christophstrobl

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

@@ -118,6 +118,23 @@ public static Collation of(CollationLocale locale) {
 		return new Collation(locale);
 	}
 
+	/**
+	 * Parse the given collation string into a {@link Collation}.
+	 *
+	 * @param collation the collation to parse. Can be a simple string like {@code en_US} or a
+	 *          {@link Document#parse(String) parsable} document like <code>&#123; 'locale' : '?0' &#125;</code> .
+	 * @return never {@literal null}.
+	 * @throws IllegalArgumentException if {@literal collation} is null.
+	 * @since 2.2
+	 */
+	public static Collation parse(String collation) {
+
+		Assert.notNull(collation, "Collation must not be null!");
+
+		return StringUtils.trimLeadingWhitespace(collation).startsWith("{") ? from(Document.parse(collation))
+				: of(collation);
+	}
+
 	/**
 	 * Create new {@link Collation} from values in {@link Document}.
 	 *

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

@@ -95,4 +95,36 @@
 	 * @since 2.1
 	 */
 	String sort() default "";
+
+	/**
+	 * Defines the collation to apply when executing the query. <br />
+	 *
+	 * <pre>
+	 *     <code>
+	 *
+	 * // Fixed value
+	 * &#64;Query(collation = "en_US")
+	 * List<Entry> findAllByFixedCollation();
+	 *
+	 * // Fixed value as Document
+	 * &#64;Query(collation = "{ 'locale' :  'en_US' }")
+	 * List<Entry> findAllByFixedJsonCollation();
+	 *
+	 * // Dynamic value as String
+	 * &#64;Query(collation = "?0")
+	 * List<Entry> findAllByDynamicCollation(String collation);
+	 *
+	 * // Dynamic value as Document
+	 * &#64;Query(collation = "{ 'locale' :  ?0 }")
+	 * List<Entry> findAllByDynamicJsonCollation(String collation);
+	 *
+	 * // SpEL expression
+	 * &#64;Query(collation = "?#{[0]}")
+	 * List<Entry> findAllByDynamicSpElCollation(String collation);
+	 *     </code>
+	 * </pre>
+	 *
+	 * @since 2.2
+	 */
+	String collation() default "";
 }

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/AbstractMongoQuery.java

@@ -86,6 +86,7 @@ public Object execute(Object[] parameters) {
 
 		applyQueryMetaAttributesWhenPresent(query);
 		query = applyAnnotatedDefaultSortIfPresent(query);
+		query = applyAnnotatedCollationIfPresent(query, accessor);
 
 		ResultProcessor processor = method.getResultProcessor().withDynamicProjection(accessor);
 		Class<?> typeToRead = processor.getReturnedType().getTypeToRead();
@@ -154,6 +155,21 @@ Query applyAnnotatedDefaultSortIfPresent(Query query) {
 		return QueryUtils.decorateSort(query, Document.parse(method.getAnnotatedSort()));
 	}
 
+	/**
+	 * If present apply a {@link org.springframework.data.mongodb.core.query.Collation} derived from the
+	 * {@link org.springframework.data.repository.query.QueryMethod} the given {@link Query}.
+	 *
+	 * @param query must not be {@literal null}.
+	 * @param accessor the {@link ParameterAccessor} used to obtain parameter placeholder replacement values.
+	 * @return
+	 * @since 2.2
+	 */
+	Query applyAnnotatedCollationIfPresent(Query query, ConvertingParameterAccessor accessor) {
+
+		return QueryUtils.applyCollation(query, method.hasAnnotatedCollation() ? method.getAnnotatedCollation() : null,
+				accessor);
+	}
+
 	/**
 	 * Creates a {@link Query} instance using the given {@link ConvertingParameterAccessor}. Will delegate to
 	 * {@link #createQuery(ConvertingParameterAccessor)} by default but allows customization of the count query to be

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/AbstractReactiveMongoQuery.java

@@ -105,12 +105,14 @@ private Object executeDeferred(Object[] parameters) {
 
 	private Object execute(MongoParameterAccessor parameterAccessor) {
 
-		Query query = createQuery(new ConvertingParameterAccessor(operations.getConverter(), parameterAccessor));
+		ConvertingParameterAccessor convertingParamterAccessor = new ConvertingParameterAccessor(operations.getConverter(), parameterAccessor);
+		Query query = createQuery(convertingParamterAccessor);
 
 		applyQueryMetaAttributesWhenPresent(query);
 		query = applyAnnotatedDefaultSortIfPresent(query);
+		query = applyAnnotatedCollationIfPresent(query, convertingParamterAccessor);
 
-		ResultProcessor processor = method.getResultProcessor().withDynamicProjection(parameterAccessor);
+		ResultProcessor processor = method.getResultProcessor().withDynamicProjection(convertingParamterAccessor);
 		Class<?> typeToRead = processor.getReturnedType().getTypeToRead();
 
 		FindWithQuery<?> find = typeToRead == null //
@@ -119,7 +121,7 @@ private Object execute(MongoParameterAccessor parameterAccessor) {
 
 		String collection = method.getEntityInformation().getCollectionName();
 
-		ReactiveMongoQueryExecution execution = getExecution(parameterAccessor,
+		ReactiveMongoQueryExecution execution = getExecution(convertingParamterAccessor,
 				new ResultProcessingConverter(processor, operations, instantiators), find);
 
 		return execution.execute(query, processor.getReturnedType().getDomainType(), collection);
@@ -195,6 +197,21 @@ Query applyAnnotatedDefaultSortIfPresent(Query query) {
 		return QueryUtils.decorateSort(query, Document.parse(method.getAnnotatedSort()));
 	}
 
+	/**
+	 * If present apply a {@link org.springframework.data.mongodb.core.query.Collation} derived from the
+	 * {@link org.springframework.data.repository.query.QueryMethod} the given {@link Query}.
+	 *
+	 * @param query must not be {@literal null}.
+	 * @param accessor the {@link ParameterAccessor} used to obtain parameter placeholder replacement values.
+	 * @return
+	 * @since 2.2
+	 */
+	Query applyAnnotatedCollationIfPresent(Query query, ConvertingParameterAccessor accessor) {
+
+		return QueryUtils.applyCollation(query, method.hasAnnotatedCollation() ? method.getAnnotatedCollation() : null,
+				accessor);
+	}
+
 	/**
 	 * Creates a {@link Query} instance using the given {@link ConvertingParameterAccessor}. Will delegate to
 	 * {@link #createQuery(ConvertingParameterAccessor)} by default but allows customization of the count query to be

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/ConvertingParameterAccessor.java

@@ -29,6 +29,7 @@
 import org.springframework.data.geo.Point;
 import org.springframework.data.mongodb.core.convert.MongoWriter;
 import org.springframework.data.mongodb.core.mapping.MongoPersistentProperty;
+import org.springframework.data.mongodb.core.query.Collation;
 import org.springframework.data.mongodb.core.query.TextCriteria;
 import org.springframework.data.repository.query.ParameterAccessor;
 import org.springframework.data.util.TypeInformation;
@@ -135,6 +136,15 @@ public TextCriteria getFullText() {
 		return delegate.getFullText();
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.mongodb.repository.query.MongoParameterAccessor#getCollation()
+	 */
+	@Override
+	public Collation getCollation() {
+		return delegate.getCollation();
+	}
+
 	/**
 	 * Converts the given value with the underlying {@link MongoWriter}.
 	 *

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/MongoParameterAccessor.java

@@ -18,6 +18,7 @@
 import org.springframework.data.domain.Range;
 import org.springframework.data.geo.Distance;
 import org.springframework.data.geo.Point;
+import org.springframework.data.mongodb.core.query.Collation;
 import org.springframework.data.mongodb.core.query.TextCriteria;
 import org.springframework.data.repository.query.ParameterAccessor;
 import org.springframework.lang.Nullable;
@@ -57,6 +58,15 @@ public interface MongoParameterAccessor extends ParameterAccessor {
 	@Nullable
 	TextCriteria getFullText();
 
+	/**
+	 * Returns the {@link Collation} to be used for the query.
+	 *
+	 * @return {@literal null} if not set.
+	 * @since 2.2
+	 */
+	@Nullable
+	Collation getCollation();
+
 	/**
 	 * Returns the raw parameter values of the underlying query method.
 	 *

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/MongoParameters.java

@@ -23,6 +23,7 @@
 import org.springframework.data.domain.Range;
 import org.springframework.data.geo.Distance;
 import org.springframework.data.geo.Point;
+import org.springframework.data.mongodb.core.query.Collation;
 import org.springframework.data.mongodb.core.query.TextCriteria;
 import org.springframework.data.mongodb.repository.Near;
 import org.springframework.data.mongodb.repository.query.MongoParameters.MongoParameter;
@@ -45,12 +46,13 @@ public class MongoParameters extends Parameters<MongoParameters, MongoParameter>
 	private final int maxDistanceIndex;
 	private final @Nullable Integer fullTextIndex;
 	private final @Nullable Integer nearIndex;
+	private final @Nullable Integer collationIndex;
 
 	/**
 	 * Creates a new {@link MongoParameters} instance from the given {@link Method} and {@link MongoQueryMethod}.
 	 *
 	 * @param method must not be {@literal null}.
-	 * @param queryMethod must not be {@literal null}.
+	 * @param isGeoNearMethod indicate if this is a geo spatial query method
 	 */
 	public MongoParameters(Method method, boolean isGeoNearMethod) {
 
@@ -64,6 +66,7 @@ public MongoParameters(Method method, boolean isGeoNearMethod) {
 
 		this.rangeIndex = getTypeIndex(parameterTypeInfo, Range.class, Distance.class);
 		this.maxDistanceIndex = this.rangeIndex == -1 ? getTypeIndex(parameterTypeInfo, Distance.class, null) : -1;
+		this.collationIndex = getTypeIndex(parameterTypeInfo, Collation.class, null);
 
 		int index = findNearIndexInParameters(method);
 		if (index == -1 && isGeoNearMethod) {
@@ -74,14 +77,15 @@ public MongoParameters(Method method, boolean isGeoNearMethod) {
 	}
 
 	private MongoParameters(List<MongoParameter> parameters, int maxDistanceIndex, @Nullable Integer nearIndex,
-			@Nullable Integer fullTextIndex, int rangeIndex) {
+			@Nullable Integer fullTextIndex, int rangeIndex, @Nullable Integer collationIndex) {
 
 		super(parameters);
 
 		this.nearIndex = nearIndex;
 		this.fullTextIndex = fullTextIndex;
 		this.maxDistanceIndex = maxDistanceIndex;
 		this.rangeIndex = rangeIndex;
+		this.collationIndex = collationIndex;
 	}
 
 	private final int getNearIndex(List<Class<?>> parameterTypes) {
@@ -111,11 +115,11 @@ private int findNearIndexInParameters(Method method) {
 
 			MongoParameter param = createParameter(MethodParameter.forParameter(p));
 			if (param.isManuallyAnnotatedNearParameter()) {
-				if(index == -1) {
+				if (index == -1) {
 					index = param.getIndex();
 				} else {
-					throw new IllegalStateException(String.format("Found multiple @Near annotations ond method %s! Only one allowed!",
-							method.toString()));
+					throw new IllegalStateException(
+							String.format("Found multiple @Near annotations ond method %s! Only one allowed!", method.toString()));
 				}
 
 			}
@@ -132,8 +136,6 @@ protected MongoParameter createParameter(MethodParameter parameter) {
 		return new MongoParameter(parameter);
 	}
 
-
-
 	public int getDistanceRangeIndex() {
 		return -1;
 	}
@@ -158,7 +160,7 @@ public int getNearIndex() {
 	}
 
 	/**
-	 * Returns ths inde of the parameter to be used as a textquery param
+	 * Returns the index of the parameter to be used as a textquery param
 	 *
 	 * @return
 	 * @since 1.6
@@ -183,13 +185,24 @@ public int getRangeIndex() {
 		return rangeIndex;
 	}
 
+	/**
+	 * Returns the index of the {@link Collation} parameter or -1 if not present.
+	 *
+	 * @return -1 if not set.
+	 * @since 2.2
+	 */
+	public int getCollationParameterIndex() {
+		return collationIndex != null ? collationIndex.intValue() : -1;
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.data.repository.query.Parameters#createFrom(java.util.List)
 	 */
 	@Override
 	protected MongoParameters createFrom(List<MongoParameter> parameters) {
-		return new MongoParameters(parameters, this.maxDistanceIndex, this.nearIndex, this.fullTextIndex, this.rangeIndex);
+		return new MongoParameters(parameters, this.maxDistanceIndex, this.nearIndex, this.fullTextIndex, this.rangeIndex,
+				this.collationIndex);
 	}
 
 	private int getTypeIndex(List<TypeInformation<?>> parameterTypes, Class<?> type, @Nullable Class<?> componentType) {
@@ -241,7 +254,7 @@ class MongoParameter extends Parameter {
 		@Override
 		public boolean isSpecialParameter() {
 			return super.isSpecialParameter() || Distance.class.isAssignableFrom(getType()) || isNearParameter()
-					|| TextCriteria.class.isAssignableFrom(getType());
+					|| TextCriteria.class.isAssignableFrom(getType()) || Collation.class.isAssignableFrom(getType());
 		}
 
 		private boolean isNearParameter() {

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/MongoParametersParameterAccessor.java

@@ -22,6 +22,7 @@
 import org.springframework.data.domain.Range.Bound;
 import org.springframework.data.geo.Distance;
 import org.springframework.data.geo.Point;
+import org.springframework.data.mongodb.core.query.Collation;
 import org.springframework.data.mongodb.core.query.Term;
 import org.springframework.data.mongodb.core.query.TextCriteria;
 import org.springframework.data.repository.query.ParametersParameterAccessor;
@@ -67,7 +68,8 @@ public Range<Distance> getDistanceRange() {
 		}
 
 		int maxDistanceIndex = mongoParameters.getMaxDistanceIndex();
-		Bound<Distance> maxDistance = maxDistanceIndex == -1 ? Bound.unbounded() : Bound.inclusive((Distance) getValue(maxDistanceIndex));
+		Bound<Distance> maxDistance = maxDistanceIndex == -1 ? Bound.unbounded()
+				: Bound.inclusive((Distance) getValue(maxDistanceIndex));
 
 		return Range.of(Bound.unbounded(), maxDistance);
 	}
@@ -134,6 +136,20 @@ protected TextCriteria potentiallyConvertFullText(Object fullText) {
 						ClassUtils.getShortName(fullText.getClass())));
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.mongodb.repository.query.MongoParameterAccessor#getCollation()
+	 */
+	@Override
+	public Collation getCollation() {
+
+		if (method.getParameters().getCollationParameterIndex() == -1) {
+			return null;
+		}
+
+		return getValue(method.getParameters().getCollationParameterIndex());
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.data.mongodb.repository.query.MongoParameterAccessor#getValues()

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/MongoQueryMethod.java

@@ -322,6 +322,30 @@ public String getAnnotatedSort() {
 				"Expected to find @Query annotation but did not. Make sure to check hasAnnotatedSort() before."));
 	}
 
+	/**
+	 * Check if the query method is decorated with an non empty {@link Query#collation()}.
+	 *
+	 * @return true if method annotated with {@link Query} having an non empty collation attribute.
+	 * @since 2.2
+	 */
+	public boolean hasAnnotatedCollation() {
+		return lookupQueryAnnotation().map(it -> !it.collation().isEmpty()).orElse(false);
+	}
+
+	/**
+	 * Get the collation value extracted from the {@link Query} annotation.
+	 *
+	 * @return the {@link Query#sort()} value.
+	 * @throws IllegalStateException if method not annotated with {@link Query}. Make sure to check
+	 *           {@link #hasAnnotatedQuery()} first.
+	 * @since 2.2
+	 */
+	public String getAnnotatedCollation() {
+
+		return lookupQueryAnnotation().map(Query::collation).orElseThrow(() -> new IllegalStateException(
+				"Expected to find @Query annotation but did not. Make sure to check hasAnnotatedCollation() before."));
+	}
+
 	@SuppressWarnings("unchecked")
 	private <A extends Annotation> Optional<A> doFindAnnotation(Class<A> annotationType) {