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>