From deb6d748e3634371987be8a600d230b87e1fd7f2 Mon Sep 17 00:00:00 2001 From: Ladislav Thon Date: Fri, 23 Jul 2021 16:51:00 +0200 Subject: [PATCH] remove App{Archive,ArchiveConfig,Deployment}, rename AppArchiveBuilder and ContextBuilder The `AppArchive`, `AppArchiveConfig` and `AppDeployment` types were redundant. Moreover, they looked like they can access whole world, which prevents certain kinds of implementations. (Some effort was made to design the API in these types so that whole world access is not necessary, but it's a leaky abstraction.) For those reasons, these types are removed altogether. The `AppArchiveBuilder` type is renamed to `ScannedClasses`, which is more descriptive (and shorter). The `addSubtypesOf` method is removed, because it can't be implemented in certain environments (notably, Portable Extensions). The `ContextBuilder` type is renamed to `ContextConfig`, because it isn't really used in the usual builder way and is quite close to the other existing `*Config` types. Additionally, some documentation is improved, especially for types in the `@Discovery` phase. --- .../build/compatible/spi/AppArchive.java | 162 ------------------ .../compatible/spi/AppArchiveBuilder.java | 10 -- .../compatible/spi/AppArchiveConfig.java | 66 ------- .../build/compatible/spi/AppDeployment.java | 138 --------------- .../spi/BuildCompatibleExtension.java | 5 +- ...ContextBuilder.java => ContextConfig.java} | 34 ++-- .../build/compatible/spi/Discovery.java | 4 +- .../build/compatible/spi/Enhancement.java | 4 +- .../build/compatible/spi/ExactType.java | 2 +- .../compatible/spi/ExtensionPriority.java | 4 +- .../inject/build/compatible/spi/Messages.java | 6 + .../build/compatible/spi/MetaAnnotations.java | 36 +++- .../build/compatible/spi/ScannedClasses.java | 15 ++ .../build/compatible/spi/SubtypesOf.java | 2 +- .../build/compatible/spi/Synthesis.java | 2 - .../build/compatible/spi/Validation.java | 2 - 16 files changed, 84 insertions(+), 408 deletions(-) delete mode 100644 api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchive.java delete mode 100644 api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchiveBuilder.java delete mode 100644 api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchiveConfig.java delete mode 100644 api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppDeployment.java rename api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/{ContextBuilder.java => ContextConfig.java} (51%) create mode 100644 api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ScannedClasses.java diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchive.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchive.java deleted file mode 100644 index 67db8acb..00000000 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchive.java +++ /dev/null @@ -1,162 +0,0 @@ -package jakarta.enterprise.inject.build.compatible.spi; - -import jakarta.enterprise.lang.model.declarations.ClassInfo; -import jakarta.enterprise.lang.model.declarations.FieldInfo; -import jakarta.enterprise.lang.model.declarations.MethodInfo; -import jakarta.enterprise.lang.model.types.Type; -import java.lang.annotation.Annotation; -import java.util.function.Consumer; - -// TODO remove entirely? -public interface AppArchive { - ClassQuery classes(); - - MethodQuery constructors(); // no static initializers - - MethodQuery methods(); // no constructors nor static initializers - - FieldQuery fields(); - - /** - * The {@code exactly} and {@code subtypeOf} methods are additive. - * When called multiple times, they form a union of requested classes (not an intersection). - * For example, - * 
{@code
-     * appArchive.classes()
-     *     .exactly(Foo.class)
-     *     .subtypeOf(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for the {@code Foo} class and all subtypes of the {@code Bar} class. - *

- * The {@code annotatedWith} methods are additive. - * When called multiple times, they form a union of requested annotations (not an intersection). - * For example, - * 

{@code
-     * appArchive.classes()
-     *     .annotatedWith(Foo.class)
-     *     .annotatedWith(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all classes annotated either with {@code @Foo} or with {@code @Bar} (or both). - */ - interface ClassQuery { - ClassQuery exactly(Class clazz); - - ClassQuery subtypeOf(Class clazz); - - ClassQuery annotatedWith(Class annotationType); - - void forEach(Consumer> consumer); - } - - /** - * The {@code declaredOn} method is additive. - * When called multiple times, it forms a union of requested classes (not an intersection). - * For example, - * 
{@code
-     * appArchive.methods()
-     *     .declaredOn(appArchive.classes().exactly(Foo.class))
-     *     .declaredOn(appArchive.classes().subtypeOf(Bar.class))
-     *     .forEach(...)
-     * }
- * runs given code for all methods declared on the {@code Foo} class and on all subtypes of the {@code Bar} class. - * Note that this example can be rewritten as - * 
{@code
-     * appArchive.methods()
-     *     .declaredOn(appArchive.classes().exactly(Foo.class).subtypeOf(Bar.class))
-     *     .forEach(...)
-     * }
- * which is probably easier to understand. - *

- * The {@code withReturnType} methods are additive. - * When called multiple times, they form a union of requested return types (not an intersection). - * For example, - * 

{@code
-     * appArchive.methods()
-     *     .withReturnType(Foo.class)
-     *     .withReturnType(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all methods that return either {@code Foo} or {@code Bar}. - *

- * The {@code annotatedWith} methods are additive. - * When called multiple times, they form a union of requested annotations (not an intersection). - * For example, - * 

{@code
-     * appArchive.methods()
-     *     .annotatedWith(Foo.class)
-     *     .annotatedWith(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all methods annotated either with {@code @Foo} or with {@code @Bar} (or both). - */ - interface MethodQuery { - MethodQuery declaredOn(ClassQuery classes); - - // equivalent to `withReturnType(Types.of(type))` - MethodQuery withReturnType(Class type); - - MethodQuery withReturnType(Type type); - - // TODO parameters? - - MethodQuery annotatedWith(Class annotationType); - - void forEach(Consumer> consumer); - } - - /** - * The {@code declaredOn} method is additive. - * When called multiple times, it forms a union of requested classes (not an intersection). - * For example, - * 
{@code
-     * appArchive.fields()
-     *     .declaredOn(appArchive.classes().exactly(Foo.class))
-     *     .declaredOn(appArchive.classes().subtypeOf(Bar.class))
-     *     .forEach(...)
-     * }
- * runs given code for all fields declared on the {@code Foo} class and on all subtypes of the {@code Bar} class. - * Note that this example can be rewritten as - * 
{@code
-     * appArchive.fields()
-     *     .declaredOn(appArchive.classes().exactly(Foo.class).subtypeOf(Bar.class))
-     *     .forEach()
-     * }
- * which is probably easier to understand. - *

- * The {@code ofType} methods are additive. - * When called multiple times, they form a union of requested field types (not an intersection). - * For example, - * 

{@code
-     * appArchive.fields()
-     *     .ofType(Foo.class)
-     *     .ofType(Bar.class)
-     *     .forEach()
-     * }
- * runs given code for all fields that are of type either {@code Foo} or {@code Bar}. - *

- * The {@code annotatedWith} methods are additive. - * When called multiple times, they form a union of requested annotations (not an intersection). - * For example, - * 

{@code
-     * appArchive.fields()
-     *     .annotatedWith(Foo.class)
-     *     .annotatedWith(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all fields annotated either with {@code @Foo} or with {@code @Bar} (or both). - */ - interface FieldQuery { - FieldQuery declaredOn(ClassQuery classes); - - // equivalent to `withReturnType(Types.of(type))` - FieldQuery ofType(Class type); - - FieldQuery ofType(Type type); - - FieldQuery annotatedWith(Class annotationType); - - void forEach(Consumer> consumer); - } -} diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchiveBuilder.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchiveBuilder.java deleted file mode 100644 index b05e7437..00000000 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchiveBuilder.java +++ /dev/null @@ -1,10 +0,0 @@ -package jakarta.enterprise.inject.build.compatible.spi; - -// TODO better name -public interface AppArchiveBuilder { - void add(String fullyQualifiedClassName); - - // TODO adds the type itself or not? (in theory yes, as subtyping is reflexive) - // TODO looks like it can't be implemented on top of Portable Extensions, so maybe remove? - void addSubtypesOf(String fullyQualifiedClassName); -} diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchiveConfig.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchiveConfig.java deleted file mode 100644 index aa02e4c0..00000000 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppArchiveConfig.java +++ /dev/null @@ -1,66 +0,0 @@ -package jakarta.enterprise.inject.build.compatible.spi; - -import jakarta.enterprise.lang.model.types.Type; -import java.lang.annotation.Annotation; -import java.util.function.Consumer; - -// TODO remove entirely, if we remove AppArchive/AppDeployment -// TODO maybe AppArchiveConfig shouldn't extend AppArchive, and *ConfigQuery shouldn't extend *Query -public interface AppArchiveConfig extends AppArchive { - @Override - ClassConfigQuery classes(); - - @Override - MethodConfigQuery constructors(); // no static initializers - - @Override - MethodConfigQuery methods(); // no constructors nor static initializers - - @Override - FieldConfigQuery fields(); - - interface ClassConfigQuery extends ClassQuery { - @Override - ClassConfigQuery exactly(Class clazz); - - @Override - ClassConfigQuery subtypeOf(Class clazz); - - @Override - ClassConfigQuery annotatedWith(Class annotationType); - - void configure(Consumer> consumer); - } - - interface MethodConfigQuery extends MethodQuery { - @Override - MethodConfigQuery declaredOn(ClassQuery classes); - - @Override - MethodConfigQuery withReturnType(Class type); - - @Override - MethodConfigQuery withReturnType(Type type); - - @Override - MethodConfigQuery annotatedWith(Class annotationType); - - void configure(Consumer> consumer); - } - - interface FieldConfigQuery extends FieldQuery { - @Override - FieldConfigQuery declaredOn(ClassQuery classes); - - @Override - FieldConfigQuery ofType(Class type); - - @Override - FieldConfigQuery ofType(Type type); - - @Override - FieldConfigQuery annotatedWith(Class annotationType); - - void configure(Consumer> consumer); - } -} diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppDeployment.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppDeployment.java deleted file mode 100644 index dcfd4a59..00000000 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AppDeployment.java +++ /dev/null @@ -1,138 +0,0 @@ -package jakarta.enterprise.inject.build.compatible.spi; - -import jakarta.enterprise.lang.model.declarations.ClassInfo; -import jakarta.enterprise.lang.model.types.Type; -import java.lang.annotation.Annotation; -import java.util.function.Consumer; - -// TODO remove entirely? -public interface AppDeployment { - BeanQuery beans(); - - ObserverQuery observers(); - - /** - * The {@code scope} methods are additive. - * When called multiple times, they form a union of requested scope types (not an intersection). - * For example, - * 
{@code
-     * appDeployment.beans()
-     *     .scope(Foo.class)
-     *     .scope(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all beans with the {@code @Foo} scope or the {@code @Bar} scope. - *

- * The {@code type} methods are additive. - * When called multiple times, they form a union of requested bean types (not an intersection). - * For example, - * 

{@code
-     * appDeployment.beans()
-     *     .type(Foo.class)
-     *     .type(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all beans with the {@code Foo} type or the {@code Bar} type (or both). - * Note that bean type is not just the class which declares the bean (or return type of a producer method, - * or type of producer field). All superclasses and superinterfaces are also included in the set of bean types. - *

- * The {@code qualifier} methods are additive. - * When called multiple times, they form a union of requested qualifiers (not an intersection). - * For example, - * 

{@code
-     * appDeployment.beans()
-     *     .qualifier(Foo.class)
-     *     .qualifier(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all beans with the {@code @Foo} qualifier or the {@code @Bar} qualifier (or both). - *

- * The {@code declaringClass} methods are additive. - * When called multiple times, they form a union of requested declaration classes (not an intersection). - * For example, - * 

{@code
-     * appDeployment.beans()
-     *     .declaringClass(Foo.class)
-     *     .declaringClass(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all beans declared on the {@code Foo} class or the {@code Bar} class. - */ - interface BeanQuery { - BeanQuery scope(Class scopeAnnotation); - - BeanQuery scope(ClassInfo scopeAnnotation); - - BeanQuery type(Class beanType); - - BeanQuery type(ClassInfo beanType); - - BeanQuery type(Type beanType); - - BeanQuery qualifier(Class qualifierAnnotation); - - BeanQuery qualifier(ClassInfo qualifierAnnotation); - - BeanQuery declaringClass(Class declaringClass); - - BeanQuery declaringClass(ClassInfo declaringClass); - - void forEach(Consumer> consumer); - - void ifNone(Runnable runnable); - } - - /** - * The {@code observedType} methods are additive. - * When called multiple times, they form a union of requested observer types (not an intersection). - * For example, - * 
{@code
-     * appDeployment.observers()
-     *     .observedType(Foo.class)
-     *     .observedType(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all observers that observe the {@code Foo} event type or the {@code Bar} event type. - *

- * The {@code qualifier} methods are additive. - * When called multiple times, they form a union of requested qualifiers (not an intersection). - * For example, - * 

{@code
-     * appDeployment.observers()
-     *     .qualifier(Foo.class)
-     *     .qualifier(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all observers with the {@code @Foo} qualifier or the {@code @Bar} qualifier (or both). - *

- * The {@code declaringClass} methods are additive. - * When called multiple times, they form a union of requested declaration classes (not an intersection). - * For example, - * 

{@code
-     * appDeployment.observers()
-     *     .declaringClass(Foo.class)
-     *     .declaringClass(Bar.class)
-     *     .forEach(...)
-     * }
- * runs given code for all observers declared on the {@code Foo} class or the {@code Bar} class. - */ - interface ObserverQuery { - ObserverQuery observedType(Class observedType); - - ObserverQuery observedType(ClassInfo observedType); - - ObserverQuery observedType(Type observedType); - - ObserverQuery qualifier(Class qualifierAnnotation); - - ObserverQuery qualifier(ClassInfo qualifierAnnotation); - - ObserverQuery declaringClass(Class declaringClass); - - ObserverQuery declaringClass(ClassInfo declaringClass); - - void forEach(Consumer> consumer); - - void ifNone(Runnable runnable); - } -} diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BuildCompatibleExtension.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BuildCompatibleExtension.java index 914d4e96..b1491380 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BuildCompatibleExtension.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BuildCompatibleExtension.java @@ -9,10 +9,11 @@ * Extensions can define arbitrary {@code public}, non-{@code static}, {@code void}-returning methods * without type parameters, annotated with one of the extension annotations. *

- * Extension processing occurs in 4 phases, corresponding to 4 extension annotations: + * Extension processing occurs in 5 phases, corresponding to 5 extension annotations: *

    *
  • {@link Discovery @Discovery}
    • *
  • {@link Enhancement @Enhancement}
    • + *
  • {@link Processing @Processing}
    • *
  • {@link Synthesis @Synthesis}
    • *
  • {@link Validation @Validation}
    • *
@@ -21,7 +22,7 @@ * on the particular processing phase and is documented in the corresponding extension annotation. * All the parameters will be provided by the container when the extension is invoked. *

- * Extension methods can be assigned a priority using {@link jakarta.enterprise.inject.build.compatible.spi.ExtensionPriority @ExtensionPriority}. + * Extension methods can be assigned a priority using {@link ExtensionPriority @ExtensionPriority}. * Note that priority only affects order of extensions in a single phase. *

* If the extension declares multiple methods, they are all invoked on the same instance of the class. diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ContextBuilder.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ContextConfig.java similarity index 51% rename from api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ContextBuilder.java rename to api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ContextConfig.java index dcaba9b1..7b2ad7bb 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ContextBuilder.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ContextConfig.java @@ -3,17 +3,22 @@ import java.lang.annotation.Annotation; import jakarta.enterprise.context.spi.AlterableContext; -public interface ContextBuilder { +/** + * Allows configuring custom scope and context. The only mandatory method is + * {@link ContextConfig#implementation(Class)}, other methods are optional. + * If they aren't called, correct value is deduced from the context implementation class. + */ +public interface ContextConfig { /** * If implementation class is defined using {@link #implementation(Class)}, * this method doesn't have to be called. If it is, it overrides the scope annotation * as defined by the implementation class. * * @param scopeAnnotation scope annotation of the context - * @return this {@code ContextBuilder} + * @return this {@code ContextConfig} */ - // if called multiple times, last call wins - ContextBuilder scope(Class scopeAnnotation); + // TODO if called multiple times, last call wins? or only allow calling once? + ContextConfig scope(Class scopeAnnotation); /** * If scope annotation is defined using {@link #scope(Class)}, @@ -21,23 +26,22 @@ public interface ContextBuilder { * as defined by the scope annotation. * * @param isNormal whether the scope is normal - * @return this {@code ContextBuilder} + * @return this {@code ContextConfig} */ - // if called multiple times, last call wins - ContextBuilder normal(boolean isNormal); + // TODO if called multiple times, last call wins? or only allow calling once? + ContextConfig normal(boolean isNormal); /** - * Defines the context implementation class. - * The implementation class typically provides the scope annotations, and therefore + * Defines the context implementation class. It must be {@code public} and + * have a {@code public} zero-parameter constructor. + *

+ * The implementation class typically provides the scope annotation, and therefore * also whether the scope is a normal scope or pseudoscope, but this can be overridden * using {@link #scope(Class)} and {@link #normal(boolean)}. - *

- * Implementations can impose additional restrictions on what valid parameters are; - * they don't have to accept all implementations of {@link AlterableContext}. * * @param implementationClass context object implementation class - * @return this {@code ContextBuilder} + * @return this {@code ContextConfig} */ - // if called multiple times, last call wins - ContextBuilder implementation(Class implementationClass); + // TODO if called multiple times, last call wins? or only allow calling once? + ContextConfig implementation(Class implementationClass); } diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Discovery.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Discovery.java index cbfad85e..2fa8b6e8 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Discovery.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Discovery.java @@ -7,12 +7,12 @@ /** * 1st phase of CDI Lite extension processing. - * Allow registering additional classes to become part of the application. + * Allow registering additional classes to be scanned during bean discovery. * Also allows registering custom CDI meta-annotations. *

* Methods annotated {@code @Discovery} can define parameters of these types: *

    - *
  • {@link AppArchiveBuilder}: to add classes to application
    • + *
  • {@link ScannedClasses}: to register classes to be scanned during bean discovery
    • *
  • {@link MetaAnnotations}: to register custom meta-annotations: * qualifiers, interceptor bindings, stereotypes and scopes
    • *
  • {@link Messages}: to produce log messages and validation errors
    • diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Enhancement.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Enhancement.java index 8d494bee..41d7e703 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Enhancement.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Enhancement.java @@ -14,10 +14,8 @@ *
  • {@link ClassConfig ClassConfig}
    • *
  • {@link MethodConfig MethodConfig}
    • *
  • {@link FieldConfig FieldConfig}
    • - *
  • {@link AppArchiveConfig AppArchiveConfig}
    • *
- * If the parameter is {@code ClassConfig}, {@code MethodConfig} or {@code FieldConfig}, the method - * must have at least one annotation {@link ExactType @ExactType} or {@link SubtypesOf @SubtypesOf}. + * The method must also have at least one annotation {@link ExactType @ExactType} or {@link SubtypesOf @SubtypesOf}. *

* You can also declare a parameter of type {@link Messages Messages} to produce log messages and validation errors. *

diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ExactType.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ExactType.java index 141ccb4f..a15e247b 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ExactType.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ExactType.java @@ -10,7 +10,7 @@ /** * Constraints the {@link Enhancement @Enhancement} or {@link Processing @Processing} method to given types. *

- * If the {@code Enhancement} method has a parameter of type {@code ClassConfig}, + * If the {@code @Enhancement} method has a parameter of type {@code ClassConfig}, * the method is called once for each given type. * If the {@code @Enhancement} method has a parameter of type {@code MethodConfig} or {@code FieldConfig}, * the method is called once for each method or field of each given type. diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ExtensionPriority.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ExtensionPriority.java index 6ec2ca72..93bf41a5 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ExtensionPriority.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ExtensionPriority.java @@ -14,11 +14,11 @@ * * @see BuildCompatibleExtension */ +// TODO this should be removed and @Priority should be used instead; +// see https://github.com/eclipse-ee4j/common-annotations-api/pull/87 @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface ExtensionPriority { - // TODO propose allowing @Priority to be present on methods - /** * @return the priority value */ diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Messages.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Messages.java index 86bb9767..b2695f67 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Messages.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Messages.java @@ -2,6 +2,10 @@ import jakarta.enterprise.lang.model.AnnotationTarget; +/** + * Allows logging and producing errors during {@link BuildCompatibleExtension} execution. + * If an error is produced, application deployment will fail. + */ public interface Messages { /** * Add a generic information message that is not related to any particular element, or that information is not known. @@ -85,6 +89,7 @@ public interface Messages { /** * Add an error which is related to given {@link BeanInfo}. + * * @param message error message * @param relatedTo bean to which the message is related */ @@ -92,6 +97,7 @@ public interface Messages { /** * Add an error which is related to given {@link ObserverInfo}. + * * @param message error message * @param relatedTo observer to which the message is related */ diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/MetaAnnotations.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/MetaAnnotations.java index b3ee5c33..10fed9fc 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/MetaAnnotations.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/MetaAnnotations.java @@ -3,16 +3,48 @@ import java.lang.annotation.Annotation; import java.util.function.Consumer; +/** + * Allows registering custom CDI meta-annotations: qualifiers, interceptor bindings, + * stereotypes, and custom scopes. + * + * @see #addQualifier(Class, Consumer) + * @see #addInterceptorBinding(Class, Consumer) + * @see #addStereotype(Class, Consumer) + * @see #addContext() + */ public interface MetaAnnotations { // TODO this API style is not very common, and makes addContext too different // I only added it to make Quarkus implementation easier, but should definitely be reconsidered + /** + * Registers {@code annotation} as a qualifier annotation. Only makes sense if the annotation + * isn't meta-annotated {@code @Qualifier}. + * + * @param annotation annotation type + * @param config allows transforming annotations on the {@code annotation} + */ void addQualifier(Class annotation, Consumer> config); + /** + * Registers {@code annotation} as an interceptor binding annotation. Only makes sense if the annotation + * isn't meta-annotated {@code @InterceptorBinding}. + * + * @param annotation annotation type + * @param config allows transforming annotations on the {@code annotation} + */ void addInterceptorBinding(Class annotation, Consumer> config); + /** + * Registers {@code annotation} as a stereotype annotation. Only makes sense if the annotation + * isn't meta-annotated {@code @Stereotype}. + * + * @param annotation annotation type + * @param config allows transforming annotations on the {@code annotation} + */ void addStereotype(Class annotation, Consumer> config); - // includes defining the scope annotation - ContextBuilder addContext(); + /** + * Registers custom context as configured by the returned {@link ContextConfig}. + */ + ContextConfig addContext(); } diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ScannedClasses.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ScannedClasses.java new file mode 100644 index 00000000..0f0f4810 --- /dev/null +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ScannedClasses.java @@ -0,0 +1,15 @@ +package jakarta.enterprise.inject.build.compatible.spi; + +/** + * Allows registering additional classes to be scanned during bean discovery. + * Annotations on these classes can later be transformed using {@link Enhancement @Enhancement}. + */ +public interface ScannedClasses { + /** + * Adds a class with given name to the set of classes to be scanned during bean discovery. + * + * @param className binary name of the class, as defined by The Java™ Language Specification; + * in other words, the class name as returned by {@link Class#getName()} + */ + void add(String className); +} diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/SubtypesOf.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/SubtypesOf.java index cde9c95d..790861d3 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/SubtypesOf.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/SubtypesOf.java @@ -8,7 +8,7 @@ /** * Constraints the {@link Enhancement @Enhancement} method to subtypes of given types. - * If the {@code Enhancement} method has a parameter of type {@code ClassConfig}, + * If the {@code @Enhancement} method has a parameter of type {@code ClassConfig}, * the method is called once for each subtype of each given type. * If the {@code @Enhancement} method has a parameter of type {@code MethodConfig} or {@code FieldConfig}, * the method is called once for each method or field of each subtype of each given type. diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Synthesis.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Synthesis.java index 7840b1f7..93ff25c5 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Synthesis.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Synthesis.java @@ -11,8 +11,6 @@ *

* Methods annotated {@code @Synthesis} can define parameters of these types: *

    - *
  • {@link AppArchive}: to find declarations in the application
    • - *
  • {@link AppDeployment}: to find beans and observers in the application
    • *
  • {@link SyntheticComponents}: to add synthetic beans and observers to the application
    • *
  • {@link Messages}: to produce log messages and validation errors
    • *
diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Validation.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Validation.java index 8361f28d..19db3e0d 100644 --- a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Validation.java +++ b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Validation.java @@ -11,8 +11,6 @@ *

* Methods annotated {@code @Validation} can define parameters of these types: *

    - *
  • {@link AppArchive}: to find declarations in the application
    • - *
  • {@link AppDeployment}: to find beans and observers in the application
    • *
  • {@link Messages}: to produce log messages and validation errors
    • *
* If you need to create instances of {@link jakarta.enterprise.lang.model.types.Type Type}, you can also declare