svn commit: r1754116 - /sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext

[bd...@apache.org]

Author: bdelacretaz
Date: Tue Jul 26 11:59:54 2016
New Revision: 1754116

URL: http://svn.apache.org/viewvc?rev=1754116&view=rev
Log:
Expand run modes documentation, especially around SLING-2662

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=1754116&r1=1754115&r2=1754116&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 Jul 26 11:59:54 2016
@@ -1,4 +1,4 @@
-Title: Sling Settings (org.apache.sling.settings)
+Title: Sling Settings and Run Modes (org.apache.sling.settings)
 
 # Overview
 
@@ -11,28 +11,54 @@ The Sling Settings Bundle exposes the `S
 | `URL getSlingHome()` | `sling.home.url` | The Sling Home path as an `java.net.URL` instance |
 | `Set<String> getRunModes()` | `sling.run.modes` | The active Run Modes of the running Sling instance |
 
-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.
+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.
 
-## Run Modes
+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.
 
-Run modes are meant to define different sets of configuration parameters for various Sling instances.
+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.
 
-In a web publishing environment, for example, one could use run modes like *staging, production, dev, dmz* or combinations of such values.
+## 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.
 
+The `sling.run.mode.install.options` property is only used on the first startup on the Sling instance and the run modes that it defines cannot be changed later.
 
-### Configuration
+The `sling.run.mode.options` property on the other hand is used at each startup, so the run modes that it defines can be changed between executions of a given Sling instance.
 
-Run modes can only be configured using a system property, or via the `sling.properties` file.
+The value of the both these properties is a string which looks like:
 
-Using `-Dsling.run.modes=foo,bar` on the JVM command-line, for example, activates the *foo* and *bar* run modes. 
+    red,green,blue|one|moon,mars
 
-This command-line parameter takes precedence over a similar definition (`sling.run.modes=dev,staging`) that might be present in the `sling.properties` file found in the Sling home directory.
+where comma-separated groups of run modes are separated by a pipe character (which is not an OR operation, it's just as separator).
 
+Once a group is defined, exactly one run mode will be active from that group. 
+
+If none of the listed run modes are selected, the first one from each group is activated by default. 
+
+If one is selected, this is active.
+
+If several are selected, the first one from the list of valid modes is used.
+
+Examples
+
+    sling.run.mode.options=a,b|c,d,e
+
+User Defines -> Result:
+
+    -> 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.
 
 ### Getting the Run Modes of the Sling instance
 
-The `SlingSettings` service provides the Run Modes of the running Sling instance, examples:
+The `SlingSettings` service provides the Run Modes of the running Sling instance as in this example:
 
     :::java
     SlingSettings settings = ...get from BundleContext...
@@ -43,4 +69,5 @@ The `SlingSettings` service provides the
       // at least one of (foo,wii) run modes
       // is active
     }
-
+	
+Getting run modes in this way is usually not needed, it's better to define bundles or configurations that are only valid in specific run modes, rather than making decisions in code based on run modes.
\ No newline at end of file