Introduce @meta data support for repository methods.

Closes #775.

Author: gregturn

Diff for: spring-data-jpa/src/main/java/org/springframework/data/jpa/provider/PersistenceProvider.java

@@ -18,22 +18,22 @@
 import static org.springframework.data.jpa.provider.JpaClassUtils.*;
 import static org.springframework.data.jpa.provider.PersistenceProvider.Constants.*;
 
-import java.util.Collections;
-import java.util.NoSuchElementException;
-import java.util.Set;
-
 import jakarta.persistence.EntityManager;
 import jakarta.persistence.Query;
 import jakarta.persistence.metamodel.IdentifiableType;
 import jakarta.persistence.metamodel.Metamodel;
 import jakarta.persistence.metamodel.SingularAttribute;
 
+import java.util.Collections;
+import java.util.NoSuchElementException;
+import java.util.Set;
+
+import org.eclipse.persistence.config.QueryHints;
 import org.eclipse.persistence.jpa.JpaQuery;
 import org.eclipse.persistence.queries.ScrollableCursor;
 import org.hibernate.ScrollMode;
 import org.hibernate.ScrollableResults;
 import org.hibernate.proxy.HibernateProxy;
-
 import org.springframework.data.jpa.repository.query.JpaParameters;
 import org.springframework.data.jpa.repository.query.JpaParametersParameterAccessor;
 import org.springframework.data.util.CloseableIterator;
@@ -49,8 +49,9 @@
  * @author Thomas Darimont
  * @author Mark Paluch
  * @author Jens Schauder
+ * @author Greg Turnquist
  */
-public enum PersistenceProvider implements QueryExtractor, ProxyIdAccessor {
+public enum PersistenceProvider implements QueryExtractor, ProxyIdAccessor, QueryComment {
 
 	/**
 	 * Hibernate persistence provider.
@@ -102,9 +103,15 @@ public CloseableIterator<Object> executeQueryWithResultStream(Query jpaQuery) {
 		}
 
 		@Override
-		public JpaParametersParameterAccessor getParameterAccessor(JpaParameters parameters, Object[] values, EntityManager em) {
+		public JpaParametersParameterAccessor getParameterAccessor(JpaParameters parameters, Object[] values,
+				EntityManager em) {
 			return new HibernateJpaParametersParameterAccessor(parameters, values, em);
 		}
+
+		@Override
+		public String getCommentHintKey() {
+			return "org.hibernate.comment";
+		}
 	},
 
 	/**
@@ -133,6 +140,16 @@ public Object getIdentifierFrom(Object entity) {
 		public CloseableIterator<Object> executeQueryWithResultStream(Query jpaQuery) {
 			return new EclipseLinkScrollableResultsIterator<>(jpaQuery);
 		}
+
+		@Override
+		public String getCommentHintKey() {
+			return QueryHints.HINT;
+		}
+
+		@Override
+		public String getCommentHintValue(String comment) {
+			return "/* " + comment + " */";
+		}
 	},
 
 	/**
@@ -161,11 +178,18 @@ public boolean shouldUseAccessorFor(Object entity) {
 		public Object getIdentifierFrom(Object entity) {
 			return null;
 		}
+
+		@Nullable
+		@Override
+		public String getCommentHintKey() {
+			return null;
+		}
 	};
 
 	static ConcurrentReferenceHashMap<Class<?>, PersistenceProvider> CACHE = new ConcurrentReferenceHashMap<>();
 	private final Iterable<String> entityManagerClassNames;
 	private final Iterable<String> metamodelClassNames;
+
 	/**
 	 * Creates a new {@link PersistenceProvider}.
 	 *
@@ -249,7 +273,8 @@ public static PersistenceProvider fromMetamodel(Metamodel metamodel) {
 		return cacheAndReturn(metamodelType, GENERIC_JPA);
 	}
 
-	public JpaParametersParameterAccessor getParameterAccessor(JpaParameters parameters, Object[] values, EntityManager em) {
+	public JpaParametersParameterAccessor getParameterAccessor(JpaParameters parameters, Object[] values,
+			EntityManager em) {
 		return new JpaParametersParameterAccessor(parameters, values);
 	}
 

Diff for: spring-data-jpa/src/main/java/org/springframework/data/jpa/provider/QueryComment.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2013-2022 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.jpa.provider;
+
+import jakarta.persistence.Query;
+
+import org.springframework.lang.Nullable;
+
+/**
+ * Interface to hide different implementations of query hints that insert comments into a {@link Query}.
+ *
+ * @author Greg Turnquist
+ * @since 3.0
+ */
+public interface QueryComment {
+
+	@Nullable
+	String getCommentHintKey();
+
+	@Nullable
+	default String getCommentHintValue(String comment) {
+		return comment;
+	}
+}

Diff for: spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/Meta.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2014-2022 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.jpa.repository;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to assign metadata to repository operations.
+ *
+ * @author Greg Turnquist
+ * @since 3.0
+ * @see org.springframework.data.jpa.repository.query.Meta
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+@Documented
+public @interface Meta {
+
+	/**
+	 * Add a comment to the query.
+	 *
+	 * @return empty {@link String} by default.
+	 */
+	String comment() default "";
+
+}

Diff for: spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/AbstractJpaQuery.java

@@ -187,6 +187,15 @@ protected <T extends Query> T applyHints(T query, JpaQueryMethod method) {
 			}
 		}
 
+		// Apply any meta-attributes that exist
+		if (method.hasQueryMetaAttributes()) {
+
+			if (provider.getCommentHintKey() != null) {
+				query.setHint( //
+						provider.getCommentHintKey(), provider.getCommentHintValue(method.getQueryMetaAttributes().getComment()));
+			}
+		}
+
 		return query;
 	}
 

Diff for: spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/JpaQueryMethod.java

@@ -24,6 +24,7 @@
 import java.util.Collections;
 import java.util.HashSet;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
 
@@ -32,6 +33,7 @@
 import org.springframework.data.jpa.provider.QueryExtractor;
 import org.springframework.data.jpa.repository.EntityGraph;
 import org.springframework.data.jpa.repository.Lock;
+import org.springframework.data.jpa.repository.Meta;
 import org.springframework.data.jpa.repository.Modifying;
 import org.springframework.data.jpa.repository.Query;
 import org.springframework.data.jpa.repository.QueryHints;
@@ -46,6 +48,7 @@
 import org.springframework.data.util.TypeInformation;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
+import org.springframework.util.ConcurrentReferenceHashMap;
 import org.springframework.util.StringUtils;
 
 /**
@@ -94,6 +97,7 @@ public class JpaQueryMethod extends QueryMethod {
 	private final Lazy<Boolean> isCollectionQuery;
 	private final Lazy<Boolean> isProcedureQuery;
 	private final Lazy<JpaEntityMetadata<?>> entityMetadata;
+	private final Map<Class<? extends Annotation>, Optional<Annotation>> annotationCache;
 
 	/**
 	 * Creates a {@link JpaQueryMethod}.
@@ -135,6 +139,7 @@ protected JpaQueryMethod(Method method, RepositoryMetadata metadata, ProjectionF
 		this.isCollectionQuery = Lazy.of(() -> super.isCollectionQuery() && !NATIVE_ARRAY_TYPES.contains(this.returnType));
 		this.isProcedureQuery = Lazy.of(() -> AnnotationUtils.findAnnotation(method, Procedure.class) != null);
 		this.entityMetadata = Lazy.of(() -> new DefaultJpaEntityMetadata<>(getDomainClass()));
+		this.annotationCache = new ConcurrentReferenceHashMap<>();
 
 		Assert.isTrue(!(isModifyingQuery() && getParameters().hasSpecialParameter()),
 				String.format("Modifying method must not contain %s", Parameters.TYPES));
@@ -193,6 +198,13 @@ public boolean isModifyingQuery() {
 		return modifying.getNullable() != null;
 	}
 
+	@SuppressWarnings("unchecked")
+	private <A extends Annotation> Optional<A> doFindAnnotation(Class<A> annotationType) {
+
+		return (Optional<A>) this.annotationCache.computeIfAbsent(annotationType,
+				it -> Optional.ofNullable(AnnotatedElementUtils.findMergedAnnotation(method, it)));
+	}
+
 	/**
 	 * Returns all {@link QueryHint}s annotated at this class. Note, that {@link QueryHints}
 	 *
@@ -259,6 +271,47 @@ Class<?> getReturnType() {
 		return returnType;
 	}
 
+	/**
+	 * @return return true if {@link Meta} annotation is available.
+	 * @since 3.0
+	 */
+	public boolean hasQueryMetaAttributes() {
+		return getMetaAnnotation() != null;
+	}
+
+	/**
+	 * Returns the {@link Meta} annotation that is applied to the method or {@code null} if not available.
+	 *
+	 * @return
+	 * @since 3.0
+	 */
+	@Nullable
+	Meta getMetaAnnotation() {
+		return doFindAnnotation(Meta.class).orElse(null);
+	}
+
+	/**
+	 * Returns the {@link org.springframework.data.jpa.repository.query.Meta} attributes to be applied.
+	 *
+	 * @return never {@literal null}.
+	 * @since 1.6
+	 */
+	public org.springframework.data.jpa.repository.query.Meta getQueryMetaAttributes() {
+
+		Meta meta = getMetaAnnotation();
+		if (meta == null) {
+			return new org.springframework.data.jpa.repository.query.Meta();
+		}
+
+		org.springframework.data.jpa.repository.query.Meta metaAttributes = new org.springframework.data.jpa.repository.query.Meta();
+
+		if (StringUtils.hasText(meta.comment())) {
+			metaAttributes.setComment(meta.comment());
+		}
+
+		return metaAttributes;
+	}
+
 	/**
 	 * Returns the query string declared in a {@link Query} annotation or {@literal null} if neither the annotation found
 	 * nor the attribute was specified.