triggerutils.java

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

/*
 * Copyright James House (c) 2001-2004
 * 
 * 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.helpers;

import java.util.Calendar;
import java.util.Date;
import java.util.LinkedList;
import java.util.List;

import org.quartz.CronTrigger;
import org.quartz.Scheduler;
import org.quartz.SimpleTrigger;
import org.quartz.Trigger;

/**
 * <p>
 * Convenience and utility methods for simplifying the construction and
 * configuration of <code>{@link Trigger}s</code>.
 * </p>
 * 
 * <p>
 * Please submit suggestions for additional convenience methods to either the
 * Quartz user forum or the developer's mail list at
 * <a href="http://www.sourceforge.net/projects/quartz">source forge</a>.
 * </p>
 * 
 * @see CronTrigger
 * @see SimpleTrigger
 * 
 * @author James House
 */
public class TriggerUtils {

    /*
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     * 
     * Constants.
     * 
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     */

    public static final int SUNDAY = 1;

    public static final int MONDAY = 2;

    public static final int TUESDAY = 3;

    public static final int WEDNESDAY = 4;

    public static final int THURSDAY = 5;

    public static final int FRIDAY = 6;

    public static final int SATURDAY = 7;

    public static final int LAST_DAY_OF_MONTH = -1;

    public static final long MILLISECONDS_IN_MINUTE = 60l * 1000l;

    public static final long MILLISECONDS_IN_HOUR = 60l * 60l * 1000l;

    public static final long SECONDS_IN_DAY = 24l * 60l * 60L;

    public static final long MILLISECONDS_IN_DAY = SECONDS_IN_DAY * 1000l;

    /*
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     * 
     * Interface.
     * 
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     */

    private static void validateDayOfWeek(int dayOfWeek) {
        if (dayOfWeek < SUNDAY || dayOfWeek > SATURDAY)
                throw new IllegalArgumentException("Invalid day of week.");
    }

    private static void validateHour(int hour) {
        if (hour < 0 || hour > 23)
                throw new IllegalArgumentException(
                        "Invalid hour (must be >= 0 and <= 23).");
    }

    private static void validateMinute(int minute) {
        if (minute < 0 || minute > 59)
                throw new IllegalArgumentException(
                        "Invalid minute (must be >= 0 and <= 59).");
    }

    private static void validateSecond(int second) {
        if (second < 0 || second > 59)
                throw new IllegalArgumentException(
                        "Invalid second (must be >= 0 and <= 59).");
    }

    private static void validateDayOfMonth(int day) {
        if ((day < 0 || day > 31) && day != LAST_DAY_OF_MONTH)
                throw new IllegalArgumentException("Invalid day of month.");
    }

    private static void validateMonth(int month) {
        if (month < 1 || month > 12)
                throw new IllegalArgumentException(
                        "Invalid month (must be >= 1 and <= 12.");
    }

    private static void validateYear(int year) {
        if (year < 1970 || year > 2099)
                throw new IllegalArgumentException(
                        "Invalid year (must be >= 1970 and <= 2099.");
    }

    /**
     * <p>
     * Set the given <code>Trigger</code>'s name to the given value, and its
     * group to the default group (<code>Scheduler.DEFAULT_GROUP</code>).
     * </p>
     */
    public static void setTriggerIdentity(Trigger trig, String name) {
        trig.setName(name);
        trig.setGroup(Scheduler.DEFAULT_GROUP);
    }

    /**
     * <p>
     * Set the given <code>Trigger</code>'s name to the given value, and its
     * group to the given group.
     * </p>
     */
    public static void setTriggerIdentity(Trigger trig, String name,
            String group) {
        trig.setName(name);
        trig.setGroup(group);
    }

    /**
     * <p>
     * Make a trigger that will fire every day at the given time.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     * 
     * @param hour
     *          the hour (0-23) upon which to fire
     * @param minute
     *          the minute (0-59) upon which to fire
     */
    public static Trigger makeDailyTrigger(int hour, int minute) {
        validateHour(hour);
        validateMinute(minute);

        CronTrigger trig = new CronTrigger();

        try {
            trig.setCronExpression("0 " + minute + " " + hour + " ? * *");
        } catch (Exception ignore) {
            return null; /* never happens... */
        }

        return trig;
    }

    /**
     * <p>
     * Make a trigger that will fire every day at the given time.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     * 
     * @param dayOfWeek
     *          (1-7) the day of week upon which to fire
     * @param hour
     *          the hour (0-23) upon which to fire
     * @param minute
     *          the minute (0-59) upon which to fire
     * 
     * @see #SUNDAY
     * @see #MONDAY
     * @see #TUESDAY
     * @see #WEDNESDAY
     * @see #THURSDAY
     * @see #FRIDAY
     * @see #SATURDAY
     */
    public static Trigger makeWeeklyTrigger(int dayOfWeek, int hour, int minute) {
        validateDayOfWeek(dayOfWeek);
        validateHour(hour);
        validateMinute(minute);

        CronTrigger trig = new CronTrigger();

        try {
            trig.setCronExpression("0 " + minute + " " + hour + " ? * "
                    + dayOfWeek);
        } catch (Exception ignore) {
            return null; /* never happens... */
        }

        return trig;
    }

    /**
     * <p>
     * Make a trigger that will fire every day at the given time.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     * 
     * <p>
     * If the day of the month specified does not occur in a given month, a
     * firing will not occur that month. (i.e. if dayOfMonth is specified as
     * 31, no firing will occur in the months of the year with fewer than 31
     * days).
     * </p>
     * 
     * @param dayOfMonth
     *          (1-31, or -1) the day of week upon which to fire
     * @param hour
     *          the hour (0-23) upon which to fire
     * @param minute
     *          the minute (0-59) upon which to fire
     */
    public static Trigger makeMonthlyTrigger(int dayOfMonth, int hour,
            int minute) {
        validateDayOfMonth(dayOfMonth);
        validateHour(hour);
        validateMinute(minute);

        CronTrigger trig = new CronTrigger();

        try {
            if (dayOfMonth != LAST_DAY_OF_MONTH) trig.setCronExpression("0 "
                    + minute + " " + hour + " " + dayOfMonth + " * ?");
            else
                trig.setCronExpression("0 " + minute + " " + hour + " L * ?");
        } catch (Exception ignore) {
            return null; /* never happens... */
        }

        return trig;
    }

    /*
     * <p> Make a trigger that will fire every N days at the given time. </p>
     * 
     * <p> The generated trigger will still need to have its name, group,
     * start-time and end-time set. </p>
     * 
     * @param hour the hour (0-23) upon which to fire @param minute the minute
     * (0-59) upon which to fire @param interval the number of days between
     * firings public static Trigger makeDailyTrigger(int interval, int hour,
     * int minute) {
     * 
     * SimpleTrigger trig = new SimpleTrigger();
     * 
     * MILLISECONDS_IN_DAY);
     * trig.setRepeatCount(SimpleTrigger.REPEAT_INDEFINITELY);
     * 
     * return trig;
     *  }
     */

    /**
     * <p>
     * Make a trigger that will fire every second, indefinitely.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     *  
     */
    public static Trigger makeSecondlyTrigger() {
        return makeSecondlyTrigger(1, SimpleTrigger.REPEAT_INDEFINITELY);
    }

    /**
     * <p>
     * Make a trigger that will fire every N seconds, indefinitely.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     * 
     * @param intervalInSeconds
     *          the number of seconds between firings
     */
    public static Trigger makeSecondlyTrigger(int intervalInSeconds) {
        return makeSecondlyTrigger(intervalInSeconds,
                SimpleTrigger.REPEAT_INDEFINITELY);
    }

    /**
     * <p>
     * Make a trigger that will fire every N seconds, with the given number of
     * repeats.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     * 
     * @param intervalInSeconds
     *          the number of seconds between firings
     * @param repeatCount
     *          the number of times to repeat the firing
     */
    public static Trigger makeSecondlyTrigger(int intervalInSeconds,
            int repeatCount) {
        SimpleTrigger trig = new SimpleTrigger();

        trig.setRepeatInterval(intervalInSeconds * 1000l);
        trig.setRepeatCount(repeatCount);

        return trig;
    }

    /**
     * <p>
     * Make a trigger that will fire every minute, indefinitely.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     *  
     */
    public static Trigger makeMinutelyTrigger() {
        return makeMinutelyTrigger(1, SimpleTrigger.REPEAT_INDEFINITELY);
    }

    /**
     * <p>
     * Make a trigger that will fire every N minutes, indefinitely.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     * 
     * @param intervalInMinutes
     *          the number of minutes between firings
     */
    public static Trigger makeMinutelyTrigger(int intervalInMinutes) {
        return makeMinutelyTrigger(intervalInMinutes,
                SimpleTrigger.REPEAT_INDEFINITELY);
    }

    /**
     * <p>
     * Make a trigger that will fire every N minutes, with the given number of
     * repeats.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     * 
     * @param intervalInMinutes
     *          the number of minutes between firings
     * @param repeatCount
     *          the number of times to repeat the firing
     */
    public static Trigger makeMinutelyTrigger(int intervalInMinutes,
            int repeatCount) {
        SimpleTrigger trig = new SimpleTrigger();

        trig.setRepeatInterval(intervalInMinutes * MILLISECONDS_IN_MINUTE);
        trig.setRepeatCount(repeatCount);

        return trig;
    }

    /**
     * <p>
     * Make a trigger that will fire every hour, indefinitely.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     *  
     */
    public static Trigger makeHourlyTrigger() {
        return makeHourlyTrigger(1, SimpleTrigger.REPEAT_INDEFINITELY);
    }

    /**
     * <p>
     * Make a trigger that will fire every N hours, indefinitely.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     * 
     * @param intervalInHours
     *          the number of hours between firings
     */
    public static Trigger makeHourlyTrigger(int intervalInHours) {
        return makeHourlyTrigger(intervalInHours,
                SimpleTrigger.REPEAT_INDEFINITELY);
    }

    /**
     * <p>
     * Make a trigger that will fire every N hours, with the given number of
     * repeats.
     * </p>
     * 
     * <p>
     * The generated trigger will still need to have its name, group,
     * start-time and end-time set.
     * </p>
     * 
     * @param intervalInHours
     *          the number of hours between firings
     * @param repeatCount
     *          the number of times to repeat the firing
     */
    public static Trigger makeHourlyTrigger(int intervalInHours, int repeatCount) {
        SimpleTrigger trig = new SimpleTrigger();

        trig.setRepeatInterval(intervalInHours * MILLISECONDS_IN_HOUR);
        trig.setRepeatCount(repeatCount);

        return trig;
    }

    /**
     * <p>
     * Returns a date that is rounded to the next even hour above the given
     * date.
     * </p>
     * 
     * <p>
     * For example an input date with a time of 08:13:54 would result in a date
     * with the time of 09:00:00. If the date's time is in the 23rd hour, the
     * date's 'day' will be promoted, and the time will be set to 00:00:00.
     * </p>
     * 
     * @param date
     *          the Date to round, if <code>null</code> the current time will
     *          be used
     */
    public static Date getEvenHourDate(Date date) {
        if (date == null) date = new Date();

        Calendar c = Calendar.getInstance();
        c.setTime(date);
        c.setLenient(true);

        c.set(Calendar.HOUR_OF_DAY, c.get(Calendar.HOUR_OF_DAY) + 1);
        c.set(Calendar.MINUTE, 0);
        c.set(Calendar.SECOND, 0);
        c.set(Calendar.MILLISECOND, 0);

        return c.getTime();
    }

    /**
     * <p>
     * Returns a date that is rounded to the previous even hour below the given
     * date.
     * </p>
     * 
     * <p>
     * For example an input date with a time of 08:13:54 would result in a date
     * with the time of 08:00:00.
     * </p>
     * 
     * @param date
     *          the Date to round, if <code>null</code> the current time will
     *          be used
     */
    public static Date getEvenHourDateBefore(Date date) {
        if (date == null) date = new Date();

        Calendar c = Calendar.getInstance();
        c.setTime(date);