Author: cziegeler
Date: Fri Dec 18 08:07:10 2015
New Revision: 1720727
URL: http://svn.apache.org/viewvc?rev=1720727&view=rev
Log:
SLING-5388 : Javadoc for ScheduleOptions is misleading
Modified:
sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/ScheduleOptions.java
sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/Scheduler.java
Modified:
sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/ScheduleOptions.java
URL:
http://svn.apache.org/viewvc/sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/ScheduleOptions.java?rev=1720727&r1=1720726&r2=1720727&view=diff
==============================================================================
---
sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/ScheduleOptions.java
(original)
+++
sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/ScheduleOptions.java
Fri Dec 18 08:07:10 2015
@@ -52,10 +52,13 @@ public interface ScheduleOptions {
ScheduleOptions canRunConcurrently(final boolean flag);
/**
- * Flag indicating whether the job should only be run on the leader.
- * This defaults to false.
+ * Flag indicating whether the job should only be run on the leader. This
defaults to false.
+ * If this job is scheduled on the leader it is started. Scheduling this
job on any other
+ * instance will not start it. This option should only be used if the
schedule call is done
+ * on all instances in the cluster.
* If no topology information is available (= no Apache Sling Discovery
Implementation active)
- * this flag is ignored and the job is run on all instances!
+ * the job is not run at all.
+ *
* If {@link #onSingleInstanceOnly(boolean)} or {@link
#onInstancesOnly(String[])} has been called before,
* that option is reset and overwritten by the value of this method.
* @param flag Whether this job should only be run on the leader
@@ -64,9 +67,12 @@ public interface ScheduleOptions {
/**
* Flag indicating whether the job should only be run on a single instance
in a cluster
- * This defaults to false.
+ * This defaults to false. Scheduling this job might start it or not
depending on the
+ * topology information. This option should only be used if the schedule
call is done
+ * on all instances in the cluster.
* If no topology information is available (= no Apache Sling Discovery
Implementation active)
- * this flag is ignored and the job is run on all instances!
+ * this job is not run at all.
+ *
* If {@link #onLeaderOnly(boolean)} or {@link #onInstancesOnly(String[])}
has been called before,
* that option is reset and overwritten by the value of this method.
* @param flag Whether this job should only be run on a single instance.
@@ -75,8 +81,9 @@ public interface ScheduleOptions {
/**
* List of Sling IDs this job should be run on.
- * If no topology information is available (= no Apache Sling Discovery
Implementation active)
- * this flag is ignored and the job is run on all instances!
+ * This job is only started if the current instance is in the set of IDs.
This option should
+ * only be used, if it is scheduled on all instances in the cluster.
+ *
* If {@link #onLeaderOnly(boolean)} or {@link
#onSingleInstanceOnly(boolean)} has been called before,
* that option is reset and overwritten by the value of this method.
* @param slingIds Array of Sling IDs this job should run on
Modified:
sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/Scheduler.java
URL:
http://svn.apache.org/viewvc/sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/Scheduler.java?rev=1720727&r1=1720726&r2=1720727&view=diff
==============================================================================
---
sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/Scheduler.java
(original)
+++
sling/trunk/bundles/commons/scheduler/src/main/java/org/apache/sling/commons/scheduler/Scheduler.java
Fri Dec 18 08:07:10 2015
@@ -104,12 +104,24 @@ public interface Scheduler {
/**
* Schedule a job based on the options.
*
- * Note that if a job with the same name has already been added, the old
job is cancelled and this new job replaces
+ * Note that if a job with the same name has already been added, the old
job is
+ * cancelled and this new job replaces
* the old job.
*
- * The job object needs either to be a {@link Job} or a {@link Runnable}.
The options have to be created
+ * The job object needs either to be a {@link Job} or a {@link Runnable}.
The
+ * options have to be created
* by one of the provided methods from this scheduler.
*
+ * The job is only started on this instance - if it is started at all. The
+ * options for running on a single instance, on the leader etc. (see
+ * {@link ScheduleOptions#onInstancesOnly(String[])},
+ * {@link ScheduleOptions#onLeaderOnly(boolean)},
+ * and {@link ScheduleOptions#onSingleInstanceOnly(boolean)}) are only
useful,
+ * if the same job is scheduled on all instances in a cluster. In this
case this
+ * extra configuration controls on which instances the job is really
started.
+ * Using the above options might not start the job on the current
instance, for
+ * example if the current instance is not the leader.
+ *
* @param job The job to execute (either {@link Job} or {@link Runnable}).
* @param options Required options defining how to schedule the job
* @return true if the job could be added, false otherwise.
