* </td>
 * </tr>
 * <tr>
 * <td align="left"><code>"0 15 10 ? * 6L 2002-2005"</code></td>
 * <td align="left">&nbsp;</td>
 * <td align="left"><code>Fire at 10:15am on every last friday of every month during the years 2002, 2003, 2004 and 2005</code>
 * </td>
 * </tr>
 * <tr>
 * <td align="left"><code>"0 15 10 ? * 6#3"</code></td>
 * <td align="left">&nbsp;</td>
 * <td align="left"><code>Fire at 10:15am on the third Friday of every month</code>
 * </td>
 * </tr>
 * </table>
 * </p>
 * 
 * <p>
 * Pay attention to the effects of '?' and '*' in the day-of-week and
 * day-of-month fields!
 * </p>
 * 
 * <p>
 * <b>NOTES:</b>
 * <ul>
 * <li>Support for the features described for the 'C' character is not
 * complete.</li>
 * <li>Support for specifying both a day-of-week and a day-of-month value is
 * not complete (you'll need to use the '?' character in on of these fields).
 * </li>
 * <li>Be careful when setting fire times between mid-night and 1:00 AM -
 * "daylight savings" can cause a skip or a repeat depending on whether the
 * time moves back or jumps forward.</li>
 * </ul>
 * </p>
 * 
 *
 * @author Alexander Kandzior 
 * 
 * @version $Revision: 1.19 $ 
 * 
 * @since 6.0.0 
 */
public class CmsScheduledJobInfo implements I_CmsConfigurationParameterHandler {

    /** The log object for this class. */
    private static final Log LOG = CmsLog.getLog(CmsScheduledJobInfo.class);

    /** Indicates if this job is currently active in the scheduler or not. */
    private boolean m_active;

    /** The name of the class to schedule. */
    private String m_className;

    /** The context information for the user to execute the job with. */
    private CmsContextInfo m_context;

    /** The cron expression for this scheduler job. */
    private String m_cronExpression;

    /** Indicates if the configuration of this job is finalized (frozen). */
    private boolean m_frozen;

    /** The id of this job. */
    private String m_id;

    /** Instance object of the scheduled job (only required when instance is re-used). */
    private I_CmsScheduledJob m_jobInstance;

    /** The name of the job (for information purposes). */
    private String m_jobName;

    /** The parameters used for this job entry. */
    private SortedMap m_parameters;

    /** Indicates if the job instance should be re-used if the job is run. */
    private boolean m_reuseInstance;

    /** The (cron) trigger used for scheduling this job. */
    private Trigger m_trigger;

    /**
     * Default constructor.<p>
     */
    public CmsScheduledJobInfo() {

        m_reuseInstance = false;
        m_frozen = false;
        // parameters are stored in a tree map 
        m_parameters = new TreeMap();
        // a job is active by default
        m_active = true;
    }

    /**
     * Constructor for creating a new job with all required parameters.<p> 
     * 
     * @param id the id of the job of <code>null</code> if a new id should be automatically generated
     * @param jobName the display name of the job 
     * @param className the class name of the job, must be an instance of <code>{@link I_CmsScheduledJob}</code>
     * @param context the OpenCms user context information to use when executing the job
     * @param cronExpression the cron expression for scheduling the job
     * @param reuseInstance indicates if the job class should be re-used
     * @param active indicates if the job should be active in the scheduler
     * @param parameters the job parameters
     */
    public CmsScheduledJobInfo(
        String id,
        String jobName,
        String className,
        CmsContextInfo context,
        String cronExpression,
        boolean reuseInstance,
        boolean active,
        SortedMap parameters) {

        m_frozen = false;
        setId(id);
        if (CmsStringUtil.isNotEmpty(jobName)) {
            // job name is optional, if not present class name will be used
            setJobName(jobName);
        }
        setClassName(className);
        setContextInfo(context);
        setCronExpression(cronExpression);
        setReuseInstance(reuseInstance);
        setActive(active);
        setParameters(parameters);
    }

    /**
     * @see org.opencms.configuration.I_CmsConfigurationParameterHandler#addConfigurationParameter(java.lang.String, java.lang.String)
     */
    public void addConfigurationParameter(String paramName, String paramValue) {

        checkFrozen();
        // add the configured parameter
        m_parameters.put(paramName, paramValue);
        if (LOG.isDebugEnabled()) {
            LOG.debug(org.opencms.configuration.Messages.get().getBundle().key(
                org.opencms.configuration.Messages.LOG_ADD_CONFIG_PARAM_3,
                paramName,
                paramValue,
                this));
        }
    }

    /**
     * Clears the id of the job.<p>
     * 
     * This is useful if you want to create a copy of a job without keeping the job id.
     * Use <code>{@link CmsScheduledJobInfo#clone()}</code> first to create the copy,
     * and then clear the id of the clone.<p>
     */
    public void clearId() {

        setId(null);
    }

    /**
     * Creates a clone of this scheduled job.<p>
     * 
     * The clone will not be active in the scheduler until it is scheduled
     * with <code>{@link CmsScheduleManager#scheduleJob(org.opencms.file.CmsObject, CmsScheduledJobInfo)}</code>. 
     * The job id returned by <code>{@link #getId()}</code> will be the same.
     * The <code>{@link #isActive()}</code> flag will be set to false. 
     * The clones job instance class will be the same 
     * if the <code>{@link #isReuseInstance()}</code> flag is set.<p>
     * 
     * @see java.lang.Object#clone()
     */
    public Object clone() {

        CmsScheduledJobInfo result = new CmsScheduledJobInfo();

        result.m_id = m_id;
        result.m_active = false;
        result.m_frozen = false;
        result.m_className = m_className;
        if (isReuseInstance()) {
            result.m_jobInstance = m_jobInstance;
        }
        result.m_reuseInstance = m_reuseInstance;
        result.m_context = (CmsContextInfo)m_context.clone();
        result.m_cronExpression = m_cronExpression;
        result.m_jobName = m_jobName;
        result.m_parameters = new TreeMap(m_parameters);
        result.m_trigger = null;

        return result;
    }

    /**
     * Returns the name of the class to schedule.<p>
     * 
     * @return the name of the class to schedule
     */
    public String getClassName() {

        return m_className;
    }

    /**
     * @see org.opencms.configuration.I_CmsConfigurationParameterHandler#getConfiguration()
     */
    public Map getConfiguration() {

        // this configuration does not support parameters
        if (LOG.isDebugEnabled()) {
            LOG.debug(org.opencms.configuration.Messages.get().getBundle().key(
                org.opencms.configuration.Messages.LOG_GET_CONFIGURATION_1,
                this));
        }
        return getParameters();
    }

    /**
     * Returns the context information for the user executing the job.<p>
     *
     * @return the context information for the user executing the job
     */
    public CmsContextInfo getContextInfo() {

        return m_context;
    }

    /**
     * Returns the cron expression for this job entry.<p>
     * 
     * @return the cron expression for this job entry
     */
    public String getCronExpression() {

        return m_cronExpression;
    }

    /**
     * Returns the next time at which this job will be executed, after the given time.<p>
     * 
     * If this job will not be executed after the given time, <code>null</code> will be returned..<p>
     * 
     * @param date the after which the next execution time should be calculated
     * @return the next time at which this job will be executed, after the given time
     */
    public Date getExecutionTimeAfter(Date date) {

        if (!m_active || (m_trigger == null)) {
            // if the job is not active, no time can be calculated
            return null;
        }

        return m_trigger.getFireTimeAfter(date);
    }

    /**
     * Returns the next time at which this job will be executed.<p> 
     * 
     * If the job will not execute again, <code>null</code> will be returned.<p>
     * 
     * @return the next time at which this job will be executed
     */
    public Date getExecutionTimeNext() {

        if (!m_active || (m_trigger == null)) {
            // if the job is not active, no time can be calculated
            return null;
        }

        return m_trigger.getNextFireTime();
    }

    /**
     * Returns the previous time at which this job will be executed.<p>
     * 
     * If this job has not yet been executed, <code>null</code> will be returned.
     * 
     * @return the previous time at which this job will be executed
     */
    public Date getExecutionTimePrevious() {

        if (!m_active || (m_trigger == null)) {
            // if the job is not active, no time can be calculated
            return null;
        }

        return m_trigger.getPreviousFireTime();
    }

    /**
     * Returns the internal id of this job in the scheduler.<p>
     * 
     * Can be used to remove this job from the scheduler with 
     * <code>{@link CmsScheduleManager#unscheduleJob(org.opencms.file.CmsObject, String)}</code>.<p> 
     * 
     * @return the internal id of this job in the scheduler
     */
    public String getId() {

        return m_id;
    }

    /**
     * Returns an instance of the configured job class.<p>
     * 
     * If any error occurs during class invocaion, the error 
     * is written to the OpenCms log and <code>null</code> is returned.<p>