basecalendar.java

定时器开源项目, 相对于 jcrontab, Quartz 算是更完整的一个项目, 随著开发的版本上来, 他已经脱离只是写在程序里面的计时器, 在指定的时间或区间, 处理所指定的事件. 也加入了 se

/*
 * Copyright Juergen Donnerstag (c) 2002, EDS 2002
 * 
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met: 1.
 * Redistributions of source code must retain the above copyright notice, this
 * list of conditions and the following disclaimer. 2. Redistributions in
 * binary form must reproduce the above copyright notice, this list of
 * conditions and the following disclaimer in the documentation and/or other
 * materials provided with the distribution.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package org.quartz.impl.calendar;

import java.io.Serializable;
import java.util.Date;

import org.quartz.Calendar;

/**
 * <p>
 * This implementation of the Calendar may be used (you don't have to) as a
 * base class for more sophisticated one's. It merely implements the base
 * functionality required by each Calendar.
 * </p>
 * 
 * <p>
 * Regarded as base functionality is the treatment of base calendars. Base
 * calendar allow you to chain (stack) as much calendars as you may need. For
 * example to exclude weekends you may use WeeklyCalendar. In order to exclude
 * holidays as well you may define a WeeklyCalendar instance to be the base
 * calendar for HolidayCalendar instance.
 * </p>
 * 
 * @see org.quartz.Calendar
 * 
 * @author Juergen Donnerstag
 * @author James House
 */
public class BaseCalendar implements Calendar, Serializable {

    // <p>A optional base calendar.</p>
    private Calendar baseCalendar;

    private String description;

    /**
     * <p>
     * Default Constructor
     * </p>
     */
    public BaseCalendar() {
    }

    /**
     * <p>
     * Constructor
     * </p>
     */
    public BaseCalendar(Calendar baseCalendar) {
        setBaseCalendar(baseCalendar);
    }

    /**
     * <p>
     * Set a new base calendar or remove the existing one
     * </p>
     */
    public void setBaseCalendar(Calendar baseCalendar) {
        this.baseCalendar = baseCalendar;
    }

    /**
     * <p>
     * Get the base calendar. Will be null, if not set.
     * </p>
     */
    public Calendar getBaseCalendar() {
        return this.baseCalendar;
    }

    /**
     * <p>
     * Return the description given to the <code>Calendar</code> instance by
     * its creator (if any).
     * </p>
     * 
     * @return null if no description was set.
     */
    public String getDescription() {
        return description;
    }

    /**
     * <p>
     * Set a description for the <code>Calendar</code> instance - may be
     * useful for remembering/displaying the purpose of the calendar, though
     * the description has no meaning to Quartz.
     * </p>
     */
    public void setDescription(String description) {
        this.description = description;
    }

    /**
     * <p>
     * Check if date/time represented by timeStamp is included. If included
     * return true. The implementation of BaseCalendar simply calls the base
     * calendars isTimeIncluded() method if base calendar is set.
     * </p>
     * 
     * @see org.quartz.Calendar#isTimeIncluded(long)
     */
    public boolean isTimeIncluded(long timeStamp) {

        if (timeStamp <= 0)
                throw new IllegalArgumentException(
                        "timeStamp must be greater 0");

        if (baseCalendar != null) {
            if (baseCalendar.isTimeIncluded(timeStamp) == false) { return false; }
        }

        return true;
    }

    /**
     * <p>
     * Determine the next time (in milliseconds) that is 'included' by the
     * Calendar after the given time. Return the original value if timeStamp is
     * included. Return 0 if all days are excluded.
     * </p>
     * 
     * @see org.quartz.Calendar#getNextIncludedTime(long)
     */
    public long getNextIncludedTime(long timeStamp) {

        if (timeStamp <= 0)
                throw new IllegalArgumentException(
                        "timeStamp must be greater 0");

        if (baseCalendar != null) { return baseCalendar
                .getNextIncludedTime(timeStamp); }

        return timeStamp;
    }

    /**
     * <p>
     * Utility method. Return the date of excludeDate. The time fraction will
     * be reset to 00.00:00.
     * </p>
     */
    static public Date buildHoliday(Date excludedDate) {
        java.util.Calendar cl = java.util.Calendar.getInstance();
        java.util.Calendar clEx = java.util.Calendar.getInstance();
        clEx.setTime(excludedDate);

        cl.setLenient(false);
        cl.clear();
        cl.set(clEx.get(java.util.Calendar.YEAR), clEx
                .get(java.util.Calendar.MONTH), clEx
                .get(java.util.Calendar.DATE));

        return cl.getTime();
    }

    /**
     * <p>
     * Utility method. Return just the date of excludeDate. The time fraction
     * will be reset to 00.00:00.
     * </p>
     */
    static public long buildHoliday(long timeStamp) {
        return buildHoliday(new Date(timeStamp)).getTime();
    }

    /**
     * <p>
     * Utility method. Return a java.util.Calendar for timeStamp.
     * </p>
     * 
     * @param timeStamp
     * @return Calendar
     */
    static public java.util.Calendar getJavaCalendar(long timeStamp) {
        java.util.Calendar cl = java.util.Calendar.getInstance();
        cl.setTime(new Date(timeStamp));
        return cl;
    }
}