Provide RepositoryMethodMetadata during method invocation.

Provide context during repository method invocation to potential consumers.

See: #3090
Original Pull Request: #3093

Author: christophstrobl

src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc

@@ -238,6 +238,97 @@ XML::
 ======
 ====
 
+[[repositories.spring-factories]]
+==== Registering Fragments with spring.factories
+
+As already mentioned in the <<repositories.configuration>> section, the infrastructure only auto detects fragments within the repositories base package. Therefore fragments residing in another location or maybe contributed by an external archive will not be found if they do not share a common namespace.
+Registering fragments within `spring.factories` allows you to circumvent this restriction as explained in the following section.
+
+Imagine you'd like to provide some custom search functionality usable across multiple repositories for your organization leveraging a text search index.
+
+First all you need is the fragment interface. Please note the generic `<T>` parameter to align the fragment with the repository domain type.
+
+====
+[source,java]
+----
+package com.acme.search;
+
+public interface SearchExtension<T> {
+
+    List<T> search(String text, Limit limit);
+}
+----
+====
+
+Let's assume the actual full text search is available via a `SearchService` that is registered as a `Bean` within the context so we can consume it in our `SearchExtension` implementation. All we need to run the search is the collection/index name and a object mapper that converts the search results into actual domain objects as sketched out below.
+
+====
+[source,java]
+----
+package com.acme.search;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.data.domain.Limit;
+import org.springframework.data.repository.core.support.RepositoryMethodMetadata;
+
+class DefaultSearchExtension<T> implements SearchExtension<T> {
+
+    private SearchService service;
+
+    DefaultSearchExtension(@Autowired SearchService service) {
+        this.service = service;
+    }
+
+    public List<T> search(String text, Limit limit) {
+        return search(RepositoryMethodMetadata.get(), text, limit);
+    }
+
+    List<T> search(RepositoryMethodMetadata metadata, String text, Limit limit) {
+
+        Class<T> domainType = metadata.repository().getDomainType();
+
+        String indexName = domainType.getSimpleName().toLowerCase();
+        List<String> jsonResult = service.search(indexName, text, 0, limit.max());
+
+        return jsonResult.stream().map( ... ).collect(toList());
+    }
+}
+----
+====
+
+In the snipped above we use `RepositoryMethodMetadata.get()` to get hold of metadata for the actual method invocation. In doing so we can access additional information attached to the repository. In this case we use the repositories domain type to identify the name of the index to be searched.
+
+[TIP]
+====
+For testing you can use `TransactionSynchronizationManager.bindResource(RepositoryMethodMetadata.class, metadata)` to provide repository method metadata.
+====
+
+Now that we've got both, the fragments declaration and implementation we can register it in the `META-INF/spring.factories` file, package things up if needed and we're good to go.
+
+====
+[source,properties]
+----
+com.acme.search.SearchExtension=com.acme.search.DefaultSearchExtension
+----
+====
+
+To make use of the extension simply add the interface to the repository as shown below. The infrastructure will take care placing the required `RepositoryMethodMetadata` so all that
+
+====
+[source,java]
+----
+package io.my.movies;
+
+import com.acme.search.SearchExtension;
+import org.springframework.data.repository.CrudRepository;
+
+
+public interface MovieRepository extends CrudRepository<Movie, String>, SearchExtension<Movie> {
+
+}
+----
+====
+
 [[repositories.customize-base-repository]]
 == Customize the Base Repository
 

src/main/java/org/springframework/data/repository/core/support/DefaultRepositoryMethodMetadata.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2024 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
+ *
+ *      https://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.repository.core.support;
+
+import java.lang.reflect.Method;
+
+import org.springframework.data.repository.core.RepositoryMetadata;
+import org.springframework.lang.Nullable;
+import org.springframework.transaction.support.TransactionSynchronizationManager;
+
+/**
+ * @author Christoph Strobl
+ */
+class DefaultRepositoryMethodMetadata implements RepositoryMethodMetadata {
+
+	private final RepositoryMetadata repositoryMetadata;
+	private final MethodMetadata methodMetadata;
+
+	DefaultRepositoryMethodMetadata(RepositoryMetadata repositoryMetadata, MethodMetadata methodMetadata) {
+
+		this.repositoryMetadata = repositoryMetadata;
+		this.methodMetadata = methodMetadata;
+	}
+
+	static DefaultRepositoryMethodMetadata repositoryMethodMetadata(RepositoryMetadata repositoryMetadata,
+			Method declaredMethod) {
+
+		return repositoryMethodMetadata(repositoryMetadata, declaredMethod, null);
+	}
+
+	static DefaultRepositoryMethodMetadata repositoryMethodMetadata(RepositoryMetadata repositoryMetadata,
+			Method declaredMethod, @Nullable Method targetMethod) {
+
+		return new DefaultRepositoryMethodMetadata(repositoryMetadata,
+				new DefaultMethodMetadata(declaredMethod, targetMethod));
+	}
+
+	static void bind(RepositoryMethodMetadata metadata) {
+		TransactionSynchronizationManager.bindResource(RepositoryMethodMetadata.class, metadata);
+	}
+
+	static void unbind() {
+		TransactionSynchronizationManager.unbindResourceIfPossible(RepositoryMethodMetadata.class);
+	}
+
+	@Override
+	public RepositoryMetadata repository() {
+		return repositoryMetadata;
+	}
+
+	@Override
+	public MethodMetadata method() {
+		return methodMetadata;
+	}
+
+	@Override
+	public String toString() {
+		return "DefaultRepositoryMethodMetadata{" + "repository=" + repositoryMetadata.getRepositoryInterface()
+				+ ", domainType=" + repositoryMetadata.getDomainType() + ", invokedMethod=" + methodMetadata.declaredMethod()
+				+ ", targetMethod=" + methodMetadata.targetMethod() + '}';
+	}
+
+	record DefaultMethodMetadata(Method declaredMethod, @Nullable Method targetMethod) implements MethodMetadata {
+	}
+
+}

src/main/java/org/springframework/data/repository/core/support/QueryExecutorMethodInterceptor.java

@@ -33,6 +33,7 @@
 import org.springframework.data.repository.core.RepositoryInformation;
 import org.springframework.data.repository.core.support.RepositoryInvocationMulticaster.DefaultRepositoryInvocationMulticaster;
 import org.springframework.data.repository.core.support.RepositoryInvocationMulticaster.NoOpRepositoryInvocationMulticaster;
+import org.springframework.data.repository.core.support.RepositoryMethodMetadata.MethodMetadata;
 import org.springframework.data.repository.query.QueryCreationException;
 import org.springframework.data.repository.query.QueryLookupStrategy;
 import org.springframework.data.repository.query.QueryMethod;
@@ -163,7 +164,9 @@ private Object doInvoke(MethodInvocation invocation) throws Throwable {
 			RepositoryMethodInvoker invocationMetadata = invocationMetadataCache.get(method);
 
 			if (invocationMetadata == null) {
-				invocationMetadata = RepositoryMethodInvoker.forRepositoryQuery(method, queries.get(method));
+
+				DefaultRepositoryMethodMetadata repositoryMethodMetadata = DefaultRepositoryMethodMetadata.repositoryMethodMetadata(repositoryInformation, method);
+				invocationMetadata = RepositoryMethodInvoker.forRepositoryQuery(repositoryMethodMetadata, queries.get(method));
 				invocationMetadataCache.put(method, invocationMetadata);
 			}
 

src/main/java/org/springframework/data/repository/core/support/RepositoryComposition.java

@@ -32,6 +32,7 @@
 import org.springframework.data.repository.core.RepositoryMetadata;
 import org.springframework.data.repository.core.support.MethodLookup.InvokedMethod;
 import org.springframework.data.repository.core.support.RepositoryInvocationMulticaster.NoOpRepositoryInvocationMulticaster;
+import org.springframework.data.repository.core.support.RepositoryMethodMetadata.MethodMetadata;
 import org.springframework.data.repository.util.ReactiveWrapperConverters;
 import org.springframework.data.util.ReactiveWrappers;
 import org.springframework.data.util.Streamable;
@@ -281,7 +282,7 @@ Object invoke(RepositoryInvocationMulticaster listener, Method method, Object[]
 
 		ReflectionUtils.makeAccessible(methodToCall);
 
-		return fragments.invoke(metadata != null ? metadata.getRepositoryInterface() : method.getDeclaringClass(), listener,
+		return fragments.invoke(metadata, listener,
 				method, methodToCall, argumentConverter.apply(methodToCall, args));
 	}
 
@@ -369,7 +370,6 @@ public static class RepositoryFragments implements Streamable<RepositoryFragment
 		private final List<RepositoryFragment<?>> fragments;
 
 		private RepositoryFragments(List<RepositoryFragment<?>> fragments) {
-
 			this.fragments = fragments;
 		}
 
@@ -382,6 +382,10 @@ public static RepositoryFragments empty() {
 			return EMPTY;
 		}
 
+		public static RepositoryFragments empty(RepositoryMetadata metadata) {
+			return EMPTY;
+		}
+
 		/**
 		 * Create {@link RepositoryFragments} from just implementation objects.
 		 *
@@ -484,7 +488,7 @@ public Object invoke(Method invokedMethod, Method methodToCall, Object[] args) t
 		/**
 		 * Invoke {@link Method} by resolving the fragment that implements a suitable method.
 		 *
-		 * @param repositoryInterface
+		 * @param metadata
 		 * @param listener
 		 * @param invokedMethod invoked method as per invocation on the interface.
 		 * @param methodToCall backend method that is backing the call.
@@ -493,7 +497,7 @@ public Object invoke(Method invokedMethod, Method methodToCall, Object[] args) t
 		 * @throws Throwable
 		 */
 		@Nullable
-		Object invoke(Class<?> repositoryInterface, RepositoryInvocationMulticaster listener, Method invokedMethod,
+		Object invoke(@Nullable RepositoryMetadata metadata, RepositoryInvocationMulticaster listener, Method invokedMethod,
 				Method methodToCall, Object[] args) throws Throwable {
 
 			RepositoryFragment<?> fragment = fragmentCache.computeIfAbsent(methodToCall, this::findImplementationFragment);
@@ -507,12 +511,15 @@ Object invoke(Class<?> repositoryInterface, RepositoryInvocationMulticaster list
 
 			if (repositoryMethodInvoker == null) {
 
-				repositoryMethodInvoker = RepositoryMethodInvoker.forFragmentMethod(invokedMethod, optional.get(),
+				DefaultRepositoryMethodMetadata repositoryMethodMetadata = DefaultRepositoryMethodMetadata.repositoryMethodMetadata(metadata, invokedMethod, methodToCall);
+				repositoryMethodInvoker = RepositoryMethodInvoker.forFragmentMethod(repositoryMethodMetadata, optional.get(),
 						methodToCall);
+
 				invocationMetadataCache.put(invokedMethod, repositoryMethodInvoker);
 			}
 
-			return repositoryMethodInvoker.invoke(repositoryInterface, listener, args);
+			Class<?> target = (metadata != null && metadata.getRepositoryInterface() != null) ? metadata.getRepositoryInterface() : invokedMethod.getDeclaringClass();
+			return repositoryMethodInvoker.invoke(target, listener, args);
 		}
 
 		private RepositoryFragment<?> findImplementationFragment(Method key) {

src/main/java/org/springframework/data/repository/core/support/RepositoryMethodInvoker.java

@@ -18,12 +18,19 @@
 import kotlin.Unit;
 import kotlin.reflect.KFunction;
 import kotlinx.coroutines.flow.Flow;
+import org.springframework.core.type.MethodMetadata;
+import org.springframework.data.repository.core.CrudMethods;
+import org.springframework.data.repository.core.RepositoryInformation;
+import org.springframework.data.repository.core.RepositoryMetadata;
+import org.springframework.data.util.TypeInformation;
+import org.springframework.transaction.support.TransactionSynchronizationManager;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.util.Collection;
+import java.util.Set;
 import java.util.stream.Stream;
 
 import org.reactivestreams.Publisher;
@@ -46,8 +53,8 @@
  * @author Mark Paluch
  * @author Christoph Strobl
  * @since 2.4
- * @see #forFragmentMethod(Method, Object, Method)
- * @see #forRepositoryQuery(Method, RepositoryQuery)
+// * @see #forFragmentMethod(Method, Object, Method)
+// * @see #forRepositoryQuery(Method, RepositoryQuery)
  * @see RepositoryQuery
  * @see RepositoryComposition
  */
@@ -57,11 +64,13 @@ abstract class RepositoryMethodInvoker {
 	private final Class<?> returnedType;
 	private final Invokable invokable;
 	private final boolean suspendedDeclaredMethod;
+	protected RepositoryMethodMetadata repositoryMethodMetadata;
 
 	@SuppressWarnings("ReactiveStreamsUnusedPublisher")
-	protected RepositoryMethodInvoker(Method method, Invokable invokable) {
+	protected RepositoryMethodInvoker(RepositoryMethodMetadata repositoryMethodMetadata, Invokable invokable) {
 
-		this.method = method;
+		this.repositoryMethodMetadata = repositoryMethodMetadata;
+		this.method = repositoryMethodMetadata.method().declaredMethod();
 
 		if (KotlinDetector.isKotlinReflectPresent()) {
 
@@ -116,7 +125,7 @@ protected RepositoryMethodInvoker(Method method, Invokable invokable) {
 		}
 	}
 
-	static RepositoryQueryMethodInvoker forRepositoryQuery(Method declaredMethod, RepositoryQuery query) {
+	static RepositoryQueryMethodInvoker forRepositoryQuery(RepositoryMethodMetadata declaredMethod, RepositoryQuery query) {
 		return new RepositoryQueryMethodInvoker(declaredMethod, query);
 	}
 
@@ -128,7 +137,7 @@ static RepositoryQueryMethodInvoker forRepositoryQuery(Method declaredMethod, Re
 	 * @param baseMethod the base method to call on fragment {@code instance}.
 	 * @return {@link RepositoryMethodInvoker} to call a fragment {@link Method}.
 	 */
-	static RepositoryMethodInvoker forFragmentMethod(Method declaredMethod, Object instance, Method baseMethod) {
+	static RepositoryMethodInvoker forFragmentMethod(RepositoryMethodMetadata declaredMethod, Object instance, Method baseMethod) {
 		return new RepositoryFragmentMethodInvoker(declaredMethod, instance, baseMethod);
 	}
 
@@ -167,6 +176,10 @@ private Object doInvoke(Class<?> repositoryInterface, RepositoryInvocationMultic
 
 		try {
 
+			if(RepositoryMethodMetadata.get() == null && repositoryMethodMetadata != null) {
+				DefaultRepositoryMethodMetadata.bind(repositoryMethodMetadata);
+			}
+
 			Object result = invokable.invoke(args);
 
 			if (result != null && ReactiveWrappers.supports(result.getClass())) {
@@ -184,6 +197,8 @@ private Object doInvoke(Class<?> repositoryInterface, RepositoryInvocationMultic
 		} catch (Exception e) {
 			multicaster.notifyListeners(method, args, computeInvocationResult(invocationResultCaptor.error(e)));
 			throw e;
+		} finally {
+			DefaultRepositoryMethodMetadata.unbind();
 		}
 	}
 
@@ -202,7 +217,7 @@ interface Invokable {
 	 * Implementation to invoke query methods.
 	 */
 	private static class RepositoryQueryMethodInvoker extends RepositoryMethodInvoker {
-		public RepositoryQueryMethodInvoker(Method method, RepositoryQuery repositoryQuery) {
+		public RepositoryQueryMethodInvoker(RepositoryMethodMetadata method, RepositoryQuery repositoryQuery) {
 			super(method, repositoryQuery::execute);
 		}
 	}
@@ -255,15 +270,19 @@ Publisher<Object> decorate(Class<?> repositoryInterface, RepositoryInvocationMul
 	 */
 	private static class RepositoryFragmentMethodInvoker extends RepositoryMethodInvoker {
 
-		public RepositoryFragmentMethodInvoker(Method declaredMethod, Object instance, Method baseClassMethod) {
-			this(CoroutineAdapterInformation.create(declaredMethod, baseClassMethod), declaredMethod, instance,
+		public RepositoryFragmentMethodInvoker(RepositoryMethodMetadata metadata, Object instance, Method baseClassMethod) {
+			this(CoroutineAdapterInformation.create(metadata.method().declaredMethod(), baseClassMethod), metadata, instance,
 					baseClassMethod);
 		}
 
-		public RepositoryFragmentMethodInvoker(CoroutineAdapterInformation adapterInformation, Method declaredMethod,
+		public RepositoryFragmentMethodInvoker(CoroutineAdapterInformation adapterInformation, RepositoryMethodMetadata declaredMethod,
 				Object instance, Method baseClassMethod) {
 			super(declaredMethod, args -> {
+
 				try {
+
+
+
 					if (adapterInformation.shouldAdaptReactiveToSuspended()) {
 						/*
 						 * Kotlin suspended functions are invoked with a synthetic Continuation parameter that keeps track of the Coroutine context.