001 /*
002 * ============================================================================
003 * GNU Lesser General Public License
004 * ============================================================================
005 *
006 * Beanlet - JSE Application Container.
007 * Copyright (C) 2006 Leon van Zantvoort
008 *
009 * This library is free software; you can redistribute it and/or
010 * modify it under the terms of the GNU Lesser General Public
011 * License as published by the Free Software Foundation; either
012 * version 2.1 of the License, or (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017 * Lesser General Public License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
022 *
023 * Leon van Zantvoort
024 * 243 Acalanes Drive #11
025 * Sunnyvale, CA 94086
026 * USA
027 *
028 * zantvoort@users.sourceforge.net
029 * http://beanlet.org
030 */
031 package org.beanlet;
032
033 import java.lang.annotation.ElementType;
034 import java.lang.annotation.Retention;
035 import java.lang.annotation.RetentionPolicy;
036 import java.lang.annotation.Target;
037
038 /**
039 * <p>Methods declared with this annotation are scheduled to be executed by a
040 * background thread.</p>
041 *
042 * <p><h3>Method Constraints</h3>
043 * The method on which the {@code Schedule} annotation is applied MUST fulfill all
044 * of the following criteria:
045 * <ul>
046 * <li>The method MUST NOT have any parameters.
047 * <li>The method MAY return any type.
048 * <li>The method MAY throw a checked exception.
049 * <li>The method on which Schedule is applied MAY be {@code public},
050 * {@code protected}, package private or {@code private}.
051 * <li>The method MUST NOT be {@code static}.
052 * <li>The method MAY be {@code final}.
053 * </ul>
054 * </p>
055 *
056 * {@beanlet.annotation}
057 *
058 * @author Leon van Zantvoort
059 */
060 @Retention(RetentionPolicy.RUNTIME)
061 @Target(ElementType.METHOD)
062 public @interface Schedule {
063
064 /**
065 * If {@code true}, the method is scheduled only once.
066 */
067 boolean once() default false;
068
069 /**
070 * If {@code true}, the running threads are interrupted on destroy.
071 */
072 boolean interrupt() default false;
073
074 /**
075 * If {@code true}, the container waits until this component has finished
076 * the runnable method on destroy.
077 */
078 boolean join() default false;
079
080 /**
081 * Set to a positive {@code long} value to let the container wait for an
082 * initial delay before executing the runnable method for the first time.
083 */
084 long initialDelay() default 0L;
085
086 /**
087 * Set to a positive {@code long} value to let the container execute the
088 * runnable method with a fixed delay interval.
089 */
090 long delay() default 0L;
091
092 /**
093 * Set to a positive {@code long} value to let the container execute the
094 * runnable method with a fixed rate interval.
095 */
096 long rate() default 0L;
097
098 /**
099 * <p>Provides a parser and evaluator for unix-like cron expressions. Cron
100 * expressions provide the ability to specify complex time combinations such as
101 * "At 8:00am every Monday through Friday" or "At 1:30am every
102 * last Friday of the month".</p>
103 * <p>Cron expressions are comprised of 6 required fields and two optional fields
104 * separated by white space. The fields respectively are described as follows:
105 * <table cellspacing="8">
106 * <tr>
107 * <th align="left">Field Name</th>
108 * <th align="left"> </th>
109 * <th align="left">Allowed Values</th>
110 * <th align="left"> </th>
111 * <th align="left">Allowed Special Characters</th>
112 * </tr>
113 * <tr>
114 * <td align="left"><code>Seconds</code></td>
115 * <td align="left"> </th>
116 * <td align="left"><code>0-59</code></td>
117 * <td align="left"> </th>
118 * <td align="left"><code>, - * /</code></td>
119 * </tr>
120 * <tr>
121 * <td align="left"><code>Minutes</code></td>
122 * <td align="left"> </th>
123 * <td align="left"><code>0-59</code></td>
124 * <td align="left"> </th>
125 * <td align="left"><code>, - * /</code></td>
126 * </tr>
127 * <tr>
128 * <td align="left"><code>Hours</code></td>
129 * <td align="left"> </th>
130 * <td align="left"><code>0-23</code></td>
131 * <td align="left"> </th>
132 * <td align="left"><code>, - * /</code></td>
133 * </tr>
134 * <tr>
135 * <td align="left"><code>Day-of-month</code></td>
136 * <td align="left"> </th>
137 * <td align="left"><code>1-31</code></td>
138 * <td align="left"> </th>
139 * <td align="left"><code>, - * ? / L W</code></td>
140 * </tr>
141 * <td align="left"><code>Month</code></td>
142 * <td align="left"> </th>
143 * <td align="left"><code>1-12 or JAN-DEC</code></td>
144 * <td align="left"> </th>
145 * <td align="left"><code>, - * /</code></td>
146 * </tr>
147 * <tr>
148 * <td align="left"><code>Day-of-Week</code></td>
149 * <td align="left"> </th>
150 * <td align="left"><code>1-7 or SUN-SAT</code></td>
151 * <td align="left"> </th>
152 * <td align="left"><code>, - * ? / L #</code></td>
153 * </tr>
154 * <tr>
155 * <td align="left"><code>Year (Optional)</code></td>
156 * <td align="left"> </th>
157 * <td align="left"><code>empty, 1970-2099</code></td>
158 * <td align="left"> </th>
159 * <td align="left"><code>, - * /</code></td>
160 * </tr>
161 * <tr>
162 * <td align="left"><code>TimeZone (Optional)</code></td>
163 * <td align="left"> </th>
164 * <td align="left"><code>empty, Europe/Amsterdam</code></td>
165 * <td align="left"> </th>
166 * <td align="left"><code>*</code></td>
167 * </tr>
168 * </table>
169 * </p>
170 *
171 * <p>The '*' character is used to specify all values. For example, "*"
172 * in the minute field means "every minute".</p>
173 *
174 * <p>The '?' character is allowed for the day-of-month and day-of-week fields. It
175 * is used to specify 'no specific value'. This is useful when you need to
176 * specify something in one of the two fileds, but not the other.</p>
177 *
178 * <p>The '-' character is used to specify ranges For example "10-12" in
179 * the hour field means "the hours 10, 11 and 12".</p>
180 *
181 * <p>The ',' character is used to specify additional values. For example
182 * "MON,WED,FRI" in the day-of-week field means "the days Monday,
183 * Wednesday, and Friday".</p>
184 *
185 * <p>The '/' character is used to specify increments. For example "0/15"
186 * in the seconds field means "the seconds 0, 15, 30, and 45". And
187 * "5/15" in the seconds field means "the seconds 5, 20, 35, and
188 * 50". Specifying '*' before the '/' is equivalent to specifying 0 is
189 * the value to start with. Essentially, for each field in the expression, there
190 * is a set of numbers that can be turned on or off. For seconds and minutes,
191 * the numbers range from 0 to 59. For hours 0 to 23, for days of the month 0 to
192 * 31, and for months 1 to 12. The "/" character simply helps you turn
193 * on every "nth" value in the given set. Thus "7/6" in the
194 * month field only turns on month "7", it does NOT mean every 6th
195 * month, please note that subtlety.<p>
196 *
197 * <p>The 'L' character is allowed for the day-of-month and day-of-week fields.
198 * This character is short-hand for "last", but it has different
199 * meaning in each of the two fields. For example, the value "L" in
200 * the day-of-month field means "the last day of the month" - day 31
201 * for January, day 28 for February on non-leap years. If used in the
202 * day-of-week field by itself, it simply means "7" or
203 * "SAT". But if used in the day-of-week field after another value, it
204 * means "the last xxx day of the month" - for example "6L"
205 * means "the last friday of the month". When using the 'L' option, it
206 * is important not to specify lists, or ranges of values, as you'll get
207 * confusing results.</p>
208 *
209 * <p>The 'W' character is allowed for the day-of-month field. This character
210 * is used to specify the weekday (Monday-Friday) nearest the given day. As an
211 * example, if you were to specify "15W" as the value for the
212 * day-of-month field, the meaning is: "the nearest weekday to the 15th of
213 * the month". So if the 15th is a Saturday, the trigger will fire on
214 * Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the
215 * 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th.
216 * However if you specify "1W" as the value for day-of-month, and the
217 * 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not
218 * 'jump' over the boundary of a month's days. The 'W' character can only be
219 * specified when the day-of-month is a single day, not a range or list of days.</p>
220 *
221 * <p>The 'L' and 'W' characters can also be combined for the day-of-month
222 * expression to yield 'LW', which translates to "last weekday of the
223 * month".</p>
224 *
225 * <p>The '#' character is allowed for the day-of-week field. This character is
226 * used to specify "the nth" XXX day of the month. For example, the
227 * value of "6#3" in the day-of-week field means the third Friday of
228 * the month (day 6 = Friday and "#3" = the 3rd one in the month).
229 * Other examples: "2#1" = the first Monday of the month and
230 * "4#5" = the fifth Wednesday of the month. Note that if you specify
231 * "#5" and there is not 5 of the given day-of-week in the month, then
232 * no firing will occur that month.</p>
233 *
234 * <p>The legal characters and the names of months and days of the week are not
235 * case sensitive.<p>
236 *
237 * <p>
238 * <b>NOTES:</b>
239 * <ul>
240 * <li>Support for specifying both a day-of-week and a day-of-month value is
241 * not complete (you'll need to use the '?' character in on of these fields).
242 * </li>
243 * </ul>
244 * </p>
245 */
246 String cron() default "";
247
248 /**
249 * Set to {@code true} if schedule must be performed even in case of misfire.
250 */
251 boolean fireAll() default false;
252
253 /**
254 * Description of the underlying schedulable method.
255 */
256 String description() default "";
257 }