svn commit: r1009224 - in /websites/staging/sling/trunk/content: ./ documentation/bundles/sling-settings-org-apache-sling-settings.html

[bu...@apache.org]

Author: buildbot
Date: Tue Mar 28 12:06:15 2017
New Revision: 1009224

Log:
Staging update by buildbot for sling

Modified:
    websites/staging/sling/trunk/content/   (props changed)
    websites/staging/sling/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.html

Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Mar 28 12:06:15 2017
@@ -1 +1 @@
-1788488
+1789103

Modified: websites/staging/sling/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.html Tue Mar 28 12:06:15 2017
@@ -149,9 +149,9 @@ h2:hover > .headerlink, h3:hover > .head
 </table>
 <p>The new Sling Settings Bundle replaces the former <a href="/old-stuff/run-modes-org-apache-sling-runmode.html">Run Modes (org.apache.sling.runmode)</a> Bundle and the <code>SlingSettingsService</code> previously provided by the Sling Engine bundle, as it also implements the run modes logic.</p>
 <h2 id="selecting-the-active-run-modes">Selecting the active run modes<a class="headerlink" href="#selecting-the-active-run-modes" title="Permanent link">&para;</a></h2>
-<p>The run modes are selected based on the <code>sling.run.modes</code> 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.</p>
+<p>The run modes are selected based on the <code>sling.run.modes</code> 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 <code>sling.run.mode.install.options</code> or <code>sling.run.mode.options</code>) 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).</p>
 <p>Using <code>-Dsling.run.modes=foo,bar</code> on the JVM command-line, for example, activates the <em>foo</em> and <em>bar</em> run modes if that combination is valid.</p>
-<p>The Absolute Truth about run modes definition and selection is found in the <a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/settings/src/test/java/org/apache/sling/settings/impl/RunModeImplTest.java">RunModeImplTest</a> which should be self-explaining.</p>
+<p>The absolute truth about run modes definition and selection is found in the <a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/settings/src/test/java/org/apache/sling/settings/impl/RunModeImplTest.java">RunModeImplTest</a> which should be self-explaining.</p>
 <h2 id="defining-valid-run-modes">Defining valid run modes<a class="headerlink" href="#defining-valid-run-modes" title="Permanent link">&para;</a></h2>
 <p>Since <a href="https://issues.apache.org/jira/browse/SLING-2662">SLING-2662</a> the valid run modes are defined by the <code>sling.run.mode.options</code> and <code>sling.run.mode.install.options</code> configuration properties, usually defined in the <code>sling.properties</code> file or in the provisioning model of a Sling Launchpad instance.</p>
 <p>The <code>sling.run.mode.install.options</code> property is only used on the first startup on the Sling instance and the run modes that it defines cannot be changed later.</p>
@@ -161,27 +161,60 @@ h2:hover > .headerlink, h3:hover > .head
 </pre></div>
 
 
-<p>where comma-separated groups of run modes are separated by a pipe character (which is not an OR operation, it's just as separator).</p>
-<p>Once a group is defined, exactly one run mode will be active from that group. </p>
-<p>If none of the listed run modes are selected, the first one from each group is activated by default. </p>
-<p>If one is selected, this is active.</p>
-<p>If several are selected, the first one from the list of valid modes is used.</p>
+<p>where <em>comma-separated run modes form a group</em>. The individual groups are separated by a pipe character (<code>|</code>, which is not an OR operation, it's just as separator). A group defines a number of run modes which are <strong>mutually exclusive</strong>. It means once a group is defined, exactly one run mode will be active from that group.</p>
+<p>The example from above consists out of 3 different groups</p>
+<ol>
+<li><code>red,green,blue</code></li>
+<li><code>one</code></li>
+<li><code>moon,mars</code></li>
+</ol>
+<p>The rules for determining the active run modes from the selected run mode (<code>sling.run.modes</code>) and the run mode options (<code>sling.run.mode.install.options</code> and <code>sling.run.mode.options</code>) are as follows : </p>
+<ol>
+<li>If none of the run modes in the options are selected, the first one from each group in the options is activated by default. </li>
+<li>If one is selected from a group in the options, this is active.</li>
+<li>If several are selected from one group in the options, the first one from the list of valid run modes is used.</li>
+<li>If the selected run mode is not mentioned in any of the option groups it is active</li>
+</ol>
 <p>Examples</p>
 <div class="codehilite"><pre><span class="n">sling</span><span class="p">.</span><span class="n">run</span><span class="p">.</span><span class="n">mode</span><span class="p">.</span><span class="n">options</span><span class="p">=</span><span class="n">a</span><span class="p">,</span><span class="n">b</span><span class="o">|</span><span class="n">c</span><span class="p">,</span><span class="n">d</span><span class="p">,</span><span class="n">e</span>
 </pre></div>
 
 
-<p>User Defines -&gt; Result:</p>
-<div class="codehilite"><pre><span class="o">-&gt;</span> <span class="n">a</span><span class="p">,</span><span class="n">c</span>
-<span class="n">a</span> <span class="o">-&gt;</span> <span class="n">a</span><span class="p">,</span><span class="n">c</span>
-<span class="n">b</span> <span class="o">-&gt;</span> <span class="n">b</span><span class="p">,</span><span class="n">c</span>
-<span class="n">a</span><span class="p">,</span><span class="n">b</span> <span class="o">-&gt;</span> <span class="n">a</span><span class="p">,</span><span class="n">c</span>
-<span class="n">a</span><span class="p">,</span><span class="n">d</span> <span class="o">-&gt;</span> <span class="n">a</span><span class="p">,</span><span class="n">d</span>
-<span class="n">a</span><span class="p">,</span><span class="n">e</span><span class="p">,</span><span class="n">f</span> <span class="o">-&gt;</span> <span class="n">a</span><span class="p">,</span><span class="n">e</span>
-</pre></div>
-
-
-<p>Remember to look at the <code>RunModeImplTest</code> mentioned above for details, and feel freee to enhance it with useful examples.</p>
+<table class="table">
+<thead>
+<tr>
+<th>User defined run modes (e.g. via property <code>sling.run.modes</code>)</th>
+<th>Effectively active run modes</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>(none)</td>
+<td><code>a,c</code></td>
+</tr>
+<tr>
+<td><code>a</code></td>
+<td><code>a,c</code></td>
+</tr>
+<tr>
+<td><code>b</code></td>
+<td><code>b,c</code></td>
+</tr>
+<tr>
+<td><code>a,b</code></td>
+<td><code>a,c</code></td>
+</tr>
+<tr>
+<td><code>a,d</code></td>
+<td><code>a,d</code></td>
+</tr>
+<tr>
+<td><code>a,e,f</code></td>
+<td><code>a,e</code></td>
+</tr>
+</tbody>
+</table>
+<p>Remember to look at the <code>RunModeImplTest</code> mentioned above for details, and feel free to enhance it with useful examples.</p>
 <h3 id="getting-the-run-modes-of-the-sling-instance">Getting the Run Modes of the Sling instance<a class="headerlink" href="#getting-the-run-modes-of-the-sling-instance" title="Permanent link">&para;</a></h3>
 <p>The <code>SlingSettings</code> service provides the Run Modes of the running Sling instance as in this example:</p>
 <div class="codehilite"><pre><span class="n">SlingSettings</span> <span class="n">settings</span> <span class="o">=</span> <span class="o">...</span><span class="na">get</span> <span class="n">from</span> <span class="n">BundleContext</span><span class="o">...</span>
@@ -197,7 +230,7 @@ h2:hover > .headerlink, h3:hover > .head
 
 <p>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.</p>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1754116 by bdelacretaz on Tue, 26 Jul 2016 11:59:54 +0000
+        Rev. 1789103 by kwin on Tue, 28 Mar 2017 12:05:56 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project