001: /*
002: * Copyright 2004-2005 OpenSymphony
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy
006: * of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations
014: * under the License.
015: *
016: */
017:
018: /*
019: * Previously Copyright (c) 2001-2004 James House
020: * and Juergen Donnerstag (c) 2002, EDS 2002
021: */
022:
023: package org.quartz.impl.calendar;
024:
025: import java.io.Serializable;
026: import java.util.Date;
027: import java.util.TimeZone;
028:
029: import org.quartz.Calendar;
030:
031: /**
032: * <p>
033: * This implementation of the Calendar may be used (you don't have to) as a
034: * base class for more sophisticated one's. It merely implements the base
035: * functionality required by each Calendar.
036: * </p>
037: *
038: * <p>
039: * Regarded as base functionality is the treatment of base calendars. Base
040: * calendar allow you to chain (stack) as much calendars as you may need. For
041: * example to exclude weekends you may use WeeklyCalendar. In order to exclude
042: * holidays as well you may define a WeeklyCalendar instance to be the base
043: * calendar for HolidayCalendar instance.
044: * </p>
045: *
046: * @see org.quartz.Calendar
047: *
048: * @author Juergen Donnerstag
049: * @author James House
050: */
051: public class BaseCalendar implements Calendar, Serializable {
052:
053: static final long serialVersionUID = 3106623404629760239L;
054:
055: // <p>A optional base calendar.</p>
056: private Calendar baseCalendar;
057:
058: private String description;
059:
060: private TimeZone timeZone;
061:
062: public BaseCalendar() {
063: }
064:
065: public BaseCalendar(Calendar baseCalendar) {
066: setBaseCalendar(baseCalendar);
067: }
068:
069: /**
070: * @param timeZone The time zone to use for this Calendar, <code>null</code>
071: * if <code>{@link TimeZone#getDefault()}</code> should be used
072: */
073: public BaseCalendar(TimeZone timeZone) {
074: setTimeZone(timeZone);
075: }
076:
077: /**
078: * @param timeZone The time zone to use for this Calendar, <code>null</code>
079: * if <code>{@link TimeZone#getDefault()}</code> should be used
080: */
081: public BaseCalendar(Calendar baseCalendar, TimeZone timeZone) {
082: setBaseCalendar(baseCalendar);
083: setTimeZone(timeZone);
084: }
085:
086: /**
087: * <p>
088: * Set a new base calendar or remove the existing one
089: * </p>
090: */
091: public void setBaseCalendar(Calendar baseCalendar) {
092: this .baseCalendar = baseCalendar;
093: }
094:
095: /**
096: * <p>
097: * Get the base calendar. Will be null, if not set.
098: * </p>
099: */
100: public Calendar getBaseCalendar() {
101: return this .baseCalendar;
102: }
103:
104: /**
105: * <p>
106: * Return the description given to the <code>Calendar</code> instance by
107: * its creator (if any).
108: * </p>
109: *
110: * @return null if no description was set.
111: */
112: public String getDescription() {
113: return description;
114: }
115:
116: /**
117: * <p>
118: * Set a description for the <code>Calendar</code> instance - may be
119: * useful for remembering/displaying the purpose of the calendar, though
120: * the description has no meaning to Quartz.
121: * </p>
122: */
123: public void setDescription(String description) {
124: this .description = description;
125: }
126:
127: /**
128: * Returns the time zone for which this <code>Calendar</code> will be
129: * resolved.
130: *
131: * @return This Calendar's timezone, <code>null</code> if Calendar should
132: * use the <code>{@link TimeZone#getDefault()}</code>
133: */
134: public TimeZone getTimeZone() {
135: return timeZone;
136: }
137:
138: /**
139: * Sets the time zone for which this <code>Calendar</code> will be resolved.
140: *
141: * @param timeZone The time zone to use for this Calendar, <code>null</code>
142: * if <code>{@link TimeZone#getDefault()}</code> should be used
143: */
144: public void setTimeZone(TimeZone timeZone) {
145: this .timeZone = timeZone;
146: }
147:
148: /**
149: * <p>
150: * Check if date/time represented by timeStamp is included. If included
151: * return true. The implementation of BaseCalendar simply calls the base
152: * calendars isTimeIncluded() method if base calendar is set.
153: * </p>
154: *
155: * @see org.quartz.Calendar#isTimeIncluded(long)
156: */
157: public boolean isTimeIncluded(long timeStamp) {
158:
159: if (timeStamp <= 0) {
160: throw new IllegalArgumentException(
161: "timeStamp must be greater 0");
162: }
163:
164: if (baseCalendar != null) {
165: if (baseCalendar.isTimeIncluded(timeStamp) == false) {
166: return false;
167: }
168: }
169:
170: return true;
171: }
172:
173: /**
174: * <p>
175: * Determine the next time (in milliseconds) that is 'included' by the
176: * Calendar after the given time. Return the original value if timeStamp is
177: * included. Return 0 if all days are excluded.
178: * </p>
179: *
180: * @see org.quartz.Calendar#getNextIncludedTime(long)
181: */
182: public long getNextIncludedTime(long timeStamp) {
183:
184: if (timeStamp <= 0) {
185: throw new IllegalArgumentException(
186: "timeStamp must be greater 0");
187: }
188:
189: if (baseCalendar != null) {
190: return baseCalendar.getNextIncludedTime(timeStamp);
191: }
192:
193: return timeStamp;
194: }
195:
196: /**
197: * Utility method. Return the date of excludeDate. The time fraction will
198: * be reset to 00.00:00.
199: *
200: * @deprecated Always uses the default time zone.
201: */
202: public static Date buildHoliday(Date excludedDate) {
203: return new BaseCalendar().getStartOfDayJavaCalendar(
204: excludedDate.getTime()).getTime();
205: }
206:
207: /**
208: * Utility method. Return just the date of timeStamp. The time fraction
209: * will be reset to 00.00:00.
210: *
211: * @deprecated Always uses the default time zone.
212: */
213: public static long buildHoliday(long timeStamp) {
214: return new BaseCalendar().getStartOfDayJavaCalendar(timeStamp)
215: .getTime().getTime();
216: }
217:
218: /**
219: * Utility method. Return a java.util.Calendar for timeStamp.
220: *
221: * @deprecated Always uses the default time zone.
222: */
223: public static java.util.Calendar getJavaCalendar(long timeStamp) {
224: return new BaseCalendar().createJavaCalendar(timeStamp);
225: }
226:
227: /**
228: * Build a <code>{@link java.util.Calendar}</code> for the given timeStamp.
229: * The new Calendar will use the <code>BaseCalendar</code> time zone if it
230: * is not <code>null</code>.
231: */
232: protected java.util.Calendar createJavaCalendar(long timeStamp) {
233: java.util.Calendar calendar = createJavaCalendar();
234: calendar.setTime(new Date(timeStamp));
235: return calendar;
236: }
237:
238: /**
239: * Build a <code>{@link java.util.Calendar}</code> with the current time.
240: * The new Calendar will use the <code>BaseCalendar</code> time zone if
241: * it is not <code>null</code>.
242: */
243: protected java.util.Calendar createJavaCalendar() {
244: return (getTimeZone() == null) ? java.util.Calendar
245: .getInstance() : java.util.Calendar
246: .getInstance(getTimeZone());
247: }
248:
249: /**
250: * Returns the start of the given day as a <code>{@link java.util.Calendar}</code>.
251: * This calculation will take the <code>BaseCalendar</code>
252: * time zone into account if it is not <code>null</code>.
253: *
254: * @param timeInMillis A time containing the desired date for the
255: * start-of-day time
256: * @return A <code>{@link java.util.Calendar}</code> set to the start of
257: * the given day.
258: */
259: protected java.util.Calendar getStartOfDayJavaCalendar(
260: long timeInMillis) {
261: java.util.Calendar startOfDay = createJavaCalendar(timeInMillis);
262: startOfDay.set(java.util.Calendar.HOUR_OF_DAY, 0);
263: startOfDay.set(java.util.Calendar.MINUTE, 0);
264: startOfDay.set(java.util.Calendar.SECOND, 0);
265: startOfDay.set(java.util.Calendar.MILLISECOND, 0);
266: return startOfDay;
267: }
268:
269: /**
270: * Returns the end of the given day <code>{@link java.util.Calendar}</code>.
271: * This calculation will take the <code>BaseCalendar</code>
272: * time zone into account if it is not <code>null</code>.
273: *
274: * @param timeInMillis a time containing the desired date for the
275: * end-of-day time.
276: * @return A <code>{@link java.util.Calendar}</code> set to the end of
277: * the given day.
278: */
279: protected java.util.Calendar getEndOfDayJavaCalendar(
280: long timeInMillis) {
281: java.util.Calendar endOfDay = createJavaCalendar(timeInMillis);
282: endOfDay.set(java.util.Calendar.HOUR_OF_DAY, 23);
283: endOfDay.set(java.util.Calendar.MINUTE, 59);
284: endOfDay.set(java.util.Calendar.SECOND, 59);
285: endOfDay.set(java.util.Calendar.MILLISECOND, 999);
286: return endOfDay;
287: }
288: }
|