1 /**
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package javax.util.concurrent;
18
19 import java.util.concurrent.Callable;
20 import java.util.concurrent.RejectedExecutionException;
21 import java.util.concurrent.ScheduledExecutorService;
22 import java.util.concurrent.ScheduledFuture;
23 import java.util.concurrent.TimeUnit;
24
25
26
27 /**
28 * A manageable version of a {@link java.util.concurrent.ScheduledExecutorService}.<p>
29 *
30 * A ManagedScheduledExecutorService provides methods for submitting delayed or
31 * periodic tasks for execution in a managed environment.
32 * Implementations of the ManagedScheduledExecutorService are
33 * provided by a Java™ EE Product Provider. Application Component Providers
34 * use the Java Naming and Directory Interface™ (JNDI) to look-up instances of one
35 * or more ManagedExecutorService objects using resource environment references.<p>
36 *
37 * The Concurrency Utilities for Java™ EE specification describes several
38 * behaviors that a ManagedScheduledExecutorService can implement. The Application
39 * Component Provider and Deployer identify these requirements and map the
40 * resource environment reference appropriately.<p>
41 *
42 * Tasks run within the application component context that either
43 * submitted the task or created the ManagedExecutorService instance (server-managed or component-managed).
44 * All tasks run without an explicit transaction (they do not enlist in the application
45 * component's transaction). If a transaction is required, use a
46 * {@link javax.transaction.UserTransaction} instance. A UserTransaction instance is
47 * available in JNDI using the name: "java:comp/UserTransaction"<p>
48 *
49 * Example:<pre>
50 * public run() {
51 * // Begin of task
52 * InitialContext ctx = new InitialContext();
53 * UserTransaction ut = (UserTransaction) ctx.lookup("java:comp/UserTransaction");
54 * ut.begin();
55 *
56 * // Perform transactional business logic
57 *
58 * ut.commit();
59 * }</PRE>
60 *
61 * Asynchronous tasks are typically submitted to the ManagedScheduledExecutorService using one
62 * of the <code>submit</code> or <code>schedule</code>methods, each of which return a {@link java.util.concurrent.Future}
63 * instance. The Future represents the result of the task and can also be used to
64 * check if the task is complete or wait for its completion.<p>
65 *
66 * If the task is cancelled, the result fo the task is a
67 * {@link java.util.concurrent.CancellationException} exception. If the task is unable
68 * to run due to start due to a reason other than cancellation, the result is a
69 * {@link javax.util.concurrent.AbortedException} exception. If the task is scheduled
70 * with a {@link javax.util.concurrent.Trigger} and the Trigger forces the task to be skipped,
71 * the result will be a {@link javax.util.concurrent.SkippedException} exception.<p>
72 *
73 * Tasks can be scheduled to run periodically using the <code>schedule</code> methods that
74 * take a <code>Trigger</code> as an argument and the <code>scheduleAtFixedRate</code> and
75 * <code>scheduleWithFixedDelay</code> methods. The result of the <code>Future</code> will
76 * be represented by the currently scheduled or running instance of the task. Future and past executions
77 * of the task are not represented by the Future. The state of the <code>Future</code> will therefore change
78 * and multiple results are expected.<p>
79 *
80 * For example, if a task is repeat, the lifecycle of the task would be:<br>
81 * (Note: See {@link javax.util.concurrent.ManagedTaskListener} for task lifecycle management details.)<p>
82 *
83 * <table>
84 * <tr><td valign="top"><strong>Sequence</strong></td><td valign="top"><strong>State</strong></td><td valign="top"><strong>Action</strong></td><td valign="top"><strong>Listener</strong></td><td valign="top"><strong>Next state</strong></td></tr>
85 * <tr><td valign="top">1A.</td><td valign="top">None</td><td valign="top">submit()</td><td valign="top">taskSubmitted</td><td valign="top">Submitted</td></tr>
86 * <tr><td valign="top">2A.</td><td valign="top">Submitted</td><td valign="top">About to call run()</td><td valign="top">taskStarting</td><td valign="top">Started</td></tr>
87 * <tr><td valign="top">3A.</td><td valign="top">Started</td><td valign="top">Exit run()</td><td valign="top">taskDone</td><td valign="top">Reschedule</td></tr>
88 * <tr><td valign="top">1B.</td><td valign="top">Reschedule</td><td valign="top"></td><td valign="top">taskSubmitted</td><td valign="top">Submitted</td></tr>
89 * <tr><td valign="top">2B.</td><td valign="top">Submitted</td><td valign="top">About to call run()</td><td valign="top">taskStarting</td><td valign="top">Started</td></tr>
90 * <tr><td valign="top">3B.</td><td valign="top">Started</td><td valign="top">Exit run()</td><td valign="top">taskDone</td><td valign="top">Reschedule</td></tr>
91 * </table>
92 *
93 *
94 *
95 */
96 public interface ManagedScheduledExecutorService extends ScheduledExecutorService, ManagedExecutorService
97 {
98 /**
99 * Creates and executes a task based on a Trigger. The Trigger determines
100 * when the task should run and how often.
101 *
102 * @param command the task to execute.
103 * @param trigger the trigger that determines when the task should fire.
104 * @param taskListener the ManagedTaskListener instance to receive a task's lifecycle events.
105 * @return a Future representing pending completion of the task,
106 * and whose <tt>get()</tt> method will return <tt>null</tt>
107 * upon completion.
108 * @throws RejectedExecutionException if task cannot be scheduled
109 * for execution.
110 * @throws NullPointerException if command is null
111 */
112 public ScheduledFuture<?> schedule(Runnable command, Trigger trigger, ManagedTaskListener taskListener);
113
114 /**
115 * Creates and executes a task based on a Trigger. The Trigger determines
116 * when the task should run and how often.
117 *
118 * @param callable the function to execute.
119 * @param trigger the trigger that determines when the task should fire.
120 * @param taskListener the ManagedTaskListener instance to receive a task's lifecycle events.
121 * @return a ScheduledFuture that can be used to extract result or cancel.
122 * @throws RejectedExecutionException if task cannot be scheduled
123 * for execution.
124 * @throws NullPointerException if callable is null
125 */
126 public <V> ScheduledFuture<V> schedule(Callable<V> callable, Trigger trigger, ManagedTaskListener taskListener);
127
128 /**
129 * Creates and executes a one-shot action that becomes enabled
130 * after the given delay.
131 * @param command the task to execute.
132 * @param delay the time from now to delay execution.
133 * @param unit the time unit of the delay parameter.
134 * @param taskListener the ManagedTaskListener instance to receive a task's lifecycle events.
135 * @return a Future representing pending completion of the task,
136 * and whose <tt>get()</tt> method will return <tt>null</tt>
137 * upon completion.
138 * @throws RejectedExecutionException if task cannot be scheduled
139 * for execution.
140 * @throws NullPointerException if command is null
141 */
142 public ScheduledFuture<?> schedule(Runnable command, long delay, TimeUnit unit, ManagedTaskListener taskListener);
143
144 /**
145 * Creates and executes a ScheduledFuture that becomes enabled after the
146 * given delay.
147 * @param callable the function to execute.
148 * @param delay the time from now to delay execution.
149 * @param unit the time unit of the delay parameter.
150 * @param taskListener the ManagedTaskListener instance to receive a task's lifecycle events.
151 * @return a ScheduledFuture that can be used to extract result or cancel.
152 * @throws RejectedExecutionException if task cannot be scheduled
153 * for execution.
154 * @throws NullPointerException if callable is null
155 */
156 public <V> ScheduledFuture<V> schedule(Callable<V> callable, long delay, TimeUnit unit, ManagedTaskListener taskListener);
157
158 /**
159 * Creates and executes a periodic action that becomes enabled first
160 * after the given initial delay, and subsequently with the given
161 * period; that is executions will commence after
162 * <tt>initialDelay</tt> then <tt>initialDelay+period</tt>, then
163 * <tt>initialDelay + 2 * period</tt>, and so on.
164 * If any execution of the task
165 * encounters an exception, subsequent executions are suppressed.
166 * Otherwise, the task will only terminate via cancellation or
167 * termination of the executor.
168 * @param command the task to execute.
169 * @param initialDelay the time to delay first execution.
170 * @param period the period between successive executions.
171 * @param unit the time unit of the initialDelay and period parameters
172 * @param taskListener the ManagedTaskListener instance to receive a task's lifecycle events.
173 * @return a Future representing pending completion of the task,
174 * and whose <tt>get()</tt> method will throw an exception upon
175 * cancellation.
176 * @throws RejectedExecutionException if task cannot be scheduled
177 * for execution.
178 * @throws NullPointerException if command is null
179 * @throws IllegalArgumentException if period less than or equal to zero.
180 */
181 public ScheduledFuture<?> scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit, ManagedTaskListener taskListener);
182
183 /**
184 * Creates and executes a periodic action that becomes enabled first
185 * after the given initial delay, and subsequently with the
186 * given delay between the termination of one execution and the
187 * commencement of the next. If any execution of the task
188 * encounters an exception, subsequent executions are suppressed.
189 * Otherwise, the task will only terminate via cancellation or
190 * termination of the executor.
191 * @param command the task to execute.
192 * @param initialDelay the time to delay first execution.
193 * @param delay the delay between the termination of one
194 * execution and the commencement of the next.
195 * @param unit the time unit of the initialDelay and delay parameters
196 * @param taskListener the ManagedTaskListener instance to receive a task's lifecycle events.
197 * @return a Future representing pending completion of the task,
198 * and whose <tt>get()</tt> method will throw an exception upon
199 * cancellation.
200 * @throws RejectedExecutionException if task cannot be scheduled
201 * for execution.
202 * @throws NullPointerException if command is null
203 * @throws IllegalArgumentException if delay less than or equal to zero.
204 */
205 public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit, ManagedTaskListener taskListener);
206 }