svn commit: r865523 - in /websites/staging/deltaspike/trunk/content: ./ configuration.html

[bu...@apache.org]

Author: buildbot
Date: Thu Jun 13 08:16:03 2013
New Revision: 865523

Log:
Staging update by buildbot for deltaspike

Modified:
    websites/staging/deltaspike/trunk/content/   (props changed)
    websites/staging/deltaspike/trunk/content/configuration.html

Propchange: websites/staging/deltaspike/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Jun 13 08:16:03 2013
@@ -1 +1 @@
-1492557
+1492559

Modified: websites/staging/deltaspike/trunk/content/configuration.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/configuration.html (original)
+++ websites/staging/deltaspike/trunk/content/configuration.html Thu Jun 13 08:16:03 2013
@@ -88,8 +88,9 @@
 </ul>
 </li>
 <li><a href="#configresolver">ConfigResolver</a><ul>
-<li><a href="#getpropertyvalue">getPropertyValue</a></li>
-<li><a href="#getprojectstageawarepropertyvalue">getProjectStageAwarePropertyValue</a></li>
+<li><a href="#getpropertyvalue">getPropertyValue()</a></li>
+<li><a href="#getprojectstageawarepropertyvalue">getProjectStageAwarePropertyValue()</a></li>
+<li><a href="#getpropertyawarepropertyvalue">getPropertyAwarePropertyValue()</a></li>
 <li><a href="#handling-of-default-values">handling of default values</a></li>
 </ul>
 </li>
@@ -109,24 +110,30 @@
 <h1 id="configuration-basics">Configuration Basics</h1>
 <p>The goal of the DeltaSpike configuration mechanism is to make it obsolete to touch
 released binaries for changing the configuration of your project.
-All values which are needed in your code but should not be hardcoded can be
+All values which are needed in your code (but should not be hardcoded as static final constants) can be
 maintained via DeltaSpikes own configuration mechanism in a very flexible and powerful way.</p>
 <h3 id="benefits-for-production">Benefits for Production</h3>
 <p>Once a binary like a WAR file or an EAR got created and tested, it must <em>not</em> get changed anymore.
 The exact same binary which got created by the release manager will get moved to the Test system,
-then further propagated to the Staging environment and finally (if all all are happy with it)
+then further propagated to the Staging environment and finally (if all people are happy with it)
 will get moved to the Production system. And all this without any changes on the binary itself!</p>
 <p>The Apache DeltaSpike configuration system makes this possible by providing a default configuration
-inside the binary and allowing to amend this configuration (e.g. database credentials) from outside,
+inside the binary and allowing to amend this configuration (e.g. database credentials,
+some URLs from remote REST or SOAP endpoints, etc) from outside
 like environment settings, JNDI or the current <a href="projectstage.html">ProjectStage</a>.</p>
 <h3 id="drop-in-configuration">Drop-In Configuration</h3>
-<p>This also allows for dynamic configuration in case of a JAR drop-in.
+<p>This mechanism also allows for dynamic configuration in case of a JAR drop-in.
 By adding some JAR to the classpath, all it's contained configuration will get picked up
-and considered in the property value evaluation.</p>
+and considered in the property value evaluation.
+You could also use this mechanism to switch implementations of some SPI
+(Service Provider Interface) in your own code.</p>
 <h3 id="cdi-extension-configuration">CDI-Extension Configuration</h3>
-<p>In some cases low-level configs are needed e.g. during the bootstrapping process of the CDI container.
-Currently this is e.g. used to configure the value of the current project-stage,
-configured values which can be used in the expressions for <code>@Exclude</code>, etc.
+<p>In some cases low-level configs are needed e.g. during the bootstrapping process of the CDI container.</p>
+<p>The good news: our DeltaSpike configuration mechanism does not rely on any other EE mechanism to
+be booted. Which means it can perfectly get used to even configure those parts itself.
+Since the mechanism doesn't rely on CDI it can for example be used to configure CDI-Extensions.</p>
+<p>Currently this is e.g. used to configure the value of the current <a href="projectstage.html">ProjectStage</a>,
+configured values which can be used in the expressions for <code>@Exclude</code>, 'Deactivatable', etc.
 DeltaSpike needs such a low-level approach for several features internally,
 but users can utilize it for their own needs as well.
 This is done by using the <code>ConfigResolver</code> which resolves and caches <code>ConfigSource</code>s per application.</p>
@@ -135,17 +142,17 @@ This is done by using the <code>ConfigRe
 <code>@ConfigProperty</code> CDI Qualifier.</p>
 <h1 id="configresolver">ConfigResolver</h1>
 <p>The <code>ConfigResolver</code> is the central point to pick up configured values in DeltaSpike.</p>
-<h3 id="getpropertyvalue">getPropertyValue</h3>
+<h3 id="getpropertyvalue">getPropertyValue()</h3>
 <p>The method <code>ConfigResolver#getPropertyValue(String key)</code> allows to provide a string based key and
-returns the configured value as <code>String</code> or <code>null</code> if no value has been found.</p>
+returns the configured value as <code>String</code>, or <code>null</code> if no value has been found.</p>
 <p><code>ConfigResolver#getAllPropertyValues(String key)</code> has a similar contract but it returns a list which might
 be empty if there are no configured values for the given key.</p>
-<p>Simple lookup in the low-level config:</p>
-<div class="codehilite"><pre><span class="n">String</span> <span class="n">myValue</span> <span class="o">=</span> <span class="n">ConfigResolver</span><span class="o">.</span><span class="na">getPropertyValue</span><span class="o">(</span><span class="s">&quot;myKey&quot;</span><span class="o">);</span>
+<p>This is a code excerpt about how to do a simple lookup in the deltaspike configuration:</p>
+<div class="codehilite"><pre><span class="n">String</span> <span class="n">dbUserName</span> <span class="o">=</span> <span class="n">ConfigResolver</span><span class="o">.</span><span class="na">getPropertyValue</span><span class="o">(</span><span class="s">&quot;databaseconfig.username&quot;</span><span class="o">);</span>
 </pre></div>
 
 
-<h3 id="getprojectstageawarepropertyvalue">getProjectStageAwarePropertyValue</h3>
+<h3 id="getprojectstageawarepropertyvalue">getProjectStageAwarePropertyValue()</h3>
 <p>The method <code>ConfigResolver#getProjectStageAwarePropertyValue(String key)</code> utilizes the
 <a href="projectstage.html">DeltaSpike ProjectStage</a> mechanism to allow configured values
 to depend on the current <code>ProjectStage</code> of the system we run on.</p>
@@ -156,6 +163,29 @@ we found a configured value.</p>
 <li>key + '.' + projectStage , e.g. "databaseconfig.username.Production"</li>
 <li>key alone , e.g. "databaseconfig.username"</li>
 </ul>
+<h3 id="getpropertyawarepropertyvalue">getPropertyAwarePropertyValue()</h3>
+<p>The method <code>ConfigResolver#getProjectStageAwarePropertyValue(String key, String property)</code>
+first looks up the configured value of the given property and uses this value to determine
+the final lookup path. All those lookups take the <a href="projectstage.html">DeltaSpike ProjectStage</a>
+mechanism into account.</p>
+<p>Given we have the following code in our program:</p>
+<div class="codehilite"><pre><span class="n">String</span> <span class="n">dbUserName</span> <span class="o">=</span> <span class="n">ConfigResolver</span><span class="o">.</span><span class="na">getPropertyAwarePropertyValue</span><span class="o">(</span><span class="s">&quot;databaseconfig.username&quot;</span><span class="o">,</span> <span class="s">&quot;dbvendor&quot;</span><span class="o">);</span>
+</pre></div>
+
+
+<p>This will end up in the following lookup sequences. First we need to resolve the value of the property:</p>
+<ul>
+<li>propertyValue = property + '.'  + projectStage, e.g. "dbvendor.Production"</li>
+<li>if nothing found: propertyValue = property, e.g. "dbvendor"</li>
+</ul>
+<p>Let's assume we found the value 'mysql' for our dbvendor. In this case the following
+lookup chain is used until a value got found:</p>
+<ul>
+<li>key + '.' + property + projectstage, e.g. "databaseconfig.username.mysql.Production"</li>
+<li>key + '.' + property, e.g. "databaseconfig.username.mysql"</li>
+<li>key + '.' + projectstage, e.g. "databaseconfig.username.Production"</li>
+<li>key,  e.g. "databaseconfig.username"</li>
+</ul>
 <h3 id="handling-of-default-values">handling of default values</h3>
 <p>There is a 2nd variant of all those methods where it is possible to provide a
 default value which gets returned instead of <code>null</code> or if the final result is an empty String.</p>