Language model and build compatible extensions API clarifications

- renamed `BeanInfo.getName()` to `name()` for consistency
- renamed `ObserverInfo.observedType()` to `eventType()` for clarity
- added `SyntheticComponents.addObserver(Type)` to allow registering
  synthetic observers of parameterized types
- changed `WildcardType` representation to always include an upper
  bound; the `? extends Object` type is no longer represented as `?`
  because the upper bound may be annotated
- improved specification of `AnnotationTarget`, especially around
  repeatable annotation types
- improved specification of `ClassInfo` and `MethodInfo`, especially
  around implicit declarations and `abstract` classes/methods

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BeanInfo.java

@@ -127,7 +127,7 @@ public interface BeanInfo {
      *
      * @return the bean name, or {@code null} if the bean does not have a name
      */
-    String getName();
+    String name();
 
     /**
      * Returns the {@linkplain DisposerInfo disposer} method of this producer-based bean.

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ObserverInfo.java

@@ -29,7 +29,7 @@ public interface ObserverInfo {
      *
      * @return the observed event type of this observer, never {@code null}
      */
-    Type observedType();
+    Type eventType();
 
     /**
      * Returns a collection of observed event qualifiers, represented as {@link AnnotationInfo}.

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/SyntheticComponents.java

@@ -1,5 +1,7 @@
 package jakarta.enterprise.inject.build.compatible.spi;
 
+import jakarta.enterprise.lang.model.types.Type;
+
 /**
  * Allows registering synthetic beans and observers.
  *
@@ -27,4 +29,23 @@ public interface SyntheticComponents {
      * @return a new {@link SyntheticObserverBuilder}, never {@code null}
      */
     <T> SyntheticObserverBuilder<T> addObserver(Class<T> eventType);
+
+    /**
+     * Creates a {@link SyntheticObserverBuilder} that allows configuring a new synthetic observer
+     * for given {@code eventType}. The synthetic observer will be registered at the end of
+     * the {@link Synthesis @Synthesis} method.
+     * <p>
+     * This method is supposed to be called with explicitly provided type arguments. For example,
+     * to define a synthetic observer of event type {@code List<String>}, one would call:
+     * <pre>{@code
+     * // types is of type Types
+     * // syntheticComponents is of type SyntheticComponents
+     * syntheticComponents.<List<String>>addObserver(types.parameterized(List.class, String.class))
+     *     ...
+     * }</pre>
+     *
+     * @param eventType the observed event type of the new synthetic observer, must not be {@code null}
+     * @return a new {@link SyntheticObserverBuilder}, never {@code null}
+     */
+    <T> SyntheticObserverBuilder<T> addObserver(Type eventType);
 }

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/SyntheticObserverBuilder.java

@@ -3,13 +3,15 @@
 import jakarta.enterprise.event.TransactionPhase;
 import jakarta.enterprise.lang.model.AnnotationInfo;
 import jakarta.enterprise.lang.model.declarations.ClassInfo;
+import jakarta.enterprise.lang.model.types.Type;
 
 import java.lang.annotation.Annotation;
 
 /**
  * Builder for synthetic observers.
  * Instances are not reusable. For each synthetic observer, new instance
- * must be created by {@link SyntheticComponents#addObserver(Class)}.
+ * must be created by {@link SyntheticComponents#addObserver(Class)}
+ * or {@link SyntheticComponents#addObserver(Type)}.
  *
  * @param <T> the observed event type of this synthetic observer
  * @since 4.0

lang-model/src/main/java/jakarta/enterprise/lang/model/AnnotationTarget.java

@@ -19,10 +19,15 @@
  *
  * The {@code hasAnnotation}, {@code annotation}, {@code repeatableAnnotation} and {@code annotations} methods
  * may be used to obtain information about annotations present on this annotation target. The phrase
- * "present on this annotation target" means: either the annotation is directly declared on this annotation
- * target, or this annotation target is a class declaration and the annotation is
+ * "present on this annotation target" means: either the annotation is declared or implicitly declared
+ * directly on this annotation target, or this annotation target is a class declaration and the annotation is
  * {@linkplain java.lang.annotation.Inherited inherited} from a superclass.
  * <p>
+ * Note that if more than one annotation of a {@linkplain java.lang.annotation.Repeatable repeatable} annotation type
+ * is declared on an annotation target, only an implicitly declared <em>container annotation</em> is present
+ * on the annotation target; the originally declared annotations are not. If exactly one annotation of a repeatable
+ * annotation type is declared on an annotation target, that annotation is present.
+ * <p>
  * Annotations are represented as {@link AnnotationInfo}, so that implementations of this interface are not required
  * to instantiate the annotation type.
  * <p>
@@ -94,10 +99,13 @@ public interface AnnotationTarget {
     <T extends Annotation> AnnotationInfo annotation(Class<T> annotationType);
 
     /**
-     * Returns a collection of annotations of given repeatable annotation type
-     * (an annotation type that is meta-annotated {@link java.lang.annotation.Repeatable @Repeatable})
-     * present on this annotation target. Returns an empty collection if no such
-     * annotation is present.
+     * Returns a collection of annotations of given {@linkplain java.lang.annotation.Repeatable repeatable}
+     * {@code annotationType} that are present on this annotation target. Returns an empty collection if
+     * no such annotation is present.
+     * <p>
+     * For the purpose of this method, annotations in the {@code value} member of a container annotation,
+     * as defined using {@link java.lang.annotation.Repeatable @Repeatable}, are considered to be present
+     * on the annotation target on which the container annotation is present.
      *
      * @param annotationType the {@code @Repeatable} annotation type, must not be {@code null}
      * @param <T> the annotation generic type

lang-model/src/main/java/jakarta/enterprise/lang/model/declarations/ClassInfo.java

@@ -102,6 +102,7 @@ public interface ClassInfo extends DeclarationInfo {
 
     /**
      * Returns whether this class is an interface.
+     * If this class is an annotation, returns {@code false}.
      *
      * @return whether this class is an interface
      */
@@ -129,7 +130,12 @@ public interface ClassInfo extends DeclarationInfo {
     boolean isRecord();
 
     /**
-     * Returns whether this class is {@code abstract}.
+     * Returns whether this class is abstract.
+     * <p>
+     * A plain class is abstract if declared {@code abstract}.
+     * An enum is abstract if it declares {@code abstract} methods.
+     * An interface or an annotation is always abstract.
+     * A record is never abstract.
      *
      * @return whether this class is {@code abstract}
      */
@@ -151,19 +157,20 @@ public interface ClassInfo extends DeclarationInfo {
     int modifiers();
 
     /**
-     * Returns a collection of {@linkplain MethodInfo constructors} declared in this class.
-     * Constructors declared in direct or indirect superclasses are not included.
+     * Returns a collection of {@linkplain MethodInfo constructors} declared or implicitly declared
+     * in this class. Constructors declared in direct or indirect superclasses are not included.
      * <p>
-     * If this class is an interface, returns an empty collection.
+     * If this class is an interface or an annotation, returns an empty collection.
      *
      * @return immutable collection of constructors, never {@code null}
      */
     Collection<MethodInfo> constructors();
 
     /**
-     * Returns a collection of {@linkplain MethodInfo methods} declared in this class and all
-     * its superclasses up to and excluding {@code java.lang.Object}, as well as all direct and
-     * indirect superinterfaces. If this class is an interface, only superinterfaces are considered.
+     * Returns a collection of {@linkplain MethodInfo methods} declared or implicitly declared
+     * in this class and all its superclasses up to and excluding {@code java.lang.Object},
+     * as well as all direct and indirect superinterfaces. If this class is an interface,
+     * only superinterfaces are considered. Methods implicitly declared in interfaces are omitted.
      * <p>
      * If the collection of methods described above contains multiple methods with the same signature,
      * all such methods are returned. {@link MethodInfo#declaringClass() MethodInfo.declaringClass}
@@ -177,9 +184,10 @@ public interface ClassInfo extends DeclarationInfo {
     Collection<MethodInfo> methods();
 
     /**
-     * Returns a collection of {@linkplain FieldInfo fields} declared in this class and all
-     * its superclasses up to and excluding {@code java.lang.Object}, as well as all direct and
-     * indirect superinterfaces. If this class is an interface, only superinterfaces are considered.
+     * Returns a collection of {@linkplain FieldInfo fields} declared or implicitly declared
+     * in this class and all its superclasses up to and excluding {@code java.lang.Object},
+     * as well as all direct and indirect superinterfaces. If this class is an interface,
+     * only superinterfaces are considered.
      * <p>
      * If the collection of fields described above contains multiple fields with the same name,
      * all such fields are returned. {@link FieldInfo#declaringClass() FieldInfo.declaringClass}

lang-model/src/main/java/jakarta/enterprise/lang/model/declarations/MethodInfo.java

@@ -18,7 +18,7 @@ public interface MethodInfo extends DeclarationInfo {
     String name();
 
     /**
-     * Returns a list of {@linkplain ParameterInfo parameters} declared on this method.
+     * Returns a list of {@linkplain ParameterInfo parameters} declared or implicitly declared on this method.
      *
      * @return immutable list of {@linkplain ParameterInfo parameterts}, never {@code null}
      */
@@ -73,7 +73,13 @@ public interface MethodInfo extends DeclarationInfo {
     boolean isStatic();
 
     /**
-     * Returns whether this method is {@code abstract}.
+     * Returns whether this method is abstract.
+     * <p>
+     * A {@code static} method is never abstract.
+     * An instance method declared on a plain class or an enum is abstract if declared {@code abstract}.
+     * An instance method declared on an interface is abstract unless declared {@code default}.
+     * An instance method declared on an annotation type is always abstract.
+     * An instance method declared on a record type is never abstract.
      *
      * @return whether this method is {@code abstract}.
      */

lang-model/src/main/java/jakarta/enterprise/lang/model/types/WildcardType.java

@@ -5,9 +5,10 @@
  * <ul>
  * <li>{@code ? extends Number}: has an upper bound</li>
  * <li>{@code ? super Number}: has a lower bound</li>
- * <li>{@code ?}: unbounded, has neither upper bound nor lower bound</li>
+ * <li>{@code ?}: unbounded, has an implicit upper bound of {@code java.lang.Object}</li>
  * </ul>
- * Note that {@code ? extends Object} is equivalent to {@code ?} and is represented as such.
+ * Note that {@code ?} is equivalent to {@code ? extends Object} and is represented as such.
+ * Therefore, either {@link #upperBound()} or {@link #lowerBound()} always returns non-{@code null}.
  */
 public interface WildcardType extends Type {
     /**

spec/src/main/asciidoc/core/spi_lite.asciidoc

@@ -266,7 +266,7 @@ public interface BeanInfo {
     FieldInfo producerField();
     boolean isAlternative();
     Integer priority();
-    String getName();
+    String name();
     DisposerInfo disposer();
     Collection<StereotypeInfo> stereotypes();
     Collection<InjectionPointInfo> injectionPoints();
@@ -288,7 +288,7 @@ When an extension method declares a parameter of type `InterceptorInfo`, it will
 [source, java]
 ----
 public interface ObserverInfo {
-    Type observedType();
+    Type eventType();
     Collection<AnnotationInfo> qualifiers();
     ClassInfo declaringClass();
     MethodInfo observerMethod();
@@ -326,6 +326,7 @@ Extension methods annotated `@Synthesis` may declare parameters of the following
 public interface SyntheticComponents {
     <T> SyntheticBeanBuilder<T> addBean(Class<T> beanClass);
     <T> SyntheticObserverBuilder<T> addObserver(Class<T> eventType);
+    <T> SyntheticObserverBuilder<T> addObserver(Type eventType);
 }
 ----