@DocumentedSE
@InheritedSE
@InterceptorBinding
@RetentionSE(RUNTIMESE)
@TargetSE({METHODSE,TYPESE})
public @interface Asynchronous

非同期で実行する CDI 管理の Bean メソッドにアノテーションを付けます。CDI 管理の Bean は Jakarta Enterprise Bean であってはならず、メソッドもそのクラスも MicroProfile 非同期アノテーションでアノテーションを付けることはできません。

Jakarta EE Product Provider は ManagedExecutorService でメソッドを実行し、メソッドの実行を表すために同じ ManagedExecutorService によってサポートされる CompletableFutureSE を呼び出し元に返します。ManagedExecutorService は、ManagedExecutorService JavaDoc API で定義されているように、CompletableFuture およびそれらから作成されたすべての依存ステージなどのデフォルトの非同期実行機能です。Jakarta EE Product Provider は、Asynchronous.Result.getFuture および Asynchronous.Result.complete メソッドを介して非同期メソッドの実装でこの CompletableFuture を使用できるようにします。

以下に例を示します。

 @Asynchronous
 public CompletableFuture<Double> hoursWorked(LocalDate from, LocalDate to) {
     // Application component's context is made available to the async method,
     try (Connection con = ((DataSource) InitialContext.doLookup(
         "java:comp/env/jdbc/timesheetDB")).getConnection()) {
         ...
         return Asynchronous.Result.complete(total);
     } catch (NamingException | SQLException x) {
         throw new CompletionException(x);
     }
 }
 

使い方

 hoursWorked(mon, fri).thenAccept(total -> {
     // Application component's context is made available to dependent stage actions,
     DataSource ds = InitialContext.doLookup(
         "java:comp/env/jdbc/payrollDB");
     ...
 });
 

非同期メソッドの実装が別の CompletableFuture インスタンスを返す場合、Jakarta EE Product Provider はそのインスタンスの完了を使用して、Jakarta EE Product Provider が呼び出し元に返す CompletableFuture を完了し、同じ結果または例外で完了します。

以下に例を示します。

 @Asynchronous
 public CompletableFuture<List<Itinerary>> findSingleLayoverFlights(Location source, Location dest) {
     try {
         ManagedExecutorService executor = InitialContext.doLookup(
             "java:comp/DefaultManagedExecutorService");

         return executor.supplyAsync(source::flightsFrom)
                        .thenCombine(executor.completedFuture(dest.flightsTo()),
                                     Itinerary::sourceMatchingDest);
     } catch (NamingException x) {
         throw new CompletionException(x);
     }
 }
 

使い方

 findSingleLayoverFlights(RST, DEN).thenApply(Itinerary::sortByPrice);
 

次の戻り値の型を持つメソッドは、非同期メソッドとしてアノテーションを付けることができます。

• CompletableFutureSE
• CompletionStageSE
• void

他の戻り値の型が使用されている場合、またはアノテーションがクラスレベルで配置されている場合、Jakarta EE Product Provider は UnsupportedOperationExceptionSE を発生させます。ElementType.TYPE のインジェクションターゲットは、非同期メソッドインターセプターを登録するために Jakarta EE Product Provider によって実装される CDI 拡張によってのみ使用されます。アプリケーションは、メソッドレベルでのみ非同期メソッドアノテーションを使用する必要があります。

メソッドは呼び出し元に対して非同期で実行されるため、非同期メソッドによって発生する例外は呼び出し元に対して直接発生しません。代わりに、結果を表す CompletableFuture は、発生した例外で完了します。チェック例外は呼び出し元に到達不能な例外処理コードの作成を強制するため、非同期メソッドはチェック例外を発生させないことをお勧めします。チェック例外が発生した場合、非同期メソッド実装は、元の例外を原因として CompletionExceptionSE を発生させることによって例外を結果の CompletableFuture に戻すことができます。または、completeExceptionallySE を使用して例外を提供して CompletableFuture を例外的に完了する同等のアプローチを取ることもできます。元の例外を原因。

特に明記されていない限り、Jakarta EE Product Provider は、非同期メソッドの呼び出し時に RejectedExecutionExceptionSE を発生させます (たとえば、JNDI 名が無効であるか、管理対象エグゼキュータリソース以外のものを指している場合など)。後で非同期メソッドを実行できないと判断された場合 (たとえば、スレッドコンテキストを確立できない場合)、Jakarta EE Product Provider は CancellationExceptionSE を使用して CompletableFuture を例外的に完了し、チェーンは原因例外 (存在する場合) を発生させます。

Jakarta EE Product Provider は、非同期メソッドのインターセプターに Interceptor.Priority.PLATFORM_BEFORE + 5 の優先順位を割り当てる必要があります。Transactional などの優先度の低いインターセプターは、サブミットスレッドではなく、非同期メソッドが実行されるスレッドで実行する必要があります。非同期メソッドに Transactional というアノテーションが付けられている場合、使用できるトランザクション型は、メソッドを新しいトランザクションで実行させる TxType.REQUIRES_NEW と、メソッドをトランザクションなしで実行させる TxType.NOT_SUPPORTED です。他のすべてのトランザクション属性は、非同期メソッドの呼び出し時に UnsupportedOperationExceptionSE になる必要があります。