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: */
021:
022: package org.quartz;
023:
024: /**
025: * <p>
026: * An interface to be implemented by objects that define spaces of time during
027: * which an associated <code>{@link Trigger}</code> may fire. Calendars do not
028: * define actual fire times, but rather are used to limit a <code>Trigger</code>
029: * from firing on its normal schedule if necessary. Most Calendars include all
030: * times by default and allow the user to specify times to exclude. As such, it
031: * is often useful to think of Calendars as being used to <I>exclude</I> a block
032: * of time — as opposed to <I>include</I> a block of time. (i.e. the
033: * schedule "fire every five minutes except on Sundays" could be
034: * implemented with a <code>SimpleTrigger</code> and a
035: * <code>WeeklyCalendar</code> which excludes Sundays)
036: * </p>
037: *
038: * @author James House
039: * @author Juergen Donnerstag
040: */
041: public interface Calendar extends java.io.Serializable {
042:
043: /*
044: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
045: *
046: * Constants.
047: *
048: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
049: */
050:
051: int MONTH = 0;
052:
053: /*
054: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
055: *
056: * Interface.
057: *
058: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
059: */
060:
061: /**
062: * <p>
063: * Set a new base calendar or remove the existing one.
064: * </p>
065: */
066: void setBaseCalendar(Calendar baseCalendar);
067:
068: /**
069: * <p>
070: * Get the base calendar. Will be null, if not set.
071: * </p>
072: */
073: Calendar getBaseCalendar();
074:
075: /**
076: * <p>
077: * Determine whether the given time (in milliseconds) is 'included' by the
078: * Calendar.
079: * </p>
080: */
081: boolean isTimeIncluded(long timeStamp);
082:
083: /**
084: * <p>
085: * Determine the next time (in milliseconds) that is 'included' by the
086: * Calendar after the given time.
087: * </p>
088: */
089: long getNextIncludedTime(long timeStamp);
090:
091: /**
092: * <p>
093: * Return the description given to the <code>Calendar</code> instance by
094: * its creator (if any).
095: * </p>
096: *
097: * @return null if no description was set.
098: */
099: String getDescription();
100:
101: /**
102: * <p>
103: * Set a description for the <code>Calendar</code> instance - may be
104: * useful for remembering/displaying the purpose of the calendar, though
105: * the description has no meaning to Quartz.
106: * </p>
107: */
108: void setDescription(String description);
109: }
|