javax.enterprise.concurrent

## Interface ManagedExecutorService

- All Superinterfaces:
    Executor, ExecutorService
  All Known Subinterfaces:
    ManagedScheduledExecutorService

      public interface ManagedExecutorService
      extends ExecutorService

  A manageable version of a `ExecutorService`.

  A ManagedExecutorService extends the Java™ SE ExecutorService to provide methods for submitting tasks for execution in a Java™ EE environment. Implementations of the ManagedExecutorService are provided by a Java™ EE Product Provider. Application Component Providers use the Java Naming and Directory Interface™ (JNDI) to look-up instances of one or more ManagedExecutorService objects using resource environment references. ManagedExecutorService instances can also be injected into application components through the use of the `Resource` annotation.

  The Concurrency Utilities for Java™ EE specification describes several behaviors that a ManagedExecutorService can implement. The Application Component Provider and Deployer identify these requirements and map the resource environment reference appropriately.

  The most common uses for a ManagedExecutorService is to run short-duration asynchronous tasks such as for processing of asynchronous methods in Enterprise JavaBean™ (EJB™) or for processing async tasks for Servlets that supports asynchronous processing.

  Tasks are run in managed threads provided by the Java™ EE Product Provider and are run within the application component context that submitted the task. All tasks run without an explicit transaction (they do not enlist in the application component's transaction). If a transaction is required, use a `UserTransaction` instance. A UserTransaction instance is available in JNDI using the name: "java:comp/UserTransaction" or by requesting an injection of a `UserTransaction` object using the `Resource` annotation.

  Example:

       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();
       }

  Tasks can optionally provide an `ManagedTaskListener` to receive notifications of lifecycle events, through the use of `ManagedTask` interface.

  Example:

       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

  Asynchronous tasks are typically submitted to the ManagedExecutorService using one of the `submit` methods, each of which return a `Future` instance. The `Future` represents the result of the task and can also be used to check if the task is complete or wait for its completion.

  If the task is canceled, the result for the task is a `CancellationException` exception. If the task is unable to run due to a reason other than cancellation, the result is a `AbortedException` exception.

  Example:

       /**
        * Retrieve all accounts from several account databases in parallel.
        * Resource Mappings:
        *  type:      javax.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...
       }

  Since:
    1.0

- - ### Method Summary

    - ### Methods inherited from interface java.util.concurrent.ExecutorService

      `awaitTermination, invokeAll, invokeAll, invokeAny, invokeAny, isShutdown, isTerminated, shutdown, shutdownNow, submit, submit, submit`

    - ### Methods inherited from interface java.util.concurrent.Executor

      `execute`

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.