javax.util.concurrent
Interface Trigger

public interface Trigger

Triggers allow application developers to plug in rules for when and how often a task should run. The trigger can be as simple as a single, absolute date-time or can include Java™ EE business calendar logic. A Trigger implementation is created by the application developer (or may be supplied to the application externally) and is registered with a task when it is submitted to a ManagedScheduledExecutorService using any of the schedule methods. Each method will run with the same context in which the task runs. The Trigger becomes a Contextual Task.

Each Trigger instance will be invoked within the same process in which it was registered.

Example:

   /**
    * A trigger that only returns a single date.
    */
    public class SingleDateTrigger implements Trigger {
        private Date fireTime;

        public TriggerSingleDate(Date newDate) {
            fireTime = newDate;
        }

        public Date getNextRunTime(
           Future lastFuture, Date baseTime, Date lastActualRunTime,
           Date lastScheduledRunTime, Date lastCompleteTime) {

           if(baseTime.after(fireTime)) {
               return null;
           }
           return fireTime;
        }

        public boolean skipRun(Future lastFuture, Date scheduledRunTime) {
            return scheduledRunTime.after(fireTime);
        }
    }

   /**
    * A fixed-rate trigger that will skip any runs if
    * the latencyAllowance threshold is exceeded (the task
    * ran too late).
    */
    public class TriggerFixedRateLatencySensitive implements Trigger {
        private Date startTime;
        private long delta;
        private long latencyAllowance;

        public TriggerFixedRateLatencySensitive(Date startTime, long delta, long latencyAllowance) {
            this.startTime = startTime;
            this.delta = delta;
            this.latencyAllowance = latencyAllowance;
        }

        public Date getNextRunTime(Future lastFuture, Date baseTime, Date lastActualRunTime, Date lastScheduledRunTime, Date lastCompleteTime) {
            if(lastActualRunTime==null) {
                return startTime;
            }
            return new Date(lastScheduledRunTime.getTime() + delta);
        }

        public boolean skipRun(Future lastFuture, Date scheduledRunTime) {
            return System.currentTimeMillis() - scheduledRunTime.getTime() > latencyAllowance;
        }
    }

 

Author:

Chris D. Johnson

Method Summary

java.util.Date	getNextRunTime(java.util.concurrent.Future lastFuture, java.util.Date baseTime, java.util.Date lastActualRunTime, java.util.Date lastScheduledRunTime, java.util.Date lastCompleteTime) Retrieve the next time that the task should run after.
boolean	skipRun(java.util.concurrent.Future lastFuture, java.util.Date scheduledRunTime) Return true if this run instance should be skipped.

Method Detail

getNextRunTime

java.util.Date getNextRunTime(java.util.concurrent.Future lastFuture,
                              java.util.Date baseTime,
                              java.util.Date lastActualRunTime,
                              java.util.Date lastScheduledRunTime,
                              java.util.Date lastCompleteTime)

Retrieve the next time that the task should run after.

Parameters:

lastFuture - the state of the Future after the last run. This value will be null if the task has not yet run.

baseTime - the time in which the next fire time should be based.

lastActualRunTime - the time in which the last task actually ran. This value will be null if the task has not yet run.

lastScheduledRunTime - the time in which the last task was scheduled to run. This value will be null if the task has not yet run.

lastCompleteTime - the time in which the last task completed. This value will be null if the task has not yet run.

Returns:

the date/time in which the next task iteration should execute on or after.

skipRun

boolean skipRun(java.util.concurrent.Future lastFuture,
                java.util.Date scheduledRunTime)

Return true if this run instance should be skipped.

This is useful if the task shouldn't run because it is late or if the task is paused or suspended.

Once this task is skipped, the state of it's Future's result will throw a SkippedException. Unchecked exceptions will be wrapped in a SkippedException.

Parameters:

scheduledRunTime - the date/time that the task was originally scheduled to run.

Returns:

true if the task should be skipped and rescheduled.