SLING-5974 document misfire behaviour of Sling Scheduler
git-svn-id: https://svn.apache.org/repos/asf/sling/trunk@1756757 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/main/java/org/apache/sling/commons/scheduler/Scheduler.java b/src/main/java/org/apache/sling/commons/scheduler/Scheduler.java
index aad736f..a9a860d 100644
--- a/src/main/java/org/apache/sling/commons/scheduler/Scheduler.java
+++ b/src/main/java/org/apache/sling/commons/scheduler/Scheduler.java
@@ -174,7 +174,9 @@
ScheduleOptions NOW(int times, long period);
/**
- * Create a schedule options to fire a job once at a specific date
+ * Create a schedule options to fire a job once at a specific date.
+ * <p>In case the scheduled time was missed due to the Scheduler not running or no thread being available at that point in time
+ * the job will be executed only once, as soon as the Scheduler is running again and a thread is available for processing the job.</p>
* @param date The date this job should be run.
* @return The schedule options.
* @since 2.3
@@ -182,7 +184,16 @@
ScheduleOptions AT(Date date);
/**
- * Create a schedule options to fire a job period starting at a specific date
+ * Create a schedule options to fire a job period starting at a specific date.
+ * <p>In case the scheduled time was missed due to the Scheduler not running or no thread being available at that point in time
+ * the behavior depends on the {@code times} parameter:
+ * <ol>
+ * <li>If {@code times} is -1 (meaning unlimited repetitions) there will be no immediate action. Instead the scheduler just waits for next scheduled interval.
+ * <li>Otherwise (limited amount of repitions) the job will be executed only once, as soon as the Scheduler is running again and a thread is available for processing the job.
+ * Then the scheduler waits desired interval and executes all remaining triggers.
+ * Effectively the first fire time of the misfired trigger is moved to current time with no other changes.
+ * </ol>
+ * </p>
* @param date The date this job should be run.
* @param times The number of times this job should be started (must be higher than 1 or
* -1 for endless)
@@ -193,7 +204,10 @@
ScheduleOptions AT(Date date, int times, long period);
/**
- * Create a schedule options to schedule the job based on the expression
+ * Create a schedule options to schedule the job based on the expression.
+ * <p>In case the scheduled time was missed due to the Scheduler not running or no thread being available at that point in time
+ * the job will be executed only once, as soon as the Scheduler is running again and a thread is available for processing the job.
+ * No matter how many trigger executions were missed, only a single immediate execution is performed.</p>
* @param expression The cron exception
* @return The schedule options.
* @since 2.3
