Module jakarta.concurrency

Package jakarta.enterprise.concurrent

Annotation Interface Schedule

@Documented
@Retention(RUNTIME)
@Target({ANNOTATION_TYPE,METHOD})
public @interface Schedule

Defines a schedule that indicates when to run a method.

For the scheduled asychronous method to aim to run at a given day and time, all of the criteria specified by the Schedule must match or be disregarded according to the rules of each field.

Scheduled methods

When the Schedule annotation is applied to a CDI managed bean method, the schedule defines the times after which to run the method. The method must have a void return type and no parameters. The bean must not be a Jakarta Enterprise Bean.

Upon starting the application, the Jakarta EE Product Provider computes the next time from the Schedule annotation and schedules a task that aims to run at the computed time on the default ManagedScheduledExecutorService. After it is time to run the task, the task first checks to ensure that the schedule does not require skipping the invocation of the method. If method invocation is not skipped, the task obtains an instance of the bean and invokes the method on the bean instance.

After successful or skipped invocation of the method, the task uses the Schedule annotation to compute the next time. The computed next time is after the method completion time or the time of the skip. The task schedules another task that aims to run after the computed next time. This continues with each invocation of the method until an invocation of the method raises an exception or error or the application stops.

For example,

  @Schedule(daysOfWeek = { DayOfWeek.SATURDAY, DayOfWeek.SUNDAY },
            hours = 8,
            minutes = 30,
            zone = "America/Chicago")
  public void weekendsAtEightThirtyAM() {
      System.out.println("Good morning. Today is " + ZonedDateTime.now());
  }
 

Asynchronous methods with a Schedule

When the Schedule annotation is used as a value of Asynchronous.runAt(), the schedule defines the times after which to run the asynchronous method.

Asynchronous methods with a Schedule annotation can be written to schedule automatically at application startup by observing the application's jakarta.enterprise.Startup event. For example,

  @Asynchronous(runAt = @Schedule(cron = "30 8 * * SAT,SUN",
                                  zone = "America/Chicago"))
  public void weekendsAtEightThirtyAM(@Observes Startup event) {
      System.out.println("Good morning. Today is " + ZonedDateTime.now());
  }
 

Or, asynchronous methods can be written to require invocation in order to apply the schedule. For example,

  @Asynchronous(runAt = @Schedule(cron = "30 6 * * MON-FRI",
                                  zone = "America/Chicago"))
  public void weekdaysAtSixThirtyAM(String message) {
      System.out.println(message + " Today is " + ZonedDateTime.now());
  }
 

The above method does not run even if a scheduled time is reached until the application manually requests to schedule it by invoking the method,

  if (decidedToScheduleDailyMessage) {
      bean.weekdaysAtSixThirtyAM("Good morning!");
  }
 

Since:

3.1

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	cron	Cron expression following the rules of CronTrigger.
int[]	daysOfMonth	Days of the month on which the asynchronous method aims to run.
DayOfWeek[]	daysOfWeek	Days of the week on which the asynchronous method aims to run.
int[]	hours	Hours of the day at which the asynchronous method aims to run.
int[]	minutes	Minutes at which the asynchronous method aims to run.
Month[]	months	Months in which the asynchronous method aims to run.
int[]	seconds	Seconds at which the asynchronous method aims to run.
long	skipIfLateBy	Seconds after which an execution that is late to start should be skipped rather than starting it late.
String	zone	Time zone id, such as America/Chicago or America/Los_Angeles, which identifies the time zone of the schedule.

Element Details

cron

String cron

Cron expression following the rules of CronTrigger.

When a non-empty value is specified, it overrides all values that are specified for months(), daysOfMonth(), daysOfWeek(), hours(), minutes(), and seconds().

The default value is the empty string, indicating that no cron expression is to be used.

Returns:

cron expression indicating when to run the asynchronous method.

Default:

""

months

Month[] months

Months in which the asynchronous method aims to run.

The default value is an empty list, which means that the month is not included in the criteria for deciding when to run the asynchronous method.

Returns:

list of months in which the asynchronous method aims to run; An empty list disregards the month.

Default:

{}

daysOfMonth

int[] daysOfMonth

Days of the month on which the asynchronous method aims to run. Values can range from 1 to 31.

The default value is an empty list, which means that the day of the month is not included in the criteria for deciding when to run the asynchronous method.

Returns:

list of days of the month on which the asynchronous method aims to run; An empty list disregards the day of the month.

Default:

{}

daysOfWeek

DayOfWeek[] daysOfWeek

Days of the week on which the asynchronous method aims to run.

The default value is an empty list, which means that the day of the week is not included in the criteria for deciding when to run the asynchronous method.

Returns:

list of days of the week on which the asynchronous method aims to run; An empty list disregards the day of the week.

Default:

{}

hours

int[] hours

Hours of the day at which the asynchronous method aims to run.

Values can range from 0 to 23. A value of empty list indicates that the hour is not included in the criteria for deciding when to run the asynchronous method.

The default value is 0 (midnight).

Returns:

list of hours at which the asynchronous method aims to run; An empty list disregards the hour.

Default:

{0}

minutes

int[] minutes

Minutes at which the asynchronous method aims to run.

Values can range from 0 to 59. A value of empty list indicates that the minute is not included in the criteria for deciding when to run the asynchronous method.

The default value is 0 (at the start of the hour).

Returns:

list of minutes at which the asynchronous method aims to run; An empty list disregards the minutes.

Default:

{0}

seconds

int[] seconds

Seconds at which the asynchronous method aims to run.

Values can range from 0 to 59. A value of empty list causes the asynchronous method to raise IllegalArgumentException.

The default value is 0 (at the start of the minute).

Returns:

list of seconds at which the asynchronous method aims to run.

Default:

{0}

skipIfLateBy

long skipIfLateBy

Seconds after which an execution that is late to start should be skipped rather than starting it late.

Values must be greater than 0. The default value is 600 seconds (10 minutes). This differs from executions that are missed due to overlap, which are always skipped.

Returns:

the threshold for skipping executions that are late to start.

Default:

600L

zone

String zone

Time zone id, such as America/Chicago or America/Los_Angeles, which identifies the time zone of the schedule.

The default value of empty string indicates to use the default time zone for the system.

Default:

""