Merge pull request #407 from njr-11/98-empty-list-value-for-schedule-…

…fields-is-undefined

empty list value for Schedule fields is undefined

api/src/main/java/jakarta/enterprise/concurrent/Schedule.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023 Contributors to the Eclipse Foundation
+ * Copyright (c) 2023,2024 Contributors to the Eclipse Foundation
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -28,101 +28,116 @@
  * <p>Defines schedules for
  * {@link Asynchronous#runAt() scheduled asynchronous methods}.</p>
  *
+ * <p>For the scheduled asychronous method to aim to run at a given day and time,
+ * all of the criteria specified by the {@code Schedule} must match
+ * or be disregarded according to the rules of each field.</p>
+ *
  * @since 3.1
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.ANNOTATION_TYPE)
 public @interface Schedule {
     /**
-     * Cron expression following the rules of {@link CronTrigger}.
-     * When a non-empty value is specified, it overrides all values
+     * <p>Cron expression following the rules of {@link CronTrigger}.</p>
+     *
+     * <p>When a non-empty value is specified, it overrides all values
      * that are specified for
-     * month, dayOfMonth, dayOfWeek, hours, minutes, and seconds.
-     * The default value is the empty-string, indicating that
-     * no cron expression is to be used.
+     * {@link months}, {@link daysOfMonth}, {@link daysOfWeek},
+     * {@link hours}, {@link minutes}, and {@link seconds}.</p>
      *
-     * @return cron expression indicating when to run the task.
+     * <p>The default value is the empty string, indicating that
+     * no cron expression is to be used.</p>
+     *
+     * @return cron expression indicating when to run the asynchronous method.
      */
     String cron() default "";
 
     /**
-     * Months in which the task aims to runs.
-     * The default value is every month.
+     * <p>Months in which the asynchronous method aims to run.</p>
+     *
+     * <p>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.</p>
      *
-     * @return list of months in which the task aims to run.
+     * @return list of months in which the asynchronous method aims to run; An empty list disregards the month.
      */
-    Month[] months() default {
-        Month.JANUARY, Month.FEBRUARY, Month.MARCH,
-        Month.APRIL, Month.MAY, Month.JUNE,
-        Month.JULY, Month.AUGUST, Month.SEPTEMBER,
-        Month.OCTOBER, Month.NOVEMBER, Month.DECEMBER };
+    Month[] months() default {};
 
     /**
-     * Days of the month on which the task aims to runs. Values can range from 1 to 31.
-     * The default value is every day of the month.
+     * <p>Days of the month on which the asynchronous method aims to run. Values can range from 1 to 31.</p>
      *
-     * @return list of days of the month on which the task aims to run.
+     * <p>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.</p>
+     *
+     * @return list of days of the month on which the asynchronous method aims to run; An empty list disregards the day of the month.
      */
-    int[] daysOfMonth() default {
-        1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
-        11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
-        21, 22, 23, 24, 25, 26, 27, 28, 29, 30,
-        31
-    };
+    int[] daysOfMonth() default {};
 
     /**
-     * Days of the week on which the task aims to runs.
-     * The default value is every day of the week.
+     * <p>Days of the week on which the asynchronous method aims to run.</p>
+     *
+     * <p>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.</p>
      *
-     * @return list of days of the month on which the task aims to run.
+     * @return list of days of the week on which the asynchronous method aims to run; An empty list disregards the day of the week.
      */
-    DayOfWeek[] daysOfWeek() default {
-        DayOfWeek.SUNDAY, DayOfWeek.MONDAY, DayOfWeek.TUESDAY,
-        DayOfWeek.WEDNESDAY, DayOfWeek.THURSDAY, DayOfWeek.FRIDAY,
-        DayOfWeek.SATURDAY
-    };
+    DayOfWeek[] daysOfWeek() default {};
 
     /**
-     * Hours of the day at which the task aims to runs. Values can range from 0 to 23.
-     * The default value is 0 (midnight).
+     * <p>Hours of the day at which the asynchronous method aims to run.</p>
+     *
+     * <p>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.</p>
      *
-     * @return list of hours at which the task aims to run.
+     * <p>The default value is 0 (midnight).</p>
+     *
+     * @return list of hours at which the asynchronous method aims to run; An empty list disregards the hour.
      */
     int[] hours() default { 0 };
 
     /**
-     * Minutes at which the task aims to runs. Values can range from 0 to 59.
-     * The default value is 0 (at the start of the hour).
+     * <p>Minutes at which the asynchronous method aims to run.</p>
+     *
+     * <p>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.</p>
      *
-     * @return list of minutes at which the task aims to run.
+     * <p>The default value is 0 (at the start of the hour).</p>
+     *
+     * @return list of minutes at which the asynchronous method aims to run; An empty list disregards the minutes.
      */
     int[] minutes() default { 0 };
 
     /**
-     * Seconds at which the task aims to runs. Values can range from 0 to 59.
-     * The default value is 0 (at the start of the minute).
+     * <p>Seconds at which the asynchronous method aims to run.</p>
+     *
+     * <p>Values can range from 0 to 59. A value of empty list causes the asynchronous method
+     * to raise {@link IllegalArgumentException}.</p>
      *
-     * @return list of seconds at which the task aims to run.
+     * <p>The default value is 0 (at the start of the minute).</p>
+     *
+     * @return list of seconds at which the asynchronous method aims to run.
      */
     int[] seconds() default { 0 };
 
     /**
-     * Seconds after which an execution that is late to start should be skipped
-     * rather than starting it late. Values must be greater than 0.
+     * <p>Seconds after which an execution that is late to start should be skipped
+     * rather than starting it late.</p>
+     *
+     * <p>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.
+     * This differs from executions that are missed due to overlap, which are always skipped.</p>
      *
      * @return the threshold for skipping executions that are late to start.
      */
     long skipIfLateBy() default 600L;
 
     /**
-     * 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
+     * <p>Time zone id, such as {@code America/Chicago} or {@code America/Los_Angeles},
+     * which identifies the time zone of the schedule.</p>
+     *
+     * <p>The default value of empty string indicates to use the
      * {@link java.time.ZoneId#systemDefault() default time zone}
-     * for the system.
+     * for the system.</p>
      */
     String zone() default "";
 }