Issue #229 document scope for beans, qualifier limitations and example

Signed-off-by: Nathan Rauh <[email protected]>

api/src/main/java/jakarta/enterprise/concurrent/ContextServiceDefinition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021,2023 Contributors to the Eclipse Foundation
+ * Copyright (c) 2021,2024 Contributors to the Eclipse Foundation
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -23,6 +23,10 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.spi.Producer;
+import jakarta.inject.Qualifier;
+
 /**
  * <p>Defines a {@link ContextService}
  * to be injected into
@@ -139,6 +143,14 @@
      * {@code ContextServiceDefinition} does not automatically produce
      * bean instances for any injection points.</p>
      *
+     * <p>When the qualifiers list is non-empty, the container creates
+     * a {@link ContextService} instance and registers
+     * an {@link ApplicationScoped} bean for it with the specified qualifiers.
+     * The life cycle of the bean aligns with the life cycle of the application
+     * and the bean is not accessible from outside of the application.
+     * Applications must not configure a {@code java:global} {@link #name() name}
+     * if also configuring a non-empty list of qualifiers.</p>
+     *
      * <p>Applications can define their own {@link Producer Producers}
      * for {@link ContextService} injection points as long as the
      * qualifier annotations on the producer do not conflict with the

api/src/main/java/jakarta/enterprise/concurrent/ManagedExecutorDefinition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021,2023 Contributors to the Eclipse Foundation
+ * Copyright (c) 2021,2024 Contributors to the Eclipse Foundation
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -23,6 +23,7 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import jakarta.enterprise.context.ApplicationScoped;
 import jakarta.enterprise.inject.spi.Producer;
 import jakarta.inject.Qualifier;
 
@@ -129,6 +130,14 @@
      * {@code ManagedExecutorDefinition} does not automatically produce
      * bean instances for any injection points.</p>
      *
+     * <p>When the qualifiers list is non-empty, the container creates
+     * a {@link ManagedExecutorService} instance and registers
+     * an {@link ApplicationScoped} bean for it with the specified qualifiers.
+     * The life cycle of the bean aligns with the life cycle of the application
+     * and the bean is not accessible from outside of the application.
+     * Applications must not configure a {@code java:global} {@link #name() name}
+     * if also configuring a non-empty list of qualifiers.</p>
+     *
      * <p>Applications can define their own {@link Producer Producers}
      * for {@link ManagedExecutorService} injection points as long as the
      * qualifier annotations on the producer do not conflict with the

api/src/main/java/jakarta/enterprise/concurrent/ManagedScheduledExecutorDefinition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021,2023 Contributors to the Eclipse Foundation
+ * Copyright (c) 2021,2024 Contributors to the Eclipse Foundation
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -23,6 +23,10 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.spi.Producer;
+import jakarta.inject.Qualifier;
+
 /**
  * <p>Defines a {@link ManagedScheduledExecutorService}
  * to be injected into
@@ -126,6 +130,14 @@
      * {@code ManagedScheduledExecutorDefinition} does not automatically produce
      * bean instances for any injection points.</p>
      *
+     * <p>When the qualifiers list is non-empty, the container creates
+     * a {@link ManagedScheduledExecutorService} instance and registers
+     * an {@link ApplicationScoped} bean for it with the specified qualifiers.
+     * The life cycle of the bean aligns with the life cycle of the application
+     * and the bean is not accessible from outside of the application.
+     * Applications must not configure a {@code java:global} {@link #name() name}
+     * if also configuring a non-empty list of qualifiers.</p>
+     *
      * <p>Applications can define their own {@link Producer Producers}
      * for {@link ManagedScheduledExecutorService} injection points as long as the
      * qualifier annotations on the producer do not conflict with the

api/src/main/java/jakarta/enterprise/concurrent/ManagedThreadFactoryDefinition.java

@@ -23,6 +23,10 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.spi.Producer;
+import jakarta.inject.Qualifier;
+
 /**
  * <p>Defines {@link ManagedThreadFactory} instances
  * to be injected into
@@ -124,6 +128,14 @@
      * {@code ManagedThreadFactoryDefinition} does not automatically produce
      * bean instances for any injection points.</p>
      *
+     * <p>When the qualifiers list is non-empty, the container creates
+     * a {@link ManagedThreadFactory} instance and registers
+     * an {@link ApplicationScoped} bean for it with the specified qualifiers.
+     * The life cycle of the bean aligns with the life cycle of the application
+     * and the bean is not accessible from outside of the application.
+     * Applications must not configure a {@code java:global} {@link #name() name}
+     * if also configuring a non-empty list of qualifiers.</p>
+     *
      * <p>Applications can define their own {@link Producer Producers}
      * for {@link ManagedThreadFactory} injection points as long as the
      * qualifier annotations on the producer do not conflict with the

specification/src/main/asciidoc/jakarta-concurrency.adoc

@@ -2367,6 +2367,55 @@ ends.
 See section 3.1.8.2.1 for an example of using a `UserTransaction` within a
 task.
 
+=== Beans for Managed Objects
+
+The resource definition annotations, `ContextServiceDefinition`, `ManagedExecutorDefinition`, `ManagedScheduledExecutorDefinition`, and `ManagedThreadFactoryDefinition`, provide a `qualifiers` attribute that the application can optionally configure to specify a list of qualifier annotation classes. Similarly, the corresponding deployment descriptor elements, `<context-service>`, `<managed-executor>`, `<managed-scheduled-executor>`, and `<managed-thread-factory>`, allow `<qualifier>` sub-elements that the application can optionally configure to specify one or more qualifier annotation class names.
+
+When the a non-empty list of qualifier classes is configured for a resource definition, the container creates an instance of the corresponding managed object and registers an `jakarta.enterprise.context.ApplicationScoped` bean for it with the configured qualifiers.
+
+The container also creates a default instance of each managed object type for which the application does not already produce a bean without qualifiers, registering a `jakarta.enterprise.context.ApplicationScoped` bean without qualifiers for the default instance.
+
+The life cycle of these beans aligns with the life cycle of the application component. The configured qualifier annotation classes must be accessible to the application and must not have any attributes without default values. The application must not configure `java:global` names on resource definitions that have a non-empty list of qualifier classes. The container raises an error and does not register the bean if these requirements are not met.
+
+==== Qualifiers Example
+
+In this example, the application configures a single qualifier annotation when defining a `ManagedExecutorService`. The application injects the `ManagedExecutorService` bean by specifying the qualifier annotation on the injection point.
+
+===== Example Qualifier Annotation Class
+
+[source,java]
+----
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import jakarta.inject.Qualifier;
+
+@Qualifier
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE })
+public @interface MaxAsync5 {
+}
+----
+
+===== Example usage of Qualifier Annotation
+
+[source,java]
+----
+@ManagedExecutorDefinition(
+        name = "java:comp/concurrent/MyExecutor",
+        qualifiers = Max5Async.class,
+        maxAsync = 5)
+public class MyServlet extends HttpServlet {
+   @Inject
+   @Max5Async
+   ManagedExecutorService executor;
+
+   ...
+}
+----
+
 == Thread Context Providers
 
 The `ThreadContextProvider` SPI standardizes the interaction between