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.Date;
20 import java.util.concurrent.Future;
21
22 /**
23 * Triggers allow application developers to plug in rules
24 * for when and how often a task should run.
25 * The trigger can be as simple as a single, absolute date-time or can include
26 * Java™ EE business calendar logic.
27 *
28 * A Trigger implementation is created by the application developer
29 * (or may be supplied to the application externally) and is registered
30 * with a task when it is submitted to a {@link javax.util.concurrent.ManagedScheduledExecutorService}
31 * using any of the <code>schedule</code> methods.
32 *
33 * Each method will run with the same context in which the task runs.
34 * The Trigger becomes a Contextual Task.<p>
35 *
36 * Each Trigger instance will be invoked within the same process in which it was registered.<p>
37 *
38 * Example:<pre>
39 * /**
40 * * A trigger that only returns a single date.
41 * */
42 * public class SingleDateTrigger implements Trigger {
43 * private Date fireTime;
44 *
45 * public TriggerSingleDate(Date newDate) {
46 * fireTime = newDate;
47 * }
48 *
49 * public Date getNextRunTime(
50 * Future lastFuture, Date baseTime, Date lastActualRunTime,
51 * Date lastScheduledRunTime, Date lastCompleteTime) {
52 *
53 * if(baseTime.after(fireTime)) {
54 * return null;
55 * }
56 * return fireTime;
57 * }
58 *
59 * public boolean skipRun(Future lastFuture, Date scheduledRunTime) {
60 * return scheduledRunTime.after(fireTime);
61 * }
62 * }
63 *
64 * /**
65 * * A fixed-rate trigger that will skip any runs if
66 * * the latencyAllowance threshold is exceeded (the task
67 * * ran too late).
68 * */
69 * public class TriggerFixedRateLatencySensitive implements Trigger {
70 * private Date startTime;
71 * private long delta;
72 * private long latencyAllowance;
73 *
74 * public TriggerFixedRateLatencySensitive(Date startTime, long delta, long latencyAllowance) {
75 * this.startTime = startTime;
76 * this.delta = delta;
77 * this.latencyAllowance = latencyAllowance;
78 * }
79 *
80 * public Date getNextRunTime(Future lastFuture, Date baseTime, Date lastActualRunTime, Date lastScheduledRunTime, Date lastCompleteTime) {
81 * if(lastActualRunTime==null) {
82 * return startTime;
83 * }
84 * return new Date(lastScheduledRunTime.getTime() + delta);
85 * }
86 *
87 * public boolean skipRun(Future lastFuture, Date scheduledRunTime) {
88 * return System.currentTimeMillis() - scheduledRunTime.getTime() > latencyAllowance;
89 * }
90 * }
91 *
92 * </pre>
93 *
94 */
95 public interface Trigger {
96
97 /**
98 * Retrieve the next time that the task should run after.
99 *
100 * @param lastFuture the state of the Future after the last run.
101 * This value will be null if the task has not yet run.
102 * @param submitTime the time in which the task was originally submitted.
103 * @param lastActualRunTime the time in which the last task actually ran.
104 * This value will be null if the task has not yet run.
105 * @param lastScheduledRunTime the time in which the last task was scheduled to run.
106 * This value will be null if the task has not yet run.
107 * @param lastCompleteTime the time in which the last task completed.
108 * This value will be null if the task has not yet run.
109 * @return the date/time in which the next task iteration should execute on or after.
110 */
111 Date getNextRunTime(Future<?> lastFuture, Date submitTime, Date lastActualRunTime, Date lastScheduledRunTime, Date lastCompleteTime);
112
113 /**
114 * Return true if this run instance should be skipped.<p>
115 *
116 * This is useful if the task shouldn't run because it is late or if the task is
117 * paused or suspended.<p>
118 *
119 * Once this task is skipped, the state of it's Future's result will throw a {@link SkippedException}.
120 * Unchecked exceptions will be wrapped in a SkippedException.
121 *
122 * @param scheduledRunTime the date/time that the task was originally scheduled to run.
123 *
124 * @return true if the task should be skipped and rescheduled.
125 */
126 boolean skipRun(Future<?> lastFuture, Date scheduledRunTime);
127 }