Author: kwin
Date: Tue Mar 28 12:05:56 2017
New Revision: 1789103
URL: http://svn.apache.org/viewvc?rev=1789103&view=rev
Log:
clarify run mode options
Modified:
sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext
Modified:
sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext?rev=1789103&r1=1789102&r2=1789103&view=diff
==============================================================================
---
sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext
(original)
+++
sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext
Tue Mar 28 12:05:56 2017
@@ -14,11 +14,11 @@ The Sling Settings Bundle exposes the `S
The new Sling Settings Bundle replaces the former [Run Modes
(org.apache.sling.runmode)]({{ refs.run-modes-org-apache-sling-runmode.path }})
Bundle and the `SlingSettingsService` previously provided by the Sling Engine
bundle, as it also implements the run modes logic.
## Selecting the active run modes
-The run modes are selected based on the `sling.run.modes` property (the
"selection property"), specified in the Sling settings file or as a
command-line parameter (which takes precedence), out of the valid run modes
defined by the properties described below.
+The run modes are selected based on the `sling.run.modes` property (the
"selection property"), specified in the Sling settings file or as a
command-line parameter (which takes precedence), out of the valid run modes
defined by the properties described below. The value is a String which contains
a list of comma-separated run modes. If a run mode is given here which is not
contained in any group of valid run modes (given in
`sling.run.mode.install.options` or `sling.run.mode.options`) it is always
active, on the other hand run modes which are contained in any of the
predefined groups may be modified/removed (see below for the details).
Using `-Dsling.run.modes=foo,bar` on the JVM command-line, for example,
activates the *foo* and *bar* run modes if that combination is valid.
-The Absolute Truth about run modes definition and selection is found in the
[RunModeImplTest](https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/settings/src/test/java/org/apache/sling/settings/impl/RunModeImplTest.java)
which should be self-explaining.
+The absolute truth about run modes definition and selection is found in the
[RunModeImplTest](https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/settings/src/test/java/org/apache/sling/settings/impl/RunModeImplTest.java)
which should be self-explaining.
## Defining valid run modes
Since [SLING-2662](https://issues.apache.org/jira/browse/SLING-2662) the valid
run modes are defined by the `sling.run.mode.options` and
`sling.run.mode.install.options` configuration properties, usually defined in
the `sling.properties` file or in the provisioning model of a Sling Launchpad
instance.
@@ -31,30 +31,35 @@ The value of the both these properties i
red,green,blue|one|moon,mars
-where comma-separated groups of run modes are separated by a pipe character
(which is not an OR operation, it's just as separator).
+where *comma-separated run modes form a group*. The individual groups are
separated by a pipe character (`|`, which is not an OR operation, it's just as
separator). A group defines a number of run modes which are **mutually
exclusive**. It means once a group is defined, exactly one run mode will be
active from that group.
-Once a group is defined, exactly one run mode will be active from that group.
+The example from above consists out of 3 different groups
-If none of the listed run modes are selected, the first one from each group is
activated by default.
+1. `red,green,blue`
+2. `one`
+3. `moon,mars`
-If one is selected, this is active.
+The rules for determining the active run modes from the selected run mode
(`sling.run.modes`) and the run mode options (`sling.run.mode.install.options`
and `sling.run.mode.options`) are as follows :
-If several are selected, the first one from the list of valid modes is used.
+1. If none of the run modes in the options are selected, the first one from
each group in the options is activated by default.
+1. If one is selected from a group in the options, this is active.
+1. If several are selected from one group in the options, the first one from
the list of valid run modes is used.
+1. If the selected run mode is not mentioned in any of the option groups it is
active
Examples
sling.run.mode.options=a,b|c,d,e
-User Defines -> Result:
+User defined run modes (e.g. via property `sling.run.modes`) | Effectively
active run modes
+--- | ---
+(none) | `a,c`
+`a` | `a,c`
+`b` | `b,c`
+`a,b` | `a,c`
+`a,d` | `a,d`
+`a,e,f` | `a,e`
- -> a,c
- a -> a,c
- b -> b,c
- a,b -> a,c
- a,d -> a,d
- a,e,f -> a,e
-
-Remember to look at the `RunModeImplTest` mentioned above for details, and
feel freee to enhance it with useful examples.
+Remember to look at the `RunModeImplTest` mentioned above for details, and
feel free to enhance it with useful examples.
### Getting the Run Modes of the Sling instance
