javax.util.concurrent
Interface ManagedExecutorService

All Superinterfaces:

java.util.concurrent.Executor, java.util.concurrent.ExecutorService

All Known Subinterfaces:

ManagedScheduledExecutorService

public interface ManagedExecutorService
extends java.util.concurrent.ExecutorService

A manageable version of a ExecutorService.

A ManagedExecutorService provides methods for submitting tasks for execution in a managed 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.

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 in the local JVM from a container such as an Enterprise JavaBean™ (EJB™) or servlet. Use a managed ThreadFactory for long-running daemon tasks.

Tasks run within the application component context that either submitted the task or created the ManagedExecutorService instance (server-managed or component-managed). All tasks run without an explicit transaction (they do not enlist in the application component's transaction). If a transaction is required, use a javax.transaction.UserTransaction instance. A UserTransaction instance is available in JNDI using the name: "java:comp/UserTransaction"

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

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 cancelled, the result fo the task is a CancellationException exception. If the task is unable to run due to start 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.util.concurrent.ManagedExecutorService
  *  jndi-name: mes/ThreadPool
  *  attributes:
  *    Run Location = Local
  */
 public List 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> retrieverTasks = new ArrayList>();
         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> taskResults= mes.invokeAll(retrieverTasks);

         // Retrieve the results from the resulting Future list.
         ArrayList results = new ArrayList();
         for(Future 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 {
     public Account call() {
         // Connect to our eis system and retrieve the info for the account.
         //...
         return null;
     }
 }

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

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

Author:

Chris D Johnson

Method Summary

<T> java.util.List<java.util.concurrent.Future<T>>	invokeAll(java.util.Collection<? extends java.util.concurrent.Callable<T>> tasks, long timeout, java.util.concurrent.TimeUnit unit, ManagedTaskListener taskListener) This method has the same semantics as ExecutorService.invokeAll(java.util.Collection, long, java.util.concurrent.TimeUnit) but also includes the ability to be notified when each task's lifecycle changes.
<T> java.util.List<java.util.concurrent.Future<T>>	invokeAll(java.util.Collection<? extends java.util.concurrent.Callable<T>> tasks, ManagedTaskListener taskListener) This method has the same semantics as ExecutorService.invokeAll(java.util.Collection) but also includes the ability to be notified when each task's lifecycle changes.
<T> T	invokeAny(java.util.Collection<? extends java.util.concurrent.Callable<T>> tasks, ManagedTaskListener taskListener) This method has the same semantics as ExecutorService.invokeAny(java.util.Collection) but also includes the ability to be notified when each task's lifecycle changes.
<T> T	invokeAny(java.util.Collection<java.util.concurrent.Callable<T>> tasks, long timeout, java.util.concurrent.TimeUnit unit) This method has the same semantics as ExecutorService.invokeAny(java.util.Collection, long, java.util.concurrent.TimeUnit) but also includes the ability to be notified when each task's lifecycle changes.
<T> java.util.concurrent.Future<T>	submit(java.util.concurrent.Callable<T> task, ManagedTaskListener taskListener) This method has the same semantics as ExecutorService.submit(java.util.concurrent.Callable) but also includes the ability to be notified when the task's lifecycle changes.
java.util.concurrent.Future<?>	submit(java.lang.Runnable task, ManagedTaskListener taskListener) This method has the same semantics as ExecutorService.submit(java.lang.Runnable) but also includes the ability to be notified when the task's lifecycle changes.
<T> java.util.concurrent.Future<T>	submit(java.lang.Runnable task, T result, ManagedTaskListener taskListener) This method has the same semantics as ExecutorService#submit(java.lang.Runnable, T) but also includes the ability to be notified when the task's lifecycle changes.

Methods inherited from interface java.util.concurrent.ExecutorService

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

Methods inherited from interface java.util.concurrent.Executor

execute

Method Detail

submit

java.util.concurrent.Future<?> submit(java.lang.Runnable task,
                                      ManagedTaskListener taskListener)

This method has the same semantics as ExecutorService.submit(java.lang.Runnable) but also includes the ability to be notified when the task's lifecycle changes.

Parameters:

task - the task to submit

taskListener - the ManagedTaskListener instance to receive a task's lifecycle events.

Returns:

a Future representing pending completion of the task, and whose get() method will return null upon completion.

Throws:

java.util.concurrent.RejectedExecutionException - if task cannot be scheduled for execution

java.lang.NullPointerException - if task null

submit

<T> java.util.concurrent.Future<T> submit(java.lang.Runnable task,
                                          T result,
                                          ManagedTaskListener taskListener)

This method has the same semantics as ExecutorService#submit(java.lang.Runnable, T) but also includes the ability to be notified when the task's lifecycle changes.

Parameters:

task - the task to submit

taskListener - the ManagedTaskListener instance to receive a task's lifecycle events.

result - the result to return

Returns:

a Future representing pending completion of the task, and whose get() method will return the given result upon completion.

Throws:

java.util.concurrent.RejectedExecutionException - if task cannot be scheduled for execution

java.lang.NullPointerException - if task null

submit

<T> java.util.concurrent.Future<T> submit(java.util.concurrent.Callable<T> task,
                                          ManagedTaskListener taskListener)

This method has the same semantics as ExecutorService.submit(java.util.concurrent.Callable) but also includes the ability to be notified when the task's lifecycle changes.

Parameters:

task - the task to submit

taskListener - the ManagedTaskListener instance to receive a task's lifecycle events.

Returns:

a Future representing pending completion of the task

Throws:

java.util.concurrent.RejectedExecutionException - if task cannot be scheduled for execution

java.lang.NullPointerException - if task null

invokeAll

<T> java.util.List<java.util.concurrent.Future<T>> invokeAll(java.util.Collection<? extends java.util.concurrent.Callable<T>> tasks,
                                                             ManagedTaskListener taskListener)
                                                         throws java.lang.InterruptedException

This method has the same semantics as ExecutorService.invokeAll(java.util.Collection) but also includes the ability to be notified when each task's lifecycle changes.

Parameters:

tasks - the collection of tasks

taskListener - the ManagedTaskListener instance to receive a task's lifecycle events.

Returns:

A list of Futures representing the tasks, in the same sequential order as produced by the iterator for the given task list, each of which has completed.

Throws:

java.lang.InterruptedException - if interrupted while waiting, in which case unfinished tasks are cancelled.

java.lang.NullPointerException - if tasks or any of its elements are null

java.util.concurrent.RejectedExecutionException - if any task cannot be scheduled for execution

invokeAll

<T> java.util.List<java.util.concurrent.Future<T>> invokeAll(java.util.Collection<? extends java.util.concurrent.Callable<T>> tasks,
                                                             long timeout,
                                                             java.util.concurrent.TimeUnit unit,
                                                             ManagedTaskListener taskListener)
                                                         throws java.lang.InterruptedException

This method has the same semantics as ExecutorService.invokeAll(java.util.Collection, long, java.util.concurrent.TimeUnit) but also includes the ability to be notified when each task's lifecycle changes.

Parameters:

tasks - the collection of tasks

timeout - the maximum time to wait

unit - the time unit of the timeout argument

taskListener - the ManagedTaskListener instance to receive a task's lifecycle events.

Returns:

A list of Futures representing the tasks, in the same sequential order as produced by the iterator for the given task list. If the operation did not time out, each task will have completed. If it did time out, some of these tasks will not have completed.

Throws:

java.lang.InterruptedException - if interrupted while waiting, in which case unfinished tasks are cancelled.

java.lang.NullPointerException - if tasks, any of its elements, or unit are null

java.util.concurrent.RejectedExecutionException - if any task cannot be scheduled for execution

invokeAny

<T> T invokeAny(java.util.Collection<? extends java.util.concurrent.Callable<T>> tasks,
                ManagedTaskListener taskListener)
            throws java.lang.InterruptedException,
                   java.util.concurrent.ExecutionException

This method has the same semantics as ExecutorService.invokeAny(java.util.Collection) but also includes the ability to be notified when each task's lifecycle changes. Executes the given tasks, returning the result of one that has completed successfully (i.e., without throwing an exception), if any do. Upon normal or exceptional return, tasks that have not completed are cancelled. The results of this method are undefined if the given collection is modified while this operation is in progress.

Parameters:

tasks - the collection of tasks

taskListener - the ManagedTaskListener instance to receive a task's lifecycle events.

Returns:

The result returned by one of the tasks.

Throws:

java.lang.InterruptedException - if interrupted while waiting

java.lang.NullPointerException - if tasks or any of its elements are null

java.lang.IllegalArgumentException - if tasks empty

java.util.concurrent.ExecutionException - if no task successfully completes

java.util.concurrent.RejectedExecutionException - if tasks cannot be scheduled for execution

invokeAny

<T> T invokeAny(java.util.Collection<java.util.concurrent.Callable<T>> tasks,
                long timeout,
                java.util.concurrent.TimeUnit unit)
            throws java.lang.InterruptedException,
                   java.util.concurrent.ExecutionException,
                   java.util.concurrent.TimeoutException

This method has the same semantics as ExecutorService.invokeAny(java.util.Collection, long, java.util.concurrent.TimeUnit) but also includes the ability to be notified when each task's lifecycle changes.

Specified by:

invokeAny in interface java.util.concurrent.ExecutorService

Parameters:

tasks - the collection of tasks

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

The result returned by one of the tasks.

Throws:

java.lang.InterruptedException - if interrupted while waiting

java.lang.NullPointerException - if tasks, any of its elements, or unit are null

java.util.concurrent.TimeoutException - if the given timeout elapses before any task successfully completes

java.util.concurrent.ExecutionException - if no task successfully completes

java.util.concurrent.RejectedExecutionException - if tasks cannot be scheduled for execution