trigger.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;

import java.util.Date;
import java.util.LinkedList;

/**
 * <p>
 * The base abstract class to be extended by all <code>Trigger</code>s.
 * </p>
 * 
 * <p>
 * <code>Triggers</code> s have a name and group associated with them, which
 * should uniquely identify them within a single <code>{@link Scheduler}</code>.
 * </p>
 * 
 * <p>
 * <code>Trigger</code> s are the 'mechanism' by which <code>Job</code> s
 * are scheduled. Many <code>Trigger</code> s can point to the same <code>Job</code>,
 * but a single <code>Trigger</code> can only point to one <code>Job</code>.
 * </p>
 * 
 * @see SimpleTrigger
 * @see CronTrigger
 * 
 * @author James House
 * @author Sharada Jambula
 */
public abstract class Trigger implements java.io.Serializable, Cloneable,
        Comparable {

    private static final long serialVersionUID = -3904243490805975570L;
    
    /*
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     * 
     * Constants.
     * 
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     */

    /**
     * <p>
     * Instructs the <code>{@link Scheduler}</code> that the <code>{@link Trigger}</code>
     * has no further instructions.
     * </p>
     */
    public static final int INSTRUCTION_NOOP = 0;

    /**
     * <p>
     * Instructs the <code>{@link Scheduler}</code> that the <code>{@link Trigger}</code>
     * wants the <code>{@link org.quartz.JobDetail}</code> to re-execute
     * immediately. If not in a 'RECOVERING' or 'FAILED_OVER' situation, the
     * execution context will be re-used (giving the <code>Job</code> the
     * abilitiy to 'see' anything placed in the context by its last execution).
     * </p>
     */
    public static final int INSTRUCTION_RE_EXECUTE_JOB = 1;

    /**
     * <p>
     * Instructs the <code>{@link Scheduler}</code> that the <code>{@link Trigger}</code>
     * should be put in the <code>COMPLETE</code> state.
     * </p>
     */
    public static final int INSTRUCTION_SET_TRIGGER_COMPLETE = 2;

    /**
     * <p>
     * Instructs the <code>{@link Scheduler}</code> that the <code>{@link Trigger}</code>
     * wants itself deleted.
     * </p>
     */
    public static final int INSTRUCTION_DELETE_TRIGGER = 3;

    /**
     * <p>
     * Instructs the <code>{@link Scheduler}</code> that all <code>Trigger</code>
     * s referencing the same <code>{@link org.quartz.JobDetail}</code> as
     * this one should be put in the <code>COMPLETE</code> state.
     * </p>
     */
    public static final int INSTRUCTION_SET_ALL_JOB_TRIGGERS_COMPLETE = 4;

    /**
     * <p>
     * Instructs the <code>{@link Scheduler}</code> that upon a mis-fire
     * situation, the <code>updateAfterMisfire()</code> method will be called
     * on the <code>Trigger</code> to determine the mis-fire instruction.
     * </p>
     * 
     * <p>
     * In order to see if this instruction fits your needs, you should look at
     * the documentation for the <code>getSmartMisfirePolicy()</code> method
     * on the particular <code>Trigger</code> implementation you are using.
     * </p>
     */
    public static final int MISFIRE_INSTRUCTION_SMART_POLICY = 0;

    /**
     * <p>
     * Indicates that the <code>Trigger</code> is in the "normal" state.
     * </p>
     */
    public final static int STATE_NORMAL = 0;

    /**
     * <p>
     * Indicates that the <code>Trigger</code> is in the "paused" state.
     * </p>
     */
    public final static int STATE_PAUSED = 1;

    /**
     * <p>
     * Indicates that the <code>Trigger</code> is in the "complete" state.
     * </p>
     * 
     * <p>
     * "Complete" indicates that the trigger has not remaining fire-times in
     * its schedule.
     * </p>
     */
    public final static int STATE_COMPLETE = 2;

    /**
     * <p>
     * Indicates that the <code>Trigger</code> is in the "error" state.
     * </p>
     * 
     * <p>
     * A <code>Trigger</code> arrives at the error state when the scheduler
     * attempts to fire it, but cannot due to an error creating and executing
     * its related job. Most commonly this is due to the <code>Job</code>'s
     * class not existing in the classpath.
     * </p>
     * 
     * <p>
     * When the trigger is in the error state, the scheduler will make no
     * attempts to fire it.
     * </p>
     */
    public final static int STATE_ERROR = 3;


    /**
     * <p>
     * Indicates that the <code>Trigger</code> is in the "blocked" state.
     * </p>
     * 
     * <p>
     * A <code>Trigger</code> arrives at the blocked state when the job that
     * it is associated with is a <code>StatefulJob</code> and it is 
     * currently executing.
     * </p>
     *
     * @see StatefulJob 
     */
    public final static int STATE_BLOCKED = 4;

    /**
     * <p>
     * Indicates that the <code>Trigger</code> does not exist.
     * </p>
     */
    public final static int STATE_NONE = -1;

    /*
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     * 
     * Data members.
     * 
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     */

    private String name;

    private String group;

    private String jobName;

    private String jobGroup;

    private String description;

    private boolean volatility = false;

    private String calendarName = null;

    private String fireInstanceId = null;

    private int misfireInstruction = MISFIRE_INSTRUCTION_SMART_POLICY;

    private LinkedList triggerListeners = new LinkedList();

    /*
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     * 
     * Constructors.
     * 
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     */

    /**
     * <p>
     * Create a <code>Trigger</code> with no specified name, group, or <code>{@link org.quartz.JobDetail}</code>.
     * </p>
     * 
     * <p>
     * Note that the {@link #setName(String)},{@link #setGroup(String)}and
     * the {@link #setJobName(String)}and {@link #setJobGroup(String)}methods
     * must be called before the <code>Trigger</code> can be placed into a
     * {@link Scheduler}.
     * </p>
     */
    public Trigger() {
        // do nothing...
    }

    /**
     * <p>
     * Create a <code>Trigger</code> with the given name, and group.
     * </p>
     * 
     * <p>
     * Note that the {@link #setJobName(String)}and
     * {@link #setJobGroup(String)}methods must be called before the <code>Trigger</code>
     * can be placed into a {@link Scheduler}.
     * </p>
     * 
     * @exception IllegalArgumentException
     *              if name or group are null or empty.
     */
    public Trigger(String name, String group) {
        setName(name);
        setGroup(group);
    }

    /**
     * <p>
     * Create a <code>Trigger</code> with the given name, and group.
     * </p>
     * 
     * @exception IllegalArgumentException
     *              if name or group of the <code>Trigger</code> or <code>{@link org.quartz.JobDetail}</code>
     *              are null or empty.
     */
    public Trigger(String name, String group, String jobName, String jobGroup) {
        setName(name);
        setGroup(group);
        setJobName(jobName);
        setJobGroup(jobGroup);
    }

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

    /**
     * <p>
     * Get the name of this <code>Trigger</code>.
     * </p>
     */
    public String getName() {
        return name;
    }

    /**
     * <p>
     * Set the name of this <code>Trigger</code>.
     * </p>
     * 
     * @exception IllegalArgumentException
     *              if name is null or empty.
     */
    public void setName(String name) {
        if (name == null || name.trim().length() == 0)
                throw new IllegalArgumentException(
                        "Trigger name cannot be null or empty.");

        this.name = name;
    }

    /**
     * <p>
     * Get the group of this <code>Trigger</code>.
     * </p>
     */
    public String getGroup() {
        return group;
    }

    /**
     * <p>
     * Set the name of this <code>Trigger</code>.
     * </p>
     * 
     * @exception IllegalArgumentException
     *              if group is null or empty.
     */
    public void setGroup(String group) {
        if (group == null || group.trim().length() == 0)
                throw new IllegalArgumentException(
                        "Group name cannot be null or empty.");

        this.group = group;
    }

    /**
     * <p>
     * Get the name of the associated <code>{@link org.quartz.JobDetail}</code>.
     * </p>
     */
    public String getJobName() {
        return jobName;
    }

    /**
     * <p>
     * Set the name of the associated <code>{@link org.quartz.JobDetail}</code>.
     * </p>
     * 
     * @exception IllegalArgumentException
     *              if jobName is null or empty.
     */
    public void setJobName(String jobName) {
        if (jobName == null || jobName.trim().length() == 0)
                throw new IllegalArgumentException(
                        "Job name cannot be null or empty.");

        this.jobName = jobName;
    }

    /**
     * <p>
     * Get the name of the associated <code>{@link org.quartz.JobDetail}</code>'s
     * group.
     * </p>
     */
    public String getJobGroup() {
        return jobGroup;
    }

    /**
     * <p>
     * Set the name of the associated <code>{@link org.quartz.JobDetail}</code>'s
     * group.
     * </p>
     * 
     * @exception IllegalArgumentException
     *              if jobGroup is null or empty.
     */
    public void setJobGroup(String jobGroup) {
        if (jobGroup == null || jobGroup.trim().length() == 0)
                throw new IllegalArgumentException(
                        "Group name cannot be null or empty.");

        this.jobGroup = jobGroup;
    }

    /**
     * <p>
     * Returns the 'full name' of the <code>Trigger</code> in the format
     * "group.name".
     * </p>
     */
    public String getFullName() {
        return group + "." + name;
    }

    /**
     * <p>
     * Returns the 'full name' of the <code>Job</code> that the <code>Trigger</code>
     * points to, in the format "group.name".
     * </p>
     */
    public String getFullJobName() {
        return jobGroup + "." + jobName;
    }

    /**
     * <p>
     * Return the description given to the <code>Trigger</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>Trigger</code> instance - may be
     * useful for remembering/displaying the purpose of the trigger, though the
     * description has no meaning to Quartz.
     * </p>
     */
    public void setDescription(String description) {
        this.description = description;
    }

    /**
     * <p>