001 /**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package javax.util.concurrent;
018
019 import java.util.concurrent.Callable;
020 import java.util.concurrent.RejectedExecutionException;
021 import java.util.concurrent.ScheduledExecutorService;
022 import java.util.concurrent.ScheduledFuture;
023 import java.util.concurrent.TimeUnit;
024
025
026
027 /**
028 * A manageable version of a {@link java.util.concurrent.ScheduledExecutorService}.<p>
029 *
030 * A ManagedScheduledExecutorService provides methods for submitting delayed or
031 * periodic tasks for execution in a managed environment.
032 * Implementations of the ManagedScheduledExecutorService are
033 * provided by a Java™ EE Product Provider. Application Component Providers
034 * use the Java Naming and Directory Interface™ (JNDI) to look-up instances of one
035 * or more ManagedExecutorService objects using resource environment references.<p>
036 *
037 * The Concurrency Utilities for Java™ EE specification describes several
038 * behaviors that a ManagedScheduledExecutorService can implement. The Application
039 * Component Provider and Deployer identify these requirements and map the
040 * resource environment reference appropriately.<p>
041 *
042 * Tasks run within the application component context that either
043 * submitted the task or created the ManagedExecutorService instance (server-managed or component-managed).
044 * All tasks run without an explicit transaction (they do not enlist in the application
045 * component's transaction). If a transaction is required, use a
046 * {@link javax.transaction.UserTransaction} instance. A UserTransaction instance is
047 * available in JNDI using the name: "java:comp/UserTransaction"<p>
048 *
049 * Example:<pre>
050 * public run() {
051 * // Begin of task
052 * InitialContext ctx = new InitialContext();
053 * UserTransaction ut = (UserTransaction) ctx.lookup("java:comp/UserTransaction");
054 * ut.begin();
055 *
056 * // Perform transactional business logic
057 *
058 * ut.commit();
059 * }</PRE>
060 *
061 * Asynchronous tasks are typically submitted to the ManagedScheduledExecutorService using one
062 * of the <code>submit</code> or <code>schedule</code>methods, each of which return a {@link java.util.concurrent.Future}
063 * instance. The Future represents the result of the task and can also be used to
064 * check if the task is complete or wait for its completion.<p>
065 *
066 * If the task is cancelled, the result fo the task is a
067 * {@link java.util.concurrent.CancellationException} exception. If the task is unable
068 * to run due to start due to a reason other than cancellation, the result is a
069 * {@link javax.util.concurrent.AbortedException} exception. If the task is scheduled
070 * with a {@link javax.util.concurrent.Trigger} and the Trigger forces the task to be skipped,
071 * the result will be a {@link javax.util.concurrent.SkippedException} exception.<p>
072 *
073 * Tasks can be scheduled to run periodically using the <code>schedule</code> methods that
074 * take a <code>Trigger</code> as an argument and the <code>scheduleAtFixedRate</code> and
075 * <code>scheduleWithFixedDelay</code> methods. The result of the <code>Future</code> will
076 * be represented by the currently scheduled or running instance of the task. Future and past executions
077 * of the task are not represented by the Future. The state of the <code>Future</code> will therefore change
078 * and multiple results are expected.<p>
079 *
080 * For example, if a task is repeat, the lifecycle of the task would be:<br>
081 * (Note: See {@link javax.util.concurrent.ManagedTaskListener} for task lifecycle management details.)<p>
082 *
083 * <table>
084 * <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>
085 * <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>
086 * <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>
087 * <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>
088 * <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>
089 * <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>
090 * <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>
091 * </table>
092 *
093 *
094 *
095 */
096 public interface ManagedScheduledExecutorService extends ScheduledExecutorService, ManagedExecutorService
097 {
098 /**
099 * 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 }