New method ResourceInfo.getAnnotation()

jaxrs-api/src/main/java/jakarta/ws/rs/container/ResourceInfo.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -16,6 +16,7 @@
 
 package jakarta.ws.rs.container;
 
+import java.lang.annotation.Annotation;
 import java.lang.reflect.Method;
 
 /**
@@ -43,4 +44,45 @@ public interface ResourceInfo {
      * @see #getResourceMethod()
      */
     Class<?> getResourceClass();
+
+    /**
+     * How to handle inheritance of custom annotations
+     *
+     * @author Markus KARG ([email protected])
+     * @since 4.1
+     */
+    public static enum CustomAnnotationsInheritancePolicy {
+
+        /**
+         * Treat custom annotations as JAX-RS annotations according Jakarta REST Specification.
+         */
+        JAX_RS,
+
+        /**
+         * Inherit custom annotations but do not treat them as JAX-RS annotation.
+         */
+        INHERIT,
+
+        /**
+         * Do not inherit custom annoations.
+         */
+        NONE
+    }
+
+    /**
+     * Get the annotation of specified type from the target of a request, or {@code null} if this information is not available.
+     *
+     * This method respects the JAX-RS Annotation Inheritance Policy.
+     * The inheritance policy for custom annotations is to be provided.
+     *
+     * @param <A> the type of the annotation to query for and return if present
+     * @param annotationClass the Class object corresponding to the annotation type
+     * @param customAnnotationInheritancePolicy specifies how to handle inheritance if {@code annotationClass}
+     *        is a custom annotation (ignored for JAX-RS annotations)
+     * @return this element's annotation for the specified annotation type if present, else {@code null}
+     *
+     * @since 4.1
+     */
+    <A extends Annotation> A getResourceAnnotation(Class<A> annotationClass,
+            CustomAnnotationsInheritancePolicy customAnnotationsInheritancePolicy);
 }

jaxrs-spec/src/main/asciidoc/chapters/appendix/_change-log.adoc

@@ -12,6 +12,8 @@
 [[change-log]]
 == Change Log
 
+include::_changes-since-4.0-release.adoc[]
+
 include::_changes-since-3.0-release.adoc[]
 
 include::_changes-since-2.1-release.adoc[]

jaxrs-spec/src/main/asciidoc/chapters/appendix/_changes-since-4.0-release.adoc

@@ -0,0 +1,15 @@
+////
+*******************************************************************
+* Copyright (c) 2025 Eclipse Foundation
+*
+* This specification document is made available under the terms
+* of the Eclipse Foundation Specification License v1.0, which is
+* available at https://www.eclipse.org/legal/efsl.php.
+*******************************************************************
+////
+
+[[changes-since-4.0-release]]
+=== Changes Since 4.0 Release
+
+* <<annotationinheritance>>: `ResourceInfo` has new method `getAnnotation` to
+get annotation on request target, respecting annotation inheritance.

jaxrs-spec/src/main/asciidoc/chapters/resources/_annotationinheritance.adoc

@@ -56,3 +56,27 @@ method designator since it redefines the `@Produces` annotation.
 
 For consistency with other Jakarta EE specifications, it is recommended to
 always repeat annotations instead of relying on annotation inheritance.
+
+This policy can also be applied to _custom_ annotation types provided to
+`ResourceInfo.getAnnotation()`:
+
+[source,java]
+----
+var Tracing tracing = resourceInfo.getAnnotation(Tracing.class, JAX_RS);
+----
+
+In the above, a custom ´@Tracing` annotation on a request target is considered
+_as_ a JAX-RS annotation, effectively being not inherited when a resource method
+holds _any_ JAX-RS annotations, but being inherited _if not_.
+
+Consequently, for _custom_ annotations only, inheritance can optionally be
+"always on" or "always off" instead, effectively ignoring the policy laid out
+above:
+
+[source,java]
+----
+var RolesAllowed rolesAllowed = resourceInfo.getAnnotation(RolesAllowed.class, INHERIT);
+----
+
+In the above, the `@RolesAllowed` annotation is inherited, _even if_ a JAX-RS
+annotation is found directly on the resource method.