Polishing.

Refactor ContextualValueExpressionEvaluator into Function, refactor BindingContext into nested class.

Simplify tests. Rename tests to reflect what they are actually doing. Reformat code.

See #453
Original pull request: #505

Author: mp911de

src/main/antora/modules/ROOT/nav.adoc

@@ -13,10 +13,12 @@
 ** xref:repositories/namespace-reference.adoc[]
 ** xref:repositories/query-keywords-reference.adoc[]
 ** xref:repositories/query-return-types-reference.adoc[]
+
 * xref:ldap.adoc[]
 ** xref:ldap/configuration.adoc[]
 ** xref:ldap/usage.adoc[]
 ** xref:ldap/query-methods.adoc[]
+** xref:ldap/value-expressions.adoc[]
 ** xref:ldap/querydsl.adoc[]
 ** xref:ldap/cdi-integration.adoc[]
 

src/main/antora/modules/ROOT/pages/ldap/query-methods.adoc

@@ -76,3 +76,91 @@ The following table provides samples of the keywords that you can use with query
 | `(!(Firstname=name))`
 
 |===
+
+[[ldap.query-methods.at-query]]
+== Using `@Query`
+
+If you need to use a custom query that can't be derived from the method name, you can use the `@Query` annotation to define the query.
+As queries are tied to the Java method that runs them, you can actually bind parameters to be passed to the query.
+
+The following example shows a query created with the `@Query` annotation:
+
+.Declare query at the query method using `@Query`
+====
+[source,java]
+----
+interface PersonRepository extends LdapRepository<Person, Long> {
+
+  @Query("(&(employmentType=*)(!(employmentType=Hired))(mail=:emailAddress))")
+  Person findEmployeeByEmailAddress(String emailAddress);
+
+}
+----
+====
+
+NOTE: Spring Data supports named (parameter names prefixed with `:`) and positional parameter binding (in the form of zero-based `?0`).
+We recommend using named parameters for easier readability.
+Also, using positional parameters makes query methods a little error-prone when refactoring regarding the parameter position.
+
+[[ldap.encoding]]
+== Parameter Encoding
+
+Query parameters of String-based queries are encoded according to https://datatracker.ietf.org/doc/html/rfc2254[RFC2254].
+This can lead to undesired escaping of certain characters.
+You can specify your own encoder through the `@LdapEncode` annotation that defines which javadoc:org.springframework.data.ldap.repository.LdapEncoder[] to use.
+
+`@LdapEncode` applies to individual parameters of a query method.
+It is not applies for derived queries or Value Expressions (SpEL, Property Placeholders).
+
+.Declare a custom `LdapEncoder` for a query method
+====
+[source,java]
+----
+interface PersonRepository extends LdapRepository<Person, Long> {
+
+  @Query("(&(employmentType=*)(!(employmentType=Hired))(firstName=:firstName))")
+  Person findEmployeeByFirstNameLike(@LdapEncode(MyLikeEncoder.class) String firstName);
+
+}
+----
+====
+
+[[ldap.query.spel-expressions]]
+== Using SpEL Expressions
+
+Spring Data allows you to use SpEL expressions in your query methods.
+SpEL expressions are part of Spring Data's xref:ldap/value-expressions.adoc[Value Expressions] support.
+SpEL expressions can be used to manipulate query method arguments as well as to invoke bean methods.
+Method arguments can be accessed by name or index as demonstrated in the following example.
+
+.Using SpEL expressions in Repository Query Methods
+====
+[source,java]
+----
+@Query("(&(firstName=?#{[0]})(mail=:?#{principal.emailAddress}))")
+List<Person> findByFirstnameAndCurrentUserWithCustomQuery(String firstname);
+----
+====
+
+NOTE: Values provided by SpEL expressions are not escaped according to RFC2254.
+You have to ensure that the values are properly escaped if needed.
+Consider using Spring Ldap's `org.springframework.ldap.support.LdapEncoder` helper class.
+
+[[ldap.query.property-placeholders]]
+== Using Property Placeholders
+
+Property Placeholders (see xref:ldap/value-expressions.adoc[Value Expressions]) can help to easily customize your queries based on configuration properties from Spring's `Environment`.
+These are useful for queries that need to be customized based on the environment or configuration.
+
+.Using Property Placeholders in Repository Query Methods
+====
+[source,java]
+----
+@Query("(&(firstName=?0)(stage=:?${myapp.stage:dev}))")
+List<Person> findByFirstnameAndStageWithCustomQuery(String firstname);
+----
+====
+
+NOTE: Values provided by Property Placeholders are not escaped according to RFC2254.
+You have to ensure that the values are properly escaped if needed.
+Consider using Spring Ldap's `org.springframework.ldap.support.LdapEncoder` helper class.

src/main/antora/modules/ROOT/pages/ldap/value-expressions.adoc

@@ -0,0 +1 @@
+include::{commons}@data-commons::page$value-expressions.adoc[]

src/main/java/org/springframework/data/ldap/repository/query/AbstractLdapRepositoryQuery.java

@@ -26,7 +26,6 @@
 import org.springframework.data.repository.query.QueryMethod;
 import org.springframework.data.repository.query.RepositoryQuery;
 import org.springframework.data.repository.query.ResultProcessor;
-import org.springframework.data.repository.query.ValueExpressionDelegate;
 import org.springframework.ldap.core.LdapOperations;
 import org.springframework.ldap.query.LdapQuery;
 import org.springframework.util.Assert;

src/main/java/org/springframework/data/ldap/repository/query/AnnotatedLdapRepositoryQuery.java

@@ -39,9 +39,9 @@
 public class AnnotatedLdapRepositoryQuery extends AbstractLdapRepositoryQuery {
 
 	private final Query queryAnnotation;
-	private final ValueExpressionDelegate valueExpressionDelegate;
-	private final StringBasedQuery stringBasedQuery;
-	private final StringBasedQuery stringBasedBase;
+	private final StringBasedQuery query;
+	private final StringBasedQuery base;
+	private final ValueEvaluationContextProvider valueContextProvider;
 
 	/**
 	 * Construct a new instance.
@@ -81,34 +81,32 @@ public AnnotatedLdapRepositoryQuery(LdapQueryMethod queryMethod, Class<?> entity
 		Assert.notNull(queryMethod.getQueryAnnotation(), "Annotation must be present");
 		Assert.hasLength(queryMethod.getQueryAnnotation().value(), "Query filter must be specified");
 
-		queryAnnotation = queryMethod.getRequiredQueryAnnotation();
-		this.valueExpressionDelegate = valueExpressionDelegate;
-		stringBasedQuery = new StringBasedQuery(queryAnnotation.value(), queryMethod.getParameters(), valueExpressionDelegate);
-		stringBasedBase = new StringBasedQuery(queryAnnotation.base(), queryMethod.getParameters(), valueExpressionDelegate);
+		this.queryAnnotation = queryMethod.getRequiredQueryAnnotation();
+		this.query = new StringBasedQuery(queryAnnotation.value(), queryMethod.getParameters(), valueExpressionDelegate);
+		this.base = new StringBasedQuery(queryAnnotation.base(), queryMethod.getParameters(), valueExpressionDelegate);
+		this.valueContextProvider = valueExpressionDelegate.createValueContextProvider(getQueryMethod().getParameters());
 	}
 
 	@Override
 	protected LdapQuery createQuery(LdapParameterAccessor parameters) {
 
-		ValueEvaluationContextProvider valueContextProvider = valueExpressionDelegate
-				.createValueContextProvider(getQueryMethod().getParameters());
+		String query = bind(parameters, valueContextProvider, this.query);
+		String base = bind(parameters, valueContextProvider, this.base);
 
-		String boundQuery = bind(parameters, valueContextProvider, stringBasedQuery);
-
-		String boundBase = bind(parameters, valueContextProvider, stringBasedBase);
-
-		return query().base(boundBase) //
+		return query().base(base) //
 				.searchScope(queryAnnotation.searchScope()) //
 				.countLimit(queryAnnotation.countLimit()) //
 				.timeLimit(queryAnnotation.timeLimit()) //
-				.filter(boundQuery);
+				.filter(query, parameters.getBindableParameterValues());
 	}
 
 	private String bind(LdapParameterAccessor parameters, ValueEvaluationContextProvider valueContextProvider, StringBasedQuery query) {
+
 		ValueEvaluationContext evaluationContext = valueContextProvider
 				.getEvaluationContext(parameters.getBindableParameterValues(), query.getExpressionDependencies());
+
 		return query.bindQuery(parameters,
-				new ContextualValueExpressionEvaluator(valueExpressionDelegate, evaluationContext));
+				expression -> expression.evaluate(evaluationContext));
 	}
 
 }