/*
* All content copyright Terracotta, Inc., unless otherwise indicated. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy
* of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
*/
package org.quartz;
import java.util.Date;
/**
* A context bundle containing handles to various environment information, that
* is given to a <code>{@link org.quartz.JobDetail}</code> instance as it is
* executed, and to a <code>{@link Trigger}</code> instance after the
* execution completes.
*
* <p>
* The <code>JobDataMap</code> found on this object (via the
* <code>getMergedJobDataMap()</code> method) serves as a convenience -
* it is a merge of the <code>JobDataMap</code> found on the
* <code>JobDetail</code> and the one found on the <code>Trigger</code>, with
* the value in the latter overriding any same-named values in the former.
* <i>It is thus considered a 'best practice' that the execute code of a Job
* retrieve data from the JobDataMap found on this object</i> NOTE: Do not
* expect value 'set' into this JobDataMap to somehow be set back onto a
* job's own JobDataMap - even if it has the
* <code>@PersistJobDataAfterExecution</code> annotation.
* </p>
*
* <p>
* <code>JobExecutionContext</code> s are also returned from the
* <code>Scheduler.getCurrentlyExecutingJobs()</code>
* method. These are the same instances as those passed into the jobs that are
* currently executing within the scheduler. The exception to this is when your
* application is using Quartz remotely (i.e. via RMI) - in which case you get
* a clone of the <code>JobExecutionContext</code>s, and their references to
* the <code>Scheduler</code> and <code>Job</code> instances have been lost (a
* clone of the <code>JobDetail</code> is still available - just not a handle
* to the job instance that is running).
* </p>
*
* @see #getScheduler()
* @see #getMergedJobDataMap()
* @see #getJobDetail()
*
* @see Job
* @see Trigger
* @see JobDataMap
*
* @author James House
*/
public interface JobExecutionContext {
/**
* <p>
* Get a handle to the <code>Scheduler</code> instance that fired the
* <code>Job</code>.
* </p>
*/
public Scheduler getScheduler();
/**
* <p>
* Get a handle to the <code>Trigger</code> instance that fired the
* <code>Job</code>.
* </p>
*/
public Trigger getTrigger();
/**
* <p>
* Get a handle to the <code>Calendar</code> referenced by the <code>Trigger</code>
* instance that fired the <code>Job</code>.
* </p>
*/
public Calendar getCalendar();
/**
* <p>
* If the <code>Job</code> is being re-executed because of a 'recovery'
* situation, this method will return <code>true</code>.
* </p>
*/
public boolean isRecovering();
/**
* Return the {@code TriggerKey} of the originally scheduled and now recovering job.
* <p>
* When recovering a previously failed job execution this method returns the identity
* of the originally firing trigger. This recovering job will have been scheduled for
* the same firing time as the original job, and so is available via the
* {@link #getScheduledFireTime()} method. The original firing time of the job can be
* accessed via the {@link Scheduler#FAILED_JOB_ORIGINAL_TRIGGER_FIRETIME_IN_MILLISECONDS}
* element of this job's {@code JobDataMap}.
*
* @return the recovering trigger details
* @throws IllegalStateException if this is not a recovering job.
*/
public TriggerKey getRecoveringTriggerKey() throws IllegalStateException;
public int getRefireCount();
/**
* <p>
* Get the convenience <code>JobDataMap</code> of this execution context.
* </p>
*
* <p>
* The <code>JobDataMap</code> found on this object serves as a convenience -
* it is a merge of the <code>JobDataMap</code> found on the
* <code>JobDetail</code> and the one found on the <code>Trigger</code>, with
* the value in the latter overriding any same-named values in the former.
* <i>It is thus considered a 'best practice' that the execute code of a Job
* retrieve data from the JobDataMap found on this object.</i>
* </p>
*
* <p>NOTE: Do not expect value 'set' into this JobDataMap to somehow be set
* or persisted back onto a job's own JobDataMap - even if it has the
* <code>@PersistJobDataAfterExecution</code> annotation.
* </p>
*
* <p>
* Attempts to change the contents of this map typically result in an
* <code>IllegalStateException</code>.
* </p>
*
*/
public JobDataMap getMergedJobDataMap();
/**
* <p>
* Get the <code>JobDetail</code> associated with the <code>Job</code>.
* </p>
*/
public JobDetail getJobDetail();
/**
* <p>
* Get the instance of the <code>Job</code> that was created for this
* execution.
* </p>
*
* <p>
* Note: The Job instance is not available through remote scheduler
* interfaces.
* </p>
*/
public Job getJobInstance();
/**
* The actual time the trigger fired. For instance the scheduled time may
* have been 10:00:00 but the actual fire time may have been 10:00:03 if
* the scheduler was too busy.
*
* @return Returns the fireTime.
* @see #getScheduledFireTime()
*/
public Date getFireTime();
/**
* The scheduled time the trigger fired for. For instance the scheduled
* time may have been 10:00:00 but the actual fire time may have been
* 10:00:03 if the scheduler was too busy.
*
* @return Returns the scheduledFireTime.
* @see #getFireTime()
*/
public Date getScheduledFireTime();
public Date getPreviousFireTime();
public Date getNextFireTime();
/**
* Get the unique Id that identifies this particular firing instance of the
* trigger that triggered this job execution. It is unique to this
* JobExecutionContext instance as well.
*
* @return the unique fire instance id
* @see Scheduler#interrupt(String)
*/
public String getFireInstanceId();
/**
* Returns the result (if any) that the <code>Job</code> set before its
* execution completed (the type of object set as the result is entirely up
* to the particular job).
*
* <p>
* The result itself is meaningless to Quartz, but may be informative
* to <code>{@link JobListener}s</code> or
* <code>{@link TriggerListener}s</code> that are watching the job's
* execution.
* </p>
*
* @return Returns the result.
*/
public Object getResult();
/**
* Set the result (if any) of the <code>Job</code>'s execution (the type of
* object set as the result is entirely up to the particular job).
*
* <p>
* The result itself is meaningless to Quartz, but may be informative
* to <code>{@link JobListener}s</code> or
* <code>{@link TriggerListener}s</code> that are watching the job's
* execution.
* </p>
*/
public void setResult(Object result);
/**
* The amount of time the job ran for (in milliseconds). The returned
* value will be -1 until the job has actually completed (or thrown an
* exception), and is therefore generally only useful to
* <code>JobListener</code>s and <code>TriggerListener</code>s.
*
* @return Returns the jobRunTime.
*/
public long getJobRunTime();
/**
* Put the specified value into the context's data map with the given key.
* Possibly useful for sharing data between listeners and jobs.
*
* <p>NOTE: this data is volatile - it is lost after the job execution
* completes, and all TriggerListeners and JobListeners have been
* notified.</p>
*
* @param key the key for the associated value
* @param value the value to store
*/
public void put(Object key, Object value);
/**
* Get the value with the given key from the context's data map.
*
* @param key the key for the desired value
*/
public Object get(Object key);
}