Package jakarta.enterprise.concurrent

Interface ZonedTrigger

  • All Superinterfaces:
    Trigger
    All Known Implementing Classes:
    CronTrigger
    public interface ZonedTrigger
extends 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 runs on the hour, Mon-Fri from 8am-8pm Central US time.
  */
  public class HourlyDuringBusinessHoursTrigger implements ZonedTrigger {
      static final ZoneId ZONE = ZoneId.of("America/Chicago");

      public ZoneId getZoneId() {
          return ZONE;
      }

      public ZonedDateTime getNextRunTime(LastExecution lastExec, ZonedDateTime taskScheduledTime) {
          ZonedDateTime prevTime = lastExec == null ? taskScheduledTime : lastExec.getRunEnd(ZONE);
          ZonedDateTime nextTime = prevTime.truncatedTo(ChronoUnit.HOURS).plusHours(1);
          DayOfWeek day = nextTime.getDayOfWeek();
          if (day.equals(DayOfWeek.SATURDAY) || day.equals(DayOfWeek.SUNDAY)) {
              nextTime = nextTime.truncatedTo(ChronoUnit.DAYS).plusDays(1).withHour(8);
          } else { // Mon-Fri 8am-8pm
              int hour = nextTime.getHour();
              if (hour< 8)
                  nextTime = nextTime.plusHours(8 - hour);
              else if (hour> 20)
                  nextTime = nextTime.truncatedTo(ChronoUnit.DAYS)
                                     .plusDays(day.equals(DayOfWeek.FRIDAY) ? 3 : 1)
                                     .withHour(8);
          }
          return nextTime;
      }
  }

    Since:
    3.0

    • Method Detail

      • getNextRunTime

        ZonedDateTime getNextRunTime​(LastExecution lastExecutionInfo,
                             ZonedDateTime 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 at which the ManagedScheduledExecutorService.schedule method was invoked to schedule the task.
        Returns:
        the date/time after which the next execution of the task should start.

      • getNextRunTime

        default Date getNextRunTime​(LastExecution lastExecutionInfo,
                            Date taskScheduledTime)
        Retrieve the next time that the task should run after.

        This method is provided to maintain compatibility with Trigger and should not be implemented. The default implementation delegates to the method signature that accepts and returns ZonedDateTime.

        Specified by:
        getNextRunTime in interface Trigger
        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 at which the ManagedScheduledExecutorService.schedule method was invoked to schedule the task.
        Returns:
        the date/time after which the next execution of the task should start.
        Throws:
        IllegalArgumentException - if the next run time is too large to represent as a Date.

      • getZoneId

        default ZoneId getZoneId()
        Returns the timezone to use for the ZonedDateTime that is supplied to the getNextRunTime and skipRun methods.

        The default implementation returns the system default timezone and should be overridden whenever there is chance that the server might not be running with the same timezone for which the business logic within this trigger is written.

        Returns:
        timezone to use for operations on this trigger.

      • skipRun

        default boolean skipRun​(LastExecution lastExecutionInfo,
                        ZonedDateTime 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 its Future's result will throw a SkippedException. Unchecked exceptions will be wrapped in a SkippedException.

        The default implementation returns false, making it optional to implement this method if you do not require support for skipped executions.

        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 after which the execution of the task is scheduled to start.
        Returns:
        true if the task should be skipped and rescheduled.

      • skipRun

        default boolean skipRun​(LastExecution lastExecutionInfo,
                        Date scheduledRunTime)
        Return true if this run instance should be skipped.

        This method is provided to maintain compatibility with Trigger and should not be implemented. The default implementation delegates to the method signature that accepts ZonedDateTime.

        Specified by:
        skipRun in interface Trigger
        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 after which the execution of the task is scheduled to start.
        Returns:
        true if the task should be skipped and rescheduled.