org.quartz.JobExecutionContext Maven / Gradle / Ivy
/*
* 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 {@link org.quartz.JobDetail} instance as it is
* executed, and to a {@link Trigger} instance after the
* execution completes.
*
*
* The JobDataMap found on this object (via the
* getMergedJobDataMap() method) serves as a convenience -
* it is a merge of the JobDataMap found on the
* JobDetail and the one found on the Trigger, with
* the value in the latter overriding any same-named values in the former.
* It is thus considered a 'best practice' that the execute code of a Job
* retrieve data from the JobDataMap found on this object 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
* @PersistJobDataAfterExecution annotation.
*
*
*
* JobExecutionContext s are also returned from the
* Scheduler.getCurrentlyExecutingJobs()
* 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 JobExecutionContexts, and their references to
* the Scheduler and Job instances have been lost (a
* clone of the JobDetail is still available - just not a handle
* to the job instance that is running).
*
*
* @see #getScheduler()
* @see #getMergedJobDataMap()
* @see #getJobDetail()
*
* @see Job
* @see Trigger
* @see JobDataMap
*
* @author James House
*/
public interface JobExecutionContext {
/**
*
* Get a handle to the Scheduler instance that fired the
* Job.
*
*/
public Scheduler getScheduler();
/**
*
* Get a handle to the Trigger instance that fired the
* Job.
*
*/
public Trigger getTrigger();
/**
*
* Get a handle to the Calendar referenced by the Trigger
* instance that fired the Job.
*
*/
public Calendar getCalendar();
/**
*
* If the Job is being re-executed because of a 'recovery'
* situation, this method will return true.
*
*/
public boolean isRecovering();
/**
* Return the {@code TriggerKey} of the originally scheduled and now recovering job.
*
* 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();
/**
*
* Get the convenience JobDataMap of this execution context.
*
*
*
* The JobDataMap found on this object serves as a convenience -
* it is a merge of the JobDataMap found on the
* JobDetail and the one found on the Trigger, with
* the value in the latter overriding any same-named values in the former.
* It is thus considered a 'best practice' that the execute code of a Job
* retrieve data from the JobDataMap found on this object.
*
*
* 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
* @PersistJobDataAfterExecution annotation.
*
*
*
* Attempts to change the contents of this map typically result in an
* IllegalStateException.
*
*
*/
public JobDataMap getMergedJobDataMap();
/**
*
* Get the JobDetail associated with the Job.
*
*/
public JobDetail getJobDetail();
/**
*
* Get the instance of the Job that was created for this
* execution.
*
*
*
* Note: The Job instance is not available through remote scheduler
* interfaces.
*
*/
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 Job set before its
* execution completed (the type of object set as the result is entirely up
* to the particular job).
*
*
* The result itself is meaningless to Quartz, but may be informative
* to {@link JobListener}s or
* {@link TriggerListener}s that are watching the job's
* execution.
*
*
* @return Returns the result.
*/
public Object getResult();
/**
* Set the result (if any) of the Job's execution (the type of
* object set as the result is entirely up to the particular job).
*
*
* The result itself is meaningless to Quartz, but may be informative
* to {@link JobListener}s or
* {@link TriggerListener}s that are watching the job's
* execution.
*
*/
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
* JobListeners and TriggerListeners.
*
* @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.
*
* NOTE: this data is volatile - it is lost after the job execution
* completes, and all TriggerListeners and JobListeners have been
* notified.
*
* @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);
}