Home » quartz-1.6.0 » org » quartz » [javadoc | source]

    1   
    2   /* 
    3    * Copyright 2004-2005 OpenSymphony 
    4    * 
    5    * Licensed under the Apache License, Version 2.0 (the "License"); you may not 
    6    * use this file except in compliance with the License. You may obtain a copy 
    7    * of the License at 
    8    * 
    9    *   http://www.apache.org/licenses/LICENSE-2.0 
   10    *   
   11    * Unless required by applicable law or agreed to in writing, software 
   12    * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 
   13    * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 
   14    * License for the specific language governing permissions and limitations 
   15    * under the License.
   16    * 
   17    */
   18   
   19   /*
   20    * Previously Copyright (c) 2001-2004 James House
   21    */
   22   package org.quartz;
   23   
   24   import java.util.Date;
   25   import java.util.HashMap;
   26   
   27   import org.quartz.spi.TriggerFiredBundle;
   28   
   29   /**
   30    * <p>
   31    * A context bundle containing handles to various environment information, that
   32    * is given to a <code>{@link org.quartz.JobDetail}</code> instance as it is
   33    * executed, and to a <code>{@link Trigger}</code> instance after the
   34    * execution completes.
   35    * </p>
   36    * 
   37    * <p>
   38    * The <code>JobDataMap</code> found on this object (via the 
   39    * <code>getMergedJobDataMap()</code> method) serves as a convenience -
   40    * it is a merge of the <code>JobDataMap</code> found on the 
   41    * <code>JobDetail</code> and the one found on the <code>Trigger</code>, with 
   42    * the value in the latter overriding any same-named values in the former.
   43    * <i>It is thus considered a 'best practice' that the execute code of a Job
   44    * retrieve data from the JobDataMap found on this object</i>  NOTE: Do not
   45    * expect value 'set' into this JobDataMap to somehow be set back onto a
   46    * <code>StatefulJob</code>'s own JobDataMap.
   47    * </p>
   48    * 
   49    * <p>
   50    * <code>JobExecutionContext</code> s are also returned from the 
   51    * <code>Scheduler.getCurrentlyExecutingJobs()</code>
   52    * method. These are the same instances as those passed into the jobs that are
   53    * currently executing within the scheduler. The exception to this is when your
   54    * application is using Quartz remotely (i.e. via RMI) - in which case you get
   55    * a clone of the <code>JobExecutionContext</code>s, and their references to
   56    * the <code>Scheduler</code> and <code>Job</code> instances have been lost (a
   57    * clone of the <code>JobDetail</code> is still available - just not a handle
   58    * to the job instance that is running).
   59    * </p>
   60    * 
   61    * @see #getJobDetail()
   62    * @see #getScheduler()
   63    * @see #getMergedJobDataMap()
   64    * 
   65    * @see Job
   66    * @see Trigger
   67    * @see JobDataMap
   68    * 
   69    * @author James House
   70    */
   71   public class JobExecutionContext implements java.io.Serializable {
   72   
   73       /*
   74        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   75        * 
   76        * Data members.
   77        * 
   78        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   79        */
   80   
   81       private transient Scheduler scheduler;
   82   
   83       private Trigger trigger;
   84   
   85       private JobDetail jobDetail;
   86       
   87       private JobDataMap jobDataMap;
   88   
   89       private transient Job job;
   90       
   91       private Calendar calendar;
   92   
   93       private boolean recovering = false;
   94   
   95       private int numRefires = 0;
   96   
   97       private Date fireTime;
   98   
   99       private Date scheduledFireTime;
  100   
  101       private Date prevFireTime;
  102   
  103       private Date nextFireTime;
  104       
  105       private long jobRunTime = -1;
  106       
  107       private Object result;
  108       
  109       private HashMap data = new HashMap();
  110   
  111       /*
  112        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  113        * 
  114        * Constructors.
  115        * 
  116        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  117        */
  118   
  119       /**
  120        * <p>
  121        * Create a JobExcecutionContext with the given context data.
  122        * </p>
  123        */
  124       public JobExecutionContext(Scheduler scheduler,
  125               TriggerFiredBundle firedBundle, Job job) {
  126           this.scheduler = scheduler;
  127           this.trigger = firedBundle.getTrigger();
  128           this.calendar = firedBundle.getCalendar();
  129           this.jobDetail = firedBundle.getJobDetail();
  130           this.job = job;
  131           this.recovering = firedBundle.isRecovering();
  132           this.fireTime = firedBundle.getFireTime();
  133           this.scheduledFireTime = firedBundle.getScheduledFireTime();
  134           this.prevFireTime = firedBundle.getPrevFireTime();
  135           this.nextFireTime = firedBundle.getNextFireTime();
  136           
  137           this.jobDataMap = new JobDataMap();
  138           this.jobDataMap.putAll(jobDetail.getJobDataMap());
  139           this.jobDataMap.putAll(trigger.getJobDataMap());
  140       }
  141   
  142       /*
  143        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  144        * 
  145        * Interface.
  146        * 
  147        * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  148        */
  149   
  150       /**
  151        * <p>
  152        * Get a handle to the <code>Scheduler</code> instance that fired the
  153        * <code>Job</code>.
  154        * </p>
  155        */
  156       public Scheduler getScheduler() {
  157           return scheduler;
  158       }
  159   
  160       /**
  161        * <p>
  162        * Get a handle to the <code>Trigger</code> instance that fired the
  163        * <code>Job</code>.
  164        * </p>
  165        */
  166       public Trigger getTrigger() {
  167           return trigger;
  168       }
  169   
  170       /**
  171        * <p>
  172        * Get a handle to the <code>Calendar</code> referenced by the <code>Trigger</code>
  173        * instance that fired the <code>Job</code>.
  174        * </p>
  175        */
  176       public Calendar getCalendar() {
  177           return calendar;
  178       }
  179   
  180       /**
  181        * <p>
  182        * If the <code>Job</code> is being re-executed because of a 'recovery'
  183        * situation, this method will return <code>true</code>.
  184        * </p>
  185        */
  186       public boolean isRecovering() {
  187           return recovering;
  188       }
  189   
  190       public void incrementRefireCount() {
  191           numRefires++;
  192       }
  193   
  194       public int getRefireCount() {
  195           return numRefires;
  196       }
  197   
  198       /**
  199        * <p>
  200        * Get the convenience <code>JobDataMap</code> of this execution context.
  201        * </p>
  202        * 
  203        * <p>
  204        * The <code>JobDataMap</code> found on this object serves as a convenience -
  205        * it is a merge of the <code>JobDataMap</code> found on the 
  206        * <code>JobDetail</code> and the one found on the <code>Trigger</code>, with 
  207        * the value in the latter overriding any same-named values in the former.
  208        * <i>It is thus considered a 'best practice' that the execute code of a Job
  209        * retrieve data from the JobDataMap found on this object</i>
  210        * </p>
  211        * 
  212        * <p>NOTE: Do not
  213        * expect value 'set' into this JobDataMap to somehow be set back onto a
  214        * <code>StatefulJob</code>'s own JobDataMap.
  215        * </p>
  216        * 
  217        * <p>
  218        * Attempts to change the contents of this map typically result in an 
  219        * <code>IllegalStateException</code>.
  220        * </p>
  221        * 
  222        */
  223       public JobDataMap getMergedJobDataMap() {
  224           return jobDataMap;
  225       }
  226   
  227       /**
  228        * <p>
  229        * Get the <code>JobDetail</code> associated with the <code>Job</code>.
  230        * </p>
  231        */
  232       public JobDetail getJobDetail() {
  233           return jobDetail;
  234       }
  235   
  236       /**
  237        * <p>
  238        * Get the instance of the <code>Job</code> that was created for this
  239        * execution.
  240        * </p>
  241        * 
  242        * <p>
  243        * Note: The Job instance is not available through remote scheduler
  244        * interfaces.
  245        * </p>
  246        */
  247       public Job getJobInstance() {
  248           return job;
  249       }
  250   
  251       /**
  252        * The actual time the trigger fired. For instance the scheduled time may
  253        * have been 10:00:00 but the actual fire time may have been 10:00:03 if
  254        * the scheduler was too busy.
  255        * 
  256        * @return Returns the fireTime.
  257        * @see #getScheduledFireTime()
  258        */
  259       public Date getFireTime() {
  260           return fireTime;
  261       }
  262   
  263       /**
  264        * The scheduled time the trigger fired for. For instance the scheduled
  265        * time may have been 10:00:00 but the actual fire time may have been
  266        * 10:00:03 if the scheduler was too busy.
  267        * 
  268        * @return Returns the scheduledFireTime.
  269        * @see #getFireTime()
  270        */
  271       public Date getScheduledFireTime() {
  272           return scheduledFireTime;
  273       }
  274   
  275       public Date getPreviousFireTime() {
  276           return prevFireTime;
  277       }
  278   
  279       public Date getNextFireTime() {
  280           return nextFireTime;
  281       }
  282   
  283       public String toString() {
  284           return "JobExecutionContext:" + " trigger: '"
  285                   + getTrigger().getFullName() + " job: "
  286                   + getJobDetail().getFullName() + " fireTime: '" + getFireTime()
  287                   + " scheduledFireTime: " + getScheduledFireTime()
  288                   + " previousFireTime: '" + getPreviousFireTime()
  289                   + " nextFireTime: " + getNextFireTime() + " isRecovering: "
  290                   + isRecovering() + " refireCount: " + getRefireCount();
  291       }
  292   
  293       /**
  294        * Returns the result (if any) that the <code>Job</code> set before its 
  295        * execution completed (the type of object set as the result is entirely up 
  296        * to the particular job).
  297        * 
  298        * <p>
  299        * The result itself is meaningless to Quartz, but may be informative
  300        * to <code>{@link JobListener}s</code> or 
  301        * <code>{@link TriggerListener}s</code> that are watching the job's 
  302        * execution.
  303        * </p> 
  304        * 
  305        * @return Returns the result.
  306        */
  307       public Object getResult() {
  308           return result;
  309       }
  310       
  311       /**
  312        * Set the result (if any) of the <code>Job</code>'s execution (the type of 
  313        * object set as the result is entirely up to the particular job).
  314        * 
  315        * <p>
  316        * The result itself is meaningless to Quartz, but may be informative
  317        * to <code>{@link JobListener}s</code> or 
  318        * <code>{@link TriggerListener}s</code> that are watching the job's 
  319        * execution.
  320        * </p> 
  321        */
  322       public void setResult(Object result) {
  323           this.result = result;
  324       }
  325       
  326       /**
  327        * The amount of time the job ran for (in milliseconds).  The returned 
  328        * value will be -1 until the job has actually completed (or thrown an 
  329        * exception), and is therefore generally only useful to 
  330        * <code>JobListener</code>s and <code>TriggerListener</code>s.
  331        * 
  332        * @return Returns the jobRunTime.
  333        */
  334       public long getJobRunTime() {
  335           return jobRunTime;
  336       }
  337       
  338       /**
  339        * @param jobRunTime The jobRunTime to set.
  340        */
  341       public void setJobRunTime(long jobRunTime) {
  342           this.jobRunTime = jobRunTime;
  343       }
  344   
  345       /**
  346        * Put the specified value into the context's data map with the given key.
  347        * Possibly useful for sharing data between listeners and jobs.
  348        *
  349        * <p>NOTE: this data is volatile - it is lost after the job execution
  350        * completes, and all TriggerListeners and JobListeners have been 
  351        * notified.</p> 
  352        *  
  353        * @param key
  354        * @param value
  355        */
  356       public void put(Object key, Object value) {
  357           data.put(key, value);
  358       }
  359       
  360       /**
  361        * Get the value with the given key from the context's data map.
  362        * 
  363        * @param key
  364        */
  365       public Object get(Object key) {
  366           return data.get(key);
  367       }
  368   }

Home » quartz-1.6.0 » org » quartz » [javadoc | source]