jakarta.enterprise.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 Jakarta™ 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 unspecified context. The methods can be made contextual through creating contextual proxy objects using ContextService.

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(
         LastExecution lastExecutionInfo, Date taskScheduledTime) {
         
         if(taskScheduledTime.after(fireTime)) {
             return null;
         }
         return fireTime;
      }

      public boolean skipRun(LastExecution lastExecutionInfo, 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(LastExecution lastExecutionInfo, 
                                 Date taskScheduledTime) {
          if(lastExecutionInfo==null) {
              return startTime;
          }
          return new Date(lastExecutionInfo.getScheduledStart().getTime() + delta);
      }

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

 

Since:

1.0

Method Summary

Modifier and Type	Method and Description
Date	getNextRunTime(LastExecution lastExecutionInfo, Date taskScheduledTime) Retrieve the next time that the task should run after.
boolean	skipRun(LastExecution lastExecutionInfo, Date scheduledRunTime) Return true if this run instance should be skipped.

Method Detail

getNextRunTime

Date getNextRunTime(LastExecution lastExecutionInfo,
                    Date taskScheduledTime)

Retrieve the next time that the task should run after.

Parameters:

lastExecutionInfo - information about the last execution of the task. This value will be null if the task has not yet run.

taskScheduledTime - the date/time in which the task was scheduled using the ManagedScheduledExecutorService.schedule method.

Returns:

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

skipRun

boolean skipRun(LastExecution lastExecutionInfo,
                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:

lastExecutionInfo - information about the last execution of the task. This value will be null if the task has not yet run.

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

Returns:

true if the task should be skipped and rescheduled.