More precise language for InvocationContext.getInterceptorBindings()

jakartaee · Jul 18, 2023 · e6eea77 · e6eea77
1 parent cb51fbe
commit e6eea77
Show file tree

Hide file tree

Showing 2 changed files with 33 additions and 25 deletions.
diff --git a/api/src/main/java/jakarta/interceptor/InvocationContext.java b/api/src/main/java/jakarta/interceptor/InvocationContext.java
@@ -143,10 +143,16 @@ public interface InvocationContext {
     Object proceed() throws Exception;
 
     /**
-     * Returns the set of interceptor binding annotations used to associate interceptors with
-     * the {@linkplain #getTarget() target instance} that is being intercepted. Returns an empty set if all
-     * interceptors were associated with the target instance using the {@link Interceptors @Interceptors}
-     * annotation.
+     * Returns the set of interceptor binding annotations for the method or constructor whose
+     * invocation is being intercepted. In case there is no target method or target constructor,
+     * interceptor binding annotations applied to the target class are returned.
+     * <p>
+     * All interceptor binding annotations are returned, including interceptor binding annotations
+     * that associate interceptors of a different interceptor method type, as well as interceptor
+     * binding annotations that associate no interceptor.
+     * <p>
+     * Returns an empty set if no interceptor binding annotation is applied and all interceptors
+     * were associated using the {@link Interceptors @Interceptors} annotation.
      *
      * @return immutable set of interceptor binding annotations, never {@code null}
      * @since Jakarta Interceptors 2.2
@@ -158,14 +164,14 @@ default Set<Annotation> getInterceptorBindings() {
     }
 
     /**
-     * Returns the interceptor binding annotation of given type used to associate interceptors with
-     * the {@linkplain #getTarget() target instance} that is being intercepted. Returns {@code null}
-     * if the {@linkplain #getInterceptorBindings() full set} of interceptor binding annotations
-     * does not contain an annotation of given type, or if all interceptors were associated with
-     * the target instance using the {@link Interceptors @Interceptors} annotation.
+     * Returns the single annotation of given type present in the {@linkplain #getInterceptorBindings() full set}
+     * of interceptor binding annotations.
      * <p>
-     * In case of {@linkplain  java.lang.annotation.Repeatable repeatable} interceptor binding annotations,
-     * {@link #getInterceptorBindings(Class)} should be used instead.
+     * Returns {@code null} if the {@linkplain #getInterceptorBindings() full set} of interceptor
+     * binding annotations does not contain an annotation of given type.
+     * <p>
+     * In case of {@linkplain java.lang.annotation.Repeatable repeatable} interceptor binding
+     * annotations, {@link #getInterceptorBindings(Class)} should be used instead.
      *
      * @param annotationType type of the interceptor binding annotation, must not be {@code null}
      * @return the interceptor binding annotation of given type, may be {@code null}
@@ -181,12 +187,11 @@ default <T extends Annotation> T getInterceptorBinding(Class<T> annotationType)
     }
 
     /**
-     * Returns the set of interceptor binding annotations of given type used to associate interceptors with
-     * the {@linkplain #getTarget() target instance} that is being intercepted. The result is typically
-     * a singleton set, unless {@linkplain java.lang.annotation.Repeatable repeatable} interceptor binding
-     * annotations are used. Returns an empty set if the {@linkplain #getInterceptorBindings() full set}
-     * of interceptor binding annotations does not contain any annotation of given type, or if all interceptors
-     * are associated with the target instance using the {@link Interceptors @Interceptors} annotation.
+     * Returns all annotations of given type present in the {@linkplain #getInterceptorBindings() full set}
+     * of interceptor binding annotations.
+     * <p>
+     * Returns an empty set if the {@linkplain #getInterceptorBindings() full set} of interceptor
+     * binding annotations does not contain any annotation of given type.
      *
      * @param annotationType type of the interceptor binding annotations, must not be {@code null}
      * @return immutable set of interceptor binding annotations of given type, never {@code null}

diff --git a/spec/src/main/asciidoc/2_interceptor_programming_contract.adoc b/spec/src/main/asciidoc/2_interceptor_programming_contract.adoc
@@ -307,14 +307,17 @@ the last interceptor method in the chain validates the target instance.],
 and `null` is returned.
 
 The `getInterceptorBindings` method returns the set of interceptor binding
-annotations that were used to associate interceptors with the target
-instance that is being intercepted. The zero-parameter variant returns all
-interceptor binding annotations, while the variant with a `Class` parameter
-returns only interceptor binding annotations of given type.
-
-The `getInterceptorBinding` method returns the single interceptor binding
-annotation of given type that was used to associate interceptors with
-the target instance that is being intercepted.
+annotations for the method or constructor whose invocation is being intercepted.
+In case there is no target method or target constructor, interceptor binding
+annotations applied to the target class are returned. All interceptor binding
+annotations are returned, including interceptor binding annotations that associate
+interceptors of a different interceptor method type, as well as interceptor
+binding annotations that associate no interceptor. The zero-parameter variant
+returns all interceptor binding annotations, while the variant with a `Class`
+parameter returns only interceptor binding annotations of given type.
+
+The `getInterceptorBinding` method returns the single annotation of given type
+present in the set of interceptor bindings returned by `getInterceptorBindings()`.
 
 [[exceptions]]
 === Exceptions