API updates to support Java SE 17

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

@@ -203,10 +203,17 @@
      */
     int maxAsync() default -1;
 
+    // TODO switch the link below back to
+    //      {@link Thread#isVirtual() virtual} threads
+    //      instead of
+    //      virtual {@link Thread threads}
+    //      once this project compiles against Java SE 21 again.
     /**
      * <p>Indicates whether this executor is requested to
-     * create {@link Thread#isVirtual() virtual} threads
-     * for tasks that do not run inline.</p>
+     * create virtual {@link Thread threads}
+     * for tasks that do not run inline.
+     * Virtual threads are discussed in the {@link Thread} JavaDoc
+     * under the section that is titled <i><b>Virtual threads</b></i>.</p>
      *
      * <p>When {@code true}, the executor can create
      * virtual threads if it is capable of doing so
@@ -223,6 +230,11 @@
      * In situations such as these, the executor does not control
      * the type of thread that is used to run the task.</p>
      *
+     * <p>When running on Java SE 17, the {@code true} value
+     * behaves the same as the {@code false} value and results in
+     * platform threads being created rather than virtual threads.
+     * </p>
+     *
      * @return {@code true} if the executor can create virtual threads,
      *         otherwise {@code false}.
      * @since 3.1

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

@@ -204,10 +204,17 @@
      */
     int maxAsync() default -1;
 
+    // TODO switch the link below back to
+    //      {@link Thread#isVirtual() virtual} threads
+    //      instead of
+    //      virtual {@link Thread threads}
+    //      once this project compiles against Java SE 21 again.
     /**
      * <p>Indicates whether this executor is requested to
-     * create {@link Thread#isVirtual() virtual} threads
-     * for tasks that do not run inline.</p>
+     * create virtual {@link Thread threads}
+     * for tasks that do not run inline.
+     * Virtual threads are discussed in the {@link Thread} JavaDoc
+     * under the section that is titled <i><b>Virtual threads</b></i>.</p>
      *
      * <p>When {@code true}, the executor can create
      * virtual threads if it is capable of doing so
@@ -224,6 +231,11 @@
      * In situations such as these, the executor does not control
      * the type of thread that is used to run the task.</p>
      *
+     * <p>When running on Java SE 17, the {@code true} value
+     * behaves the same as the {@code false} value and results in
+     * platform threads being created rather than virtual threads.
+     * </p>
+     *
      * @return {@code true} if the executor can create virtual threads,
      *         otherwise {@code false}.
      * @since 3.1

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

@@ -182,9 +182,16 @@
      */
     int priority() default Thread.NORM_PRIORITY;
 
+    // TODO switch the link below back to
+    //      {@link Thread#isVirtual() virtual} threads
+    //      instead of
+    //      virtual {@link Thread threads}
+    //      once this project compiles against Java SE 21 again.
     /**
      * <p>Indicates whether this thread factory is requested to
-     * create {@link Thread#isVirtual() virtual} threads.</p>
+     * create virtual {@link Thread threads}.
+     * Virtual threads are discussed in the {@link Thread} JavaDoc
+     * under the section that is titled <i><b>Virtual threads</b></i>.</p>
      *
      * <p>When {@code true}, the thread factory can create
      * virtual threads if it is capable of doing so
@@ -196,6 +203,11 @@
      * When {@code false}, the thread factory always creates
      * platform threads.</p>
      *
+     * <p>When running on Java SE 17, the {@code true} value
+     * behaves the same as the {@code false} value and results in
+     * platform threads being created rather than virtual threads.
+     * </p>
+     *
      * @return {@code true} if the thread factory is requested to
      *         create virtual threads, otherwise {@code false}.
      * @since 3.1