#38 - Add AnnotationTarget#getSingleAnnotationUsage

Author: sebersole

src/main/java/org/hibernate/models/spi/AnnotationTarget.java

@@ -105,6 +105,32 @@ default void forAllAnnotationUsages(Consumer<AnnotationUsage<?>> consumer) {
 	 */
 	<A extends Annotation> AnnotationUsage<A> getAnnotationUsage(Class<A> type);
 
+	/**
+	 * Form of {@linkplain #getAnnotationUsage(AnnotationDescriptor)} which returns {@code null} instead of
+	 * throwing {@linkplain AnnotationAccessException} when more than one usage of the requested
+	 * annotation exists.
+	 */
+	default <A extends Annotation> AnnotationUsage<A> getSingleAnnotationUsage(AnnotationDescriptor<A> descriptor) {
+		try {
+			return getAnnotationUsage( descriptor );
+		}
+		catch (AnnotationAccessException ignore) {
+			return null;
+		}
+	}
+
+	/**
+	 * Form of {@link #getSingleAnnotationUsage(AnnotationDescriptor)} accepting the annotation {@linkplain Class}
+	 */
+	default <A extends Annotation> AnnotationUsage<A> getSingleAnnotationUsage(Class<A> type) {
+		try {
+			return getAnnotationUsage( type );
+		}
+		catch (AnnotationAccessException ignore) {
+			return null;
+		}
+	}
+
 	/**
 	 * Form of {@linkplain #getAnnotationUsage} which also considers meta-annotations -
 	 * annotations on the classes of each {@linkplain #getAllAnnotationUsages() local annotation}.

src/test/java/org/hibernate/models/annotations/AnnotationUsageTests.java

@@ -5,6 +5,7 @@
 import org.hibernate.annotations.Cache;
 import org.hibernate.annotations.CacheConcurrencyStrategy;
 import org.hibernate.internal.util.MutableInteger;
+import org.hibernate.models.AnnotationAccessException;
 import org.hibernate.models.UnknownAnnotationAttributeException;
 import org.hibernate.models.spi.MutableAnnotationUsage;
 import org.hibernate.models.internal.SourceModelBuildingContextImpl;
@@ -369,6 +370,32 @@ void testForEachAnnotation(Index index) {
 		counter.set( 0 );
 		classDetails.forEachAnnotationUsage( NamedQuery.class, entityAnnotationUsage -> counter.increment() );
 		assertThat( counter.get() ).isEqualTo( 2 );
+	}
+
+	@Test
+	void testGetSingleUsageWithJandex() {
+		testGetSingleUsage( buildJandexIndex( SimpleEntity.class ) );
+	}
+
+	@Test
+	void testGetSingleUsageWithoutJandex() {
+		testGetSingleUsage( null );
+	}
+
+	void testGetSingleUsage(Index index) {
+		final SourceModelBuildingContextImpl buildingContext = createBuildingContext( index, SimpleEntity.class );
+		final ClassDetailsRegistry classDetailsRegistry = buildingContext.getClassDetailsRegistry();
+		final ClassDetails classDetails = classDetailsRegistry.getClassDetails( SimpleEntity.class.getName() );
+
+		try {
+			classDetails.getAnnotationUsage( NamedQuery.class );
+			fail( "Expecting an AnnotationAccessException to be thrown" );
+		}
+		catch (AnnotationAccessException expected) {
+			// this is expected
+		}
 
+		final AnnotationUsage<NamedQuery> singleAnnotationUsage = classDetails.getSingleAnnotationUsage( NamedQuery.class );
+		assertThat( singleAnnotationUsage ).isNull();
 	}
 }