javax.util.concurrent
Interface ManagedScheduledExecutorService

All Superinterfaces:

java.util.concurrent.Executor, java.util.concurrent.ExecutorService, ManagedExecutorService, java.util.concurrent.ScheduledExecutorService

public interface ManagedScheduledExecutorService
extends java.util.concurrent.ScheduledExecutorService, ManagedExecutorService

A manageable version of a ScheduledExecutorService.

A ManagedScheduledExecutorService provides methods for submitting delayed or periodic tasks for execution in a managed environment. Implementations of the ManagedScheduledExecutorService 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 ManagedScheduledExecutorService can implement. The Application Component Provider and Deployer identify these requirements and map the resource environment reference appropriately.

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 ManagedScheduledExecutorService using one of the submit or schedulemethods, 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. If the task is scheduled with a Trigger and the Trigger forces the task to be skipped, the result will be a SkippedException exception.

Tasks can be scheduled to run periodically using the schedule methods that take a Trigger as an argument and the scheduleAtFixedRate and scheduleWithFixedDelay methods. The result of the Future will be represented by the currently scheduled or running instance of the task. Future and past executions of the task are not represented by the Future. The state of the Future will therefore change and multiple results are expected.

For example, if a task is repeat, the lifecycle of the task would be:
(Note: See ManagedTaskListener for task lifecycle management details.)

Sequence	State	Action	Listener	Next state
1A.	None	submit()	taskSubmitted	Submitted
2A.	Submitted	About to call run()	taskStarting	Started
3A.	Started	Exit run()	taskDone	Reschedule
1B.	Reschedule		taskSubmitted	Submitted
2B.	Submitted	About to call run()	taskStarting	Started
3B.	Started	Exit run()	taskDone	Reschedule

Author:

Chris D. Johnson

Method Summary

<V> java.util.concurrent.ScheduledFuture<V>	schedule(java.util.concurrent.Callable<V> callable, long delay, java.util.concurrent.TimeUnit unit, ManagedTaskListener taskListener) Creates and executes a ScheduledFuture that becomes enabled after the given delay.
<V> java.util.concurrent.ScheduledFuture<V>	schedule(java.util.concurrent.Callable<V> callable, Trigger trigger, ManagedTaskListener taskListener) Creates and executes a task based on a Trigger.
java.util.concurrent.ScheduledFuture<?>	schedule(java.lang.Runnable command, long delay, java.util.concurrent.TimeUnit unit, ManagedTaskListener taskListener) Creates and executes a one-shot action that becomes enabled after the given delay.
java.util.concurrent.ScheduledFuture<?>	schedule(java.lang.Runnable command, Trigger trigger, ManagedTaskListener taskListener) Creates and executes a task based on a Trigger.
java.util.concurrent.ScheduledFuture<?>	scheduleAtFixedRate(java.lang.Runnable command, long initialDelay, long period, java.util.concurrent.TimeUnit unit, ManagedTaskListener taskListener) Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period; that is executions will commence after initialDelay then initialDelay+period, then initialDelay + 2 * period, and so on.
java.util.concurrent.ScheduledFuture<?>	scheduleWithFixedDelay(java.lang.Runnable command, long initialDelay, long delay, java.util.concurrent.TimeUnit unit, ManagedTaskListener taskListener) Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given delay between the termination of one execution and the commencement of the next.

Methods inherited from interface java.util.concurrent.ScheduledExecutorService

schedule, schedule, scheduleAtFixedRate, scheduleWithFixedDelay

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

Methods inherited from interface javax.util.concurrent.ManagedExecutorService

invokeAll, invokeAll, invokeAny, invokeAny, submit, submit, submit

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

schedule

java.util.concurrent.ScheduledFuture<?> schedule(java.lang.Runnable command,
                                                 Trigger trigger,
                                                 ManagedTaskListener taskListener)

Creates and executes a task based on a Trigger. The Trigger determines when the task should run and how often.

Parameters:

command - the task to execute.

trigger - the trigger that determines when the task should fire.

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 command is null

schedule

<V> java.util.concurrent.ScheduledFuture<V> schedule(java.util.concurrent.Callable<V> callable,
                                                     Trigger trigger,
                                                     ManagedTaskListener taskListener)

Creates and executes a task based on a Trigger. The Trigger determines when the task should run and how often.

Parameters:

callable - the function to execute.

trigger - the trigger that determines when the task should fire.

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

Returns:

a ScheduledFuture that can be used to extract result or cancel.

Throws:

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

java.lang.NullPointerException - if callable is null

schedule

java.util.concurrent.ScheduledFuture<?> schedule(java.lang.Runnable command,
                                                 long delay,
                                                 java.util.concurrent.TimeUnit unit,
                                                 ManagedTaskListener taskListener)

Creates and executes a one-shot action that becomes enabled after the given delay.

Parameters:

command - the task to execute.

delay - the time from now to delay execution.

unit - the time unit of the delay parameter.

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 command is null

schedule

<V> java.util.concurrent.ScheduledFuture<V> schedule(java.util.concurrent.Callable<V> callable,
                                                     long delay,
                                                     java.util.concurrent.TimeUnit unit,
                                                     ManagedTaskListener taskListener)

Creates and executes a ScheduledFuture that becomes enabled after the given delay.

Parameters:

callable - the function to execute.

delay - the time from now to delay execution.

unit - the time unit of the delay parameter.

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

Returns:

a ScheduledFuture that can be used to extract result or cancel.

Throws:

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

java.lang.NullPointerException - if callable is null

scheduleAtFixedRate

java.util.concurrent.ScheduledFuture<?> scheduleAtFixedRate(java.lang.Runnable command,
                                                            long initialDelay,
                                                            long period,
                                                            java.util.concurrent.TimeUnit unit,
                                                            ManagedTaskListener taskListener)

Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period; that is executions will commence after initialDelay then initialDelay+period, then initialDelay + 2 * period, and so on. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.

Parameters:

command - the task to execute.

initialDelay - the time to delay first execution.

period - the period between successive executions.

unit - the time unit of the initialDelay and period parameters

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 throw an exception upon cancellation.

Throws:

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

java.lang.NullPointerException - if command is null

java.lang.IllegalArgumentException - if period less than or equal to zero.

scheduleWithFixedDelay

java.util.concurrent.ScheduledFuture<?> scheduleWithFixedDelay(java.lang.Runnable command,
                                                               long initialDelay,
                                                               long delay,
                                                               java.util.concurrent.TimeUnit unit,
                                                               ManagedTaskListener taskListener)

Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given delay between the termination of one execution and the commencement of the next. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.

Parameters:

command - the task to execute.

initialDelay - the time to delay first execution.

delay - the delay between the termination of one execution and the commencement of the next.

unit - the time unit of the initialDelay and delay parameters

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 throw an exception upon cancellation.

Throws:

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

java.lang.NullPointerException - if command is null

java.lang.IllegalArgumentException - if delay less than or equal to zero.