KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > quartz > impl > calendar > CronCalendar


1 package org.quartz.impl.calendar;
2
3 import java.text.ParseException JavaDoc;
4 import java.util.Date JavaDoc;
5 import java.util.TimeZone JavaDoc;
6
7 import org.quartz.Calendar;
8 import org.quartz.CronExpression;
9
10 /**
11  * This implementation of the Calendar excludes the set of times expressed by a
12  * given {@link org.quartz.CronExpression CronExpression}. For example, you
13  * could use this calendar to exclude all but business hours (8AM - 5PM) every
14  * day using the expression "* * 0-7,18-23 ? * *".
15  * <P>
16  * It is important to remember that the cron expression here describes a set of
17  * times to be <I>excluded</I> from firing. Whereas the cron expression in
18  * {@link org.quartz.CronTrigger CronTrigger} describes a set of times that can
19  * be <I>included</I> for firing. Thus, if a <CODE>CronTrigger</CODE> has a
20  * given cron expression and is associated with a <CODE>CronCalendar</CODE> with
21  * the <I>same</I> expression, the calendar will exclude all the times the
22  * trigger includes, and they will cancel each other out.
23  *
24  * @author Aaron Craven
25  */
26 public class CronCalendar extends BaseCalendar {
27     static final long serialVersionUID = -8172103999750856831L;
28
29     /** @deprecated The use of <code>name</code> is no longer supported. */
30     private String JavaDoc name;
31     
32     CronExpression cronExpression;
33
34     /**
35      * Create a <CODE>CronCalendar</CODE> with the given cron expression and no
36      * <CODE>baseCalendar</CODE>.
37      *
38      * @param expression a String representation of the desired cron expression
39      */
40     public CronCalendar(String JavaDoc expression)
41         throws ParseException JavaDoc {
42         this(null, expression, null);
43     }
44
45     /**
46      * Create a <CODE>CronCalendar</CODE> with the given cron expression and
47      * <CODE>baseCalendar</CODE>.
48      *
49      * @param baseCalendar the base calendar for this calendar instance &ndash;
50      * see {@link BaseCalendar} for more information on base
51      * calendar functionality
52      * @param expression a String representation of the desired cron expression
53      */
54     public CronCalendar(Calendar baseCalendar,
55             String JavaDoc expression) throws ParseException JavaDoc {
56         this(baseCalendar, expression, null);
57     }
58
59     /**
60      * Create a <CODE>CronCalendar</CODE> with the given cron exprssion,
61      * <CODE>baseCalendar</CODE>, and <code>TimeZone</code>.
62      *
63      * @param baseCalendar the base calendar for this calendar instance &ndash;
64      * see {@link BaseCalendar} for more information on base
65      * calendar functionality
66      * @param expression a String representation of the desired cron expression
67      * @param timeZone
68      * Specifies for which time zone the <code>expression</code>
69      * should be interpreted, i.e. the expression 0 0 10 * * ?, is
70      * resolved to 10:00 am in this time zone. If
71      * <code>timeZone</code> is <code>null</code> then
72      * <code>TimeZone.getDefault()</code> will be used.
73      */
74     public CronCalendar(Calendar baseCalendar,
75             String JavaDoc expression, TimeZone JavaDoc timeZone) throws ParseException JavaDoc {
76         super(baseCalendar);
77         this.cronExpression = new CronExpression(expression);
78         this.cronExpression.setTimeZone(timeZone);
79     }
80
81     /**
82      * @deprecated The use of <code>name</code> is no longer supported.
83      *
84      * @see #CronCalendar(String)
85      */
86     public CronCalendar(String JavaDoc name, String JavaDoc expression)
87         throws ParseException JavaDoc {
88         this(expression);
89         this.name = name;
90     }
91
92     /**
93      * @deprecated The use of <code>name</code> is no longer supported.
94      *
95      * @see #CronCalendar(Calendar, String)
96      */
97     public CronCalendar(String JavaDoc name, Calendar baseCalendar,
98             String JavaDoc expression) throws ParseException JavaDoc {
99         this(baseCalendar, expression);
100         this.name = name;
101     }
102
103     /**
104      * @deprecated The use of <code>name</code> is no longer supported.
105      *
106      * @see #CronCalendar(Calendar, String, TimeZone)
107      */
108     public CronCalendar(String JavaDoc name, Calendar baseCalendar,
109             String JavaDoc expression, TimeZone JavaDoc timeZone) throws ParseException JavaDoc {
110         this(baseCalendar, expression, timeZone);
111         this.name = name;
112     }
113
114     /**
115      * Returns the time zone for which the <code>CronExpression</code> of
116      * this <code>CronCalendar</code> will be resolved.
117      * <p>
118      * Overrides <code>{@link BaseCalendar#getTimeZone()}</code> to
119      * defer to its <code>CronExpression</code>.
120      * </p>
121      */
122     public TimeZone JavaDoc getTimeZone() {
123         return cronExpression.getTimeZone();
124     }
125
126     /**
127      * Sets the time zone for which the <code>CronExpression</code> of this
128      * <code>CronCalendar</code> will be resolved. If <code>timeZone</code>
129      * is <code>null</code> then <code>TimeZone.getDefault()</code> will be
130      * used.
131      * <p>
132      * Overrides <code>{@link BaseCalendar#setTimeZone(TimeZone)}</code> to
133      * defer to its <code>CronExpression</code>.
134      * </p>
135      */
136     public void setTimeZone(TimeZone JavaDoc timeZone) {
137         cronExpression.setTimeZone(timeZone);
138     }
139     
140     /**
141      * Returns the name of the <CODE>CronCalendar</CODE>
142      *
143      * @return the name of the <CODE>CronCalendar</CODE>
144      *
145      * @deprecated The use of <code>name</code> is no longer supported.
146      */
147     public String JavaDoc getName() {
148         return name;
149     }
150
151     /**
152      * Determines whether the given time (in milliseconds) is 'included' by the
153      * <CODE>BaseCalendar</CODE>
154      *
155      * @param timeInMillis the date/time to test
156      * @return a boolean indicating whether the specified time is 'included' by
157      * the <CODE>CronCalendar</CODE>
158      */
159     public boolean isTimeIncluded(long timeInMillis) {
160         if ((getBaseCalendar() != null) &&
161                 (getBaseCalendar().isTimeIncluded(timeInMillis) == false)) {
162             return false;
163         }
164         
165         return (!(cronExpression.isSatisfiedBy(new Date JavaDoc(timeInMillis))));
166     }
167
168     /**
169      * Determines the next time included by the <CODE>CronCalendar</CODE>
170      * after the specified time.
171      *
172      * @param timeInMillis the initial date/time after which to find an
173      * included time
174      * @return the time in milliseconds representing the next time included
175      * after the specified time.
176      */
177     public long getNextIncludedTime(long timeInMillis) {
178         long nextIncludedTime = timeInMillis + 1; //plus on millisecond
179
180         while (!isTimeIncluded(nextIncludedTime)) {
181
182             //If the time is in a range excluded by this calendar, we can
183 // move to the end of the excluded time range and continue testing
184 // from there. Otherwise, if nextIncludedTime is excluded by the
185 // baseCalendar, ask it the next time it includes and begin testing
186 // from there. Failing this, add one millisecond and continue
187 // testing.
188 if (cronExpression.isSatisfiedBy(new Date JavaDoc(nextIncludedTime))) {
189                 nextIncludedTime = cronExpression.getNextInvalidTimeAfter(
190                         new Date JavaDoc(nextIncludedTime)).getTime();
191             } else if ((getBaseCalendar() != null) &&
192                     (!getBaseCalendar().isTimeIncluded(nextIncludedTime))){
193                 nextIncludedTime =
194                     getBaseCalendar().getNextIncludedTime(nextIncludedTime);
195             } else {
196                 nextIncludedTime++;
197             }
198         }
199         
200         return nextIncludedTime;
201     }
202
203     /**
204      * Returns a string representing the properties of the
205      * <CODE>CronCalendar</CODE>
206      *
207      * @return the properteis of the CronCalendar in a String format
208      */
209     public String JavaDoc toString() {
210         StringBuffer JavaDoc buffer = new StringBuffer JavaDoc();
211         if (name != null) {
212             buffer.append(name).append(": ");
213         }
214         buffer.append("base calendar: [");
215         if (getBaseCalendar() != null) {
216             buffer.append(getBaseCalendar().toString());
217         } else {
218             buffer.append("null");
219         }
220         buffer.append("], excluded cron expression: '");
221         buffer.append(cronExpression);
222         buffer.append("'");
223         return buffer.toString();
224     }
225     
226     /**
227      * Returns the object representation of the cron expression that defines the
228      * dates and times this calendar excludes.
229      *
230      * @return the cron expression
231      * @see org.quartz.CronExpression
232      */
233     public CronExpression getCronExpression() {
234         return cronExpression;
235     }
236     
237     /**
238      * Sets the cron expression for the calendar to a new value
239      *
240      * @param expression the new string value to build a cron expression from
241      * @throws ParseException
242      * if the string expression cannot be parsed
243      */
244     public void setCronExpression(String JavaDoc expression) throws ParseException JavaDoc {
245         CronExpression newExp = new CronExpression(expression);
246         
247         this.cronExpression = newExp;
248     }
249
250     /**
251      * Sets the cron expression for the calendar to a new value
252      *
253      * @param expression the new cron expression
254      */
255     public void setCronExpression(CronExpression expression) {
256         if (expression == null) {
257             throw new IllegalArgumentException JavaDoc("expression cannot be null");
258         }
259         
260         this.cronExpression = expression;
261     }
262 }
Popular Tags