インターフェース ManagedExecutorService

ExecutorServiceSE の管理可能なバージョン。

ManagedExecutorService は Java™ を継承します。SE ExecutorService は、Jakarta™ EE 環境で実行するタスクを送信するメソッドを提供します。ManagedExecutorService の実装は、Jakarta EE Product Provider によって提供されます。アプリケーションコンポーネントプロバイダーは、Java ネーミングおよびディレクトリインターフェースを使用します。™ （JNDI）リソース環境参照を使用して、1 つ以上の ManagedExecutorService オブジェクトのインスタンスを検索します。ManagedExecutorService インスタンスは、Resource アノテーションを使用してアプリケーションコンポーネントに挿入することもできます。

Jakarta Concurrency 仕様には、ManagedExecutorService が実装できるいくつかの動作が記述されています。アプリケーションコンポーネントプロバイダーとデプロイヤーは、これらの要件を特定し、リソース環境参照を適切にマッピングします。

ManagedExecutorService の最も一般的な用途は、Jakarta Enterprise Beans での非同期メソッドの処理や、非同期処理をサポートするサーブレットの非同期タスクの処理など、短時間の非同期タスクを実行することです。

タスクは、Jakarta EE Product Provider によって提供される管理対象スレッドで実行され、タスクを送信したアプリケーションコンポーネントコンテキスト内で実行されます。すべてのタスクは、明示的なトランザクションなしで実行されます（アプリケーションコンポーネントのトランザクションには参加しません）。トランザクションが必要な場合は、jakarta.transaction.UserTransaction インスタンスを使用してください。UserTransaction インスタンスは、" java:comp/UserTransaction" という名前を使用して JNDI で使用できます。または、Resource アノテーションを使用して jakarta.transaction.UserTransaction オブジェクトのインジェクションをリクエストします。

例:

 public run() {
   // Begin of task
   InitialContext ctx = new InitialContext();
   UserTransaction ut = (UserTransaction) ctx.lookup("java:comp/UserTransaction");
   ut.begin();

   // Perform transactional business logic

   ut.commit();
 }
 

タスクは、オプションで、ManagedTask インターフェースを使用してライフサイクルイベントの通知を受信するための ManagedTaskListener を提供できます。

例:

 public class MyRunnable implements Runnable, ManagedTask {
   ...
   public void run() {
     ...
   }

   public ManagedTaskListener getManagedTaskListener() {
     return myManagedTaskListener;
   }
   ...
 }

 MyRunnable task = ...;
 ManagedExecutorService executor = ...;

 executor.submit(task); // lifecycle events will be notified to myManagedTaskListener
 

非同期タスクは通常、submit メソッドの 1 つを使用して ManagedExecutorService に送信され、それぞれのメソッドが FutureSE インスタンスを返します。Future はタスクの結果を表し、タスクが完了したかどうかを確認したり、タスクの完了を待機したりするためにも使用できます。

タスクが取り消されると、タスクの結果は CancellationExceptionSE 例外になります。キャンセル以外の理由でタスクを実行できない場合、結果は AbortedException 例外になります。

例:

 /**
  * Retrieve all accounts from several account databases in parallel.
  * Resource Mappings:
  *  type:      jakarta.enterprise.concurrent.ManagedExecutorService
  *  jndi-name: concurrent/ThreadPool
  */
 public List<Account> getAccounts(long accountId) {
   try {
       javax.naming.InitialContext ctx = new InitialContext();
       ManagedExecutorService mes = (ManagedExecutorService)
           ctx.lookup("java:comp/env/concurrent/ThreadPool");

       // Create a set of tasks to perform the account retrieval.
       ArrayList<Callable<Account>> retrieverTasks = new ArrayList<Callable<Account>>();
       retrieverTasks.add(new EISAccountRetriever());
       retrieverTasks.add(new RDBAccountRetriever());

       // Submit the tasks to the thread pool and wait for them
       // to complete (successfully or otherwise).
       List<Future<Account>> taskResults= mes.invokeAll(retrieverTasks);

       // Retrieve the results from the resulting Future list.
       ArrayList<Account> results = new ArrayList<Account>();
       for(Future<Account> taskResult : taskResults) {
           try {
               results.add(taskResult.get());
           } catch (ExecutionException e) {
               Throwable cause = e.getCause();
               // Handle the AccountRetrieverError.
           }
       }

       return results;

   } catch (NamingException e) {
       // Throw exception for fatal error.
   } catch (InterruptedException e) {
       // Throw exception for shutdown or other interrupt condition.
   }
 }


 public class EISAccountRetriever implements Callable<Account> {
     public Account call() {
         // Connect to our eis system and retrieve the info for the account.
         //...
         return null;
   }
 }

 public class RDBAccountRetriever implements Callable<Account> {
     public Account call() {
         // Connect to our database and retrieve the info for the account.
         //...
   }
 }

 public class Account {
     // Some account data...
 }
 

ManagedExecutorService は、CompletableFutureSE およびそのコンストラクター /newIncompleteFuture メソッドの静的メソッドに対応するさまざまなメソッドを提供し、デフォルトの非同期実行機能として ManagedExecutorService によってサポートされる完了ステージを作成できるようにします。それらから作成されます。これにより、各依存アクションが最終的にどのスレッドで実行されるかに関係なく、一貫した予測可能なスレッドコンテキストで実行される完了ステージアクションのパイプラインを作成できます。

例:

 ManagedExectorService executor = InitialContext.doLookup("java:comp/DefaultManagedExecutorService");
 ...
 CompletableFuture<Integer> future = executor
    .supplyAsync(supplier)
    .thenApply(function1)
    .thenApplyAsync(function2)
    ...
 
 

ManagedExecutorService によってサポートされる完了ステージへのコンテキスト伝搬は、次のように定義されている一貫性のある予測可能な方法で行う必要があります。

• 指定されたアクションがすでにコンテキストに依存している場合 (たとえば、contextService.createContextualProxy(action, Runnable.class))、アクションはすでにキャプチャーされたコンテキストで実行されます。
• それ以外の場合、新規ステージおよびその親ステージのデフォルトの非同期実行機能である ManagedExecutorService の構成に従って、各型のスレッドコンテキストが完了ステージを作成するスレッドから伝搬されるか、コンテキストがクリアされるようにマークされます。ManagedExecutorService が executor 引数として *Async メソッドに提供される場合、提供された ManagedExecutorService はアクションを実行するために使用されますが、スレッドコンテキストの伝播とクリアを決定するためには使用されません。

各型のスレッドコンテキストは、アクションを実行するスレッドに適用されます (クリアされるか、以前にキャプチャーされたものとして)。適用されたスレッドコンテキストは、アクションが正常に完了したか例外的に完了したかを問わず、削除され、スレッドの以前のコンテキストが復元されます。

依存ステージが完了ステージから作成された場合、およびそれらから作成された依存ステージなどから同様に、スレッドコンテキストが同じ方法でキャプチャーまたはクリアされます。これにより、各ステージで実行されるアクションは、ユーザーが事前にコンテキスト化されたアクションを指定して明示的にオーバーライドしない限り、完了ステージを作成するコードのスレッドコンテキストで常に実行されることが保証されます。

ManagedTask を実装するアクションが指定されている場合、ManagedExecutorService によってサポートされる完了ステージは IllegalArgumentExceptionSE を発生させる必要があります。