#26 - Create Function counterparts to some of the iteration methods

sebersole · sebersole · commit 221d803557b4 · 2024-02-08T11:49:25.000-06:00
diff --git a/README.adoc b/README.adoc
@@ -15,6 +15,25 @@ library, which suffered from a number of shortcomings.
 
 === Annotations
 
-Hibernate Models defines an actual descriptor for annotations called `AnnotationDescriptor` which provides access
-to information (whether it is repeatable, etc.) about the annotation class.  These descriptors are available from the
-`AnnotationDescriptorRegistry`.
+The modeling of annotations in hibernate-models is defined by a few main actors:
+
+AnnotationDescriptor:: Extended information about an annotation class
+AnnotationTarget:: Something (Class, Method, ...) where an annotation can be used
+AnnotationUsage:: Specific usage of an annotation on a target
+AttributeDescriptor:: Details about an annotation attribute, including it's `ValueTypeDescriptor`
+ValueTypeDescriptor:: Describes an allowable type for annotation attributes - ints, enums, etc.  Provides the capability to manipulate these values (create them, wrap them, unwrap them, etc).
+AnnotationDescriptorRegistry:: registry of `AnnotationDescriptor` references
+
+
+=== Model
+
+These mostly model Java constructs such as Class, Method, etc. but adds the capability
+for these to be dynamic models (no physical Class).
+
+ClassDetails:: Think `java.lang.Class`
+TypeDetails:: Think `java.lang.reflect.Type`
+MemberDetails:: Think `java.lang.reflect.Member`
+FieldDetails:: Think `java.lang.reflect.Field`
+MethodDetails:: Think `java.lang.reflect.Method`
+RecordComponentDetails:: Think `java.lang.reflect.RecordComponent`
+ClassDetailsRegistry:: registry of `ClassDetails` references
diff --git a/src/main/java/org/hibernate/models/internal/AnnotationTargetSupport.java b/src/main/java/org/hibernate/models/internal/AnnotationTargetSupport.java
@@ -7,12 +7,14 @@
 package org.hibernate.models.internal;
 
 import java.lang.annotation.Annotation;
+import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 import java.util.function.Consumer;
 
 import org.hibernate.models.spi.AnnotationDescriptor;
+import org.hibernate.models.spi.AnnotationDescriptorRegistry;
 import org.hibernate.models.spi.AnnotationUsage;
 import org.hibernate.models.spi.SourceModelBuildingContext;
 
@@ -33,6 +35,23 @@ default <A extends Annotation> boolean hasAnnotationUsage(Class<A> type) {
 		return getUsageMap().containsKey( type );
 	}
 
+	@Override
+	default <A extends Annotation> boolean hasRepeatableAnnotationUsage(Class<A> type) {
+		final boolean containsDirectly = getUsageMap().containsKey( type );
+		if ( containsDirectly ) {
+			return true;
+		}
+
+		final AnnotationDescriptorRegistry descriptorRegistry = getBuildingContext().getAnnotationDescriptorRegistry();
+		final AnnotationDescriptor<A> descriptor = descriptorRegistry.getDescriptor( type );
+		if ( descriptor.isRepeatable() ) {
+			// e.g. caller asks about NamedQuery... let's also check for NamedQueries (which implies NamedQuery)
+			return getUsageMap().containsKey( descriptor.getRepeatableContainer().getAnnotationType() );
+		}
+
+		return false;
+	}
+
 	@Override
 	default <A extends Annotation> AnnotationUsage<A> getAnnotationUsage(AnnotationDescriptor<A> descriptor) {
 		return AnnotationUsageHelper.getUsage( descriptor, getUsageMap() );
@@ -45,21 +64,19 @@ default <A extends Annotation> AnnotationUsage<A> getAnnotationUsage(Class<A> an
 
 	@Override
 	default <A extends Annotation> AnnotationUsage<A> locateAnnotationUsage(Class<A> annotationType) {
-		final Map<Class<? extends Annotation>, AnnotationUsage<? extends Annotation>> localUsageMap = getUsageMap();
-
 		// e.g., locate `@Nationalized`
 		//		1. direct - look for `Nationalized.class` in the usage map (direct local use on the target)
 		//		2. "meta annotations" - for each local usage, check that annotation's annotations for `Nationalized.class` (one level deep)
 
 
 		// first, see if we can find it directly...
-		//noinspection unchecked
-		final AnnotationUsage<A> direct = (AnnotationUsage<A>) localUsageMap.get( annotationType );
-		if ( direct != null ) {
-			return direct;
+		final AnnotationUsage<A> localUsage = getAnnotationUsage( annotationType );
+		if ( localUsage != null ) {
+			return null;
 		}
 
 		// check as "meta annotations" (annotations on our annotations)...
+		final Map<Class<? extends Annotation>, AnnotationUsage<? extends Annotation>> localUsageMap = getUsageMap();
 		for ( Map.Entry<Class<? extends Annotation>, AnnotationUsage<? extends Annotation>> usageEntry : localUsageMap.entrySet() ) {
 			final AnnotationUsage<? extends Annotation> usage = usageEntry.getValue();
 			if ( annotationType.equals( usage.getAnnotationType() ) ) {
@@ -97,6 +114,19 @@ default <X extends Annotation> void forEachAnnotationUsage(Class<X> type, Consum
 		);
 	}
 
+	@Override
+	default <A extends Annotation> List<AnnotationUsage<? extends Annotation>> getMetaAnnotated(Class<A> metaAnnotationType) {
+		final AnnotationDescriptorRegistry descriptorRegistry = getBuildingContext().getAnnotationDescriptorRegistry();
+		final List<AnnotationUsage<?>> usages = new ArrayList<>();
+		forAllAnnotationUsages( (usage) -> {
+			final AnnotationUsage<? extends Annotation> metaUsage = usage.getAnnotationDescriptor().getAnnotationUsage( metaAnnotationType );
+			if ( metaUsage != null ) {
+				usages.add( usage );
+			}
+		} );
+		return usages;
+	}
+
 	@Override
 	default <X extends Annotation> AnnotationUsage<X> getNamedAnnotationUsage(Class<X> type, String matchName) {
 		return getNamedAnnotationUsage( getBuildingContext().getAnnotationDescriptorRegistry().getDescriptor( type ), matchName );
diff --git a/src/main/java/org/hibernate/models/internal/AnnotationUsageHelper.java b/src/main/java/org/hibernate/models/internal/AnnotationUsageHelper.java
@@ -76,9 +76,9 @@ public static <A extends Annotation> List<AnnotationUsage<A>> getRepeatedUsages(
 			final List<AnnotationUsage<A>> repetitions = containerUsage.getAttributeValue( "value" );
 			if ( CollectionHelper.isNotEmpty( repetitions ) ) {
 				if ( usage != null ) {
-					// we can have both when repeatable + inherited are mixed
 					final ArrayList<AnnotationUsage<A>> combined = new ArrayList<>( repetitions );
-					combined.add( usage );
+					// prepend the singular usage
+					combined.add( 0, usage );
 					return combined;
 				}
 				return repetitions;
diff --git a/src/main/java/org/hibernate/models/internal/SimpleClassDetails.java b/src/main/java/org/hibernate/models/internal/SimpleClassDetails.java
@@ -145,6 +145,11 @@ public <A extends Annotation> boolean hasAnnotationUsage(Class<A> type) {
 		return false;
 	}
 
+	@Override
+	public <A extends Annotation> boolean hasRepeatableAnnotationUsage(Class<A> type) {
+		return false;
+	}
+
 	@Override
 	public <A extends Annotation> AnnotationUsage<A> getAnnotationUsage(AnnotationDescriptor<A> descriptor) {
 		return null;
@@ -174,6 +179,11 @@ public <A extends Annotation> List<AnnotationUsage<A>> getRepeatedAnnotationUsag
 	public <X extends Annotation> void forEachAnnotationUsage(Class<X> type, Consumer<AnnotationUsage<X>> consumer) {
 	}
 
+	@Override
+	public <A extends Annotation> List<AnnotationUsage<? extends Annotation>> getMetaAnnotated(Class<A> metaAnnotationType) {
+		return Collections.emptyList();
+	}
+
 	@Override
 	public <X extends Annotation> AnnotationUsage<X> getNamedAnnotationUsage(
 			AnnotationDescriptor<X> type,
diff --git a/src/main/java/org/hibernate/models/internal/jdk/AnnotationDescriptorOrmImpl.java b/src/main/java/org/hibernate/models/internal/jdk/AnnotationDescriptorOrmImpl.java
@@ -98,6 +98,11 @@ public <X extends Annotation> boolean hasAnnotationUsage(Class<X> type) {
 		return false;
 	}
 
+	@Override
+	public <A extends Annotation> boolean hasRepeatableAnnotationUsage(Class<A> type) {
+		return false;
+	}
+
 	@Override
 	public <X extends Annotation> AnnotationUsage<X> getAnnotationUsage(AnnotationDescriptor<X> descriptor) {
 		// there are none
@@ -140,6 +145,11 @@ public <X extends Annotation> void forEachAnnotationUsage(Class<X> type, Consume
 		// there are none
 	}
 
+	public <X extends Annotation> List<AnnotationUsage<? extends Annotation>> getMetaAnnotated(Class<X> metaAnnotationType) {
+		// there are none
+		return Collections.emptyList();
+	}
+
 	@Override
 	public <X extends Annotation> AnnotationUsage<X> getNamedAnnotationUsage(
 			AnnotationDescriptor<X> type,
diff --git a/src/main/java/org/hibernate/models/spi/AnnotationTarget.java b/src/main/java/org/hibernate/models/spi/AnnotationTarget.java
@@ -10,7 +10,6 @@
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Repeatable;
 import java.lang.annotation.Target;
-import java.util.ArrayList;
 import java.util.Collection;
 import java.util.EnumSet;
 import java.util.List;
@@ -19,7 +18,9 @@
 import org.hibernate.models.AnnotationAccessException;
 
 /**
- * Abstraction of {@linkplain java.lang.reflect.AnnotatedElement}
+ * Abstract for something where an annotation can be {@linkplain AnnotationUsage used}.
+ *
+ * @see java.lang.reflect.AnnotatedElement
  *
  * @author Steve Ebersole
  */
@@ -36,24 +37,50 @@ public interface AnnotationTarget {
 
 	/**
 	 * Access to all the annotations used on this target.
+	 *
+	 * @apiNote This returns the usages directly available on the target; it does not
+	 * expand repeatable containers (e.g. NamedQueries -> *NamedQuery).
 	 */
 	Collection<AnnotationUsage<?>> getAllAnnotationUsages();
 
+	/**
+	 * Allows to visit every annotation on the target.
+	 *
+	 * @apiNote Only visits the usages directly available on the target; it does not
+	 * visit across repeatable containers (e.g. NamedQueries -> *NamedQuery).
+	 */
 	default void forAllAnnotationUsages(Consumer<AnnotationUsage<?>> consumer) {
 		getAllAnnotationUsages().forEach( consumer );
 	}
 
 	/**
-	 * Whether the given annotation is used on this target
+	 * Whether the given annotation is used on this target.
+	 *
+	 * @see #hasRepeatableAnnotationUsage
+	 *
+	 * @apiNote This form does not check across repeatable containers.  E.g., calling this
+	 * method with {@code NamedQuery} will return {@code false} when the target directly
+	 * has a NamedQueries.
 	 */
 	<A extends Annotation> boolean hasAnnotationUsage(Class<A> type);
 
+	/**
+	 * Whether the given annotation is used on this target.
+	 *
+	 * @see #hasAnnotationUsage
+	 *
+	 * @apiNote This forms does check across repeatable containers.  E.g., calling this
+	 * method with {@code NamedQuery} will return {@code true} when the target directly
+	 * has a NamedQueries.
+	 */
+	<A extends Annotation> boolean hasRepeatableAnnotationUsage(Class<A> type);
+
 	/**
 	 * Get the usage of the given annotation on this target.
 	 * <p/>
 	 * For {@linkplain Repeatable repeatable} annotation types (e.g. {@code @NamedQuery}), this method will either-<ul>
 	 *     <li>
-	 *         if the repeatable annotation itself is present, it is returned.
+	 *         if a single repeatable annotation itself is present, it is returned.
 	 *     </li>
 	 *     <li>
 	 *         if the {@linkplain Repeatable#value() "containing annotation"} is present (e.g. {@code @NamedQueries}), <ul>
@@ -67,15 +94,14 @@ default void forAllAnnotationUsages(Consumer<AnnotationUsage<?>> consumer) {
 	 *     </li>
 	 * </ul>
 	 * <p/>
-	 * For annotations which can {@linkplain ElementType#ANNOTATION_TYPE target annotations},
-	 * all annotations on this target will be checked as well.
+	 * For also checking across meta-annotations, see {@linkplain #locateAnnotationUsage(Class)}.
 	 *
 	 * @return The usage or {@code null}
 	 */
 	<A extends Annotation> AnnotationUsage<A> getAnnotationUsage(AnnotationDescriptor<A> descriptor);
 
 	/**
-	 * Helper form of {@link #getAnnotationUsage(AnnotationDescriptor)}
+	 * Form of {@link #getAnnotationUsage(AnnotationDescriptor)} accepting the annotation {@linkplain Class}
 	 */
 	<A extends Annotation> AnnotationUsage<A> getAnnotationUsage(Class<A> type);
 
@@ -87,26 +113,17 @@ default void forAllAnnotationUsages(Consumer<AnnotationUsage<?>> consumer) {
 
 	/**
 	 * Get all usages of the specified {@code annotationType} in this scope.
-	 * <p/>
-	 * For {@linkplain Repeatable repeatable} annotation types (e.g. {@code @NamedQuery}) -<ul>
-	 *     <li>
-	 *         if the repeatable annotation itself is present, a singleton list containing that single usage is returned
-	 *     </li>
-	 *     <li>
-	 *         if the {@linkplain Repeatable#value() "containing annotation"} (e.g. {@code @NamedQueries}) is present,
-	 *         the contained repeatable usages are extracted from the container and returned as a list
-	 *     </li>
-	 *     <li>
-	 *         Otherwise, an empty list is returned.
-	 *     </li>
-	 * </ul>
 	 *
-	 * @apiNote If the passed annotation type is not repeatable, an empty list is returned.
+	 * @apiNote For {@linkplain Repeatable repeatable} annotation types (e.g. {@code @NamedQuery}),
+	 * the returned list will contain the union of <ol>
+	 *     <li>the singular {@code @NamedQuery} usage</li>
+	 *     <li>the nested {@code @NamedQuery} usages from the {@code @NamedQueries} usage</li>
+	 * </ol>
 	 */
 	<A extends Annotation> List<AnnotationUsage<A>> getRepeatedAnnotationUsages(AnnotationDescriptor<A> type);
 
 	/**
-	 * Helper form of {@linkplain #getRepeatedAnnotationUsages(AnnotationDescriptor)}
+	 * Form of {@linkplain #getRepeatedAnnotationUsages(AnnotationDescriptor)} accepting the annotation {@linkplain Class}
 	 */
 	<A extends Annotation> List<AnnotationUsage<A>> getRepeatedAnnotationUsages(Class<A> type);
 
@@ -128,7 +145,7 @@ default <X extends Annotation> void forEachAnnotationUsage(
 	}
 
 	/**
-	 * Helper form of {@link #forEachAnnotationUsage(AnnotationDescriptor, Consumer)}
+	 * Form of {@link #forEachAnnotationUsage(AnnotationDescriptor, Consumer)} accepting the annotation {@linkplain Class}
 	 */
 	<X extends Annotation> void forEachAnnotationUsage(Class<X> type, Consumer<AnnotationUsage<X>> consumer);
 
@@ -155,17 +172,11 @@ default <X extends Annotation> void forEachAnnotationUsage(
 	 * </pre>
 	 * a call to this method passing {@code TheMeta} on {@code ClassDetails(TheClass)} will return
 	 * the usage of {@code @TheAnnotation} on {@code TheClass}.
+	 *
+	 * @apiNote This method does not check across repeatable containers.  Although the return is a List, we
+	 * are functionally wanting just the unique ones.
 	 */
-	default <A extends Annotation> List<AnnotationUsage<? extends Annotation>> getMetaAnnotated(Class<A> metaAnnotationType) {
-		final List<AnnotationUsage<?>> usages = new ArrayList<>();
-		forAllAnnotationUsages( (usage) -> {
-			final AnnotationUsage<? extends Annotation> metaUsage = usage.getAnnotationDescriptor().getAnnotationUsage( metaAnnotationType );
-			if ( metaUsage != null ) {
-				usages.add( usage );
-			}
-		} );
-		return usages;
-	}
+	<A extends Annotation> List<AnnotationUsage<? extends Annotation>> getMetaAnnotated(Class<A> metaAnnotationType);
 
 	/**
 	 * Get a usage of the given annotation {@code type} whose {@code attributeToMatch} attribute value
@@ -208,6 +219,43 @@ <X extends Annotation> AnnotationUsage<X> getNamedAnnotationUsage(
 			String matchName,
 			String attributeToMatch);
 
+	/**
+	 * Functional contract to process an annotation and return a value.
+	 *
+	 * @param <T> The type of the value being returned.
+	 */
+	@FunctionalInterface
+	interface AnnotationUsageProcessor<T> {
+		/**
+		 * The processed value.  May be {@code null} to indicate a "no match"
+		 */
+		T process(AnnotationUsage<? extends Annotation> annotationUsage);
+	}
+
+	/**
+	 * Returns a "matching value" using the passed {@code processor} from the
+	 * annotations, of the passed {@code annotationType}, used on the target.
+	 *
+	 * @apiNote In the case of repeatable annotations, the first usage for which
+	 * the passed {@code processor} does not return {@code null} will be returned.
+	 *
+	 * @return The matching value or {@code null}
+	 *
+	 * @param <T> The type of the value being returned.
+	 * @param <A> The type of annotations to check
+	 */
+	default <T, A extends Annotation> T fromAnnotations(
+			Class<A> annotationType,
+			AnnotationUsageProcessor<T> processor) {
+		final List<AnnotationUsage<A>> annotationUsages = getRepeatedAnnotationUsages( annotationType );
+		for ( AnnotationUsage<A> annotationUsage : annotationUsages ) {
+			final T result = processor.process( annotationUsage );
+			if ( result != null ) {
+				return result;
+			}
+		}
+		return null;
+	}
 
 	/**
 	 * Subset of {@linkplain ElementType annotation targets} supported for mapping annotations
diff --git a/src/test/java/org/hibernate/models/annotations/AnnotationUsageTests.java b/src/test/java/org/hibernate/models/annotations/AnnotationUsageTests.java
