You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by bu...@apache.org on 2013/06/13 09:50:14 UTC
svn commit: r865521 - in /websites/staging/deltaspike/trunk/content: ./
configuration.html
Author: buildbot
Date: Thu Jun 13 07:50:14 2013
New Revision: 865521
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 07:50:14 2013
@@ -1 +1 @@
-1492554
+1492557
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 07:50:14 2013
@@ -7,7 +7,7 @@
<meta name="description" content="deltaspike-generate-pages">
<meta name="author" content="chm">
- <title>Apache DeltaSpike - Configuration</title>
+ <title>Apache DeltaSpike - DeltaSpike Configuration Mechanism</title>
@@ -76,20 +76,27 @@
<div class="row">
<div class="span12">
<div class="page-title">
- <h1>Configuration</h1>
+ <h1>DeltaSpike Configuration Mechanism</h1>
</div>
<div class="toc">
<ul>
-<li><a href="#deltaspike-configuration-mechanism-basics">DeltaSpike Configuration Mechanism - Basics</a><ul>
+<li><a href="#configuration-basics">Configuration Basics</a><ul>
+<li><a href="#benefits-for-production">Benefits for Production</a></li>
+<li><a href="#drop-in-configuration">Drop-In Configuration</a></li>
+<li><a href="#cdi-extension-configuration">CDI-Extension Configuration</a></li>
+<li><a href="#userland-configuration">Userland Configuration</a></li>
+</ul>
+</li>
<li><a href="#configresolver">ConfigResolver</a><ul>
-<li><a href="#propertyfileconfig">PropertyFileConfig</a></li>
+<li><a href="#getpropertyvalue">getPropertyValue</a></li>
+<li><a href="#getprojectstageawarepropertyvalue">getProjectStageAwarePropertyValue</a></li>
+<li><a href="#handling-of-default-values">handling of default values</a></li>
</ul>
</li>
<li><a href="#configsource">ConfigSource</a><ul>
<li><a href="#reordering-of-the-default-order-of-config-sources">Reordering of the default order of Config-Sources</a></li>
<li><a href="#custom-config-sources">Custom Config-Sources</a></li>
-</ul>
-</li>
+<li><a href="#propertyfileconfig">PropertyFileConfig</a></li>
<li><a href="#type-safe-config">Type-safe config</a><ul>
<li><a href="#configproperty">@ConfigProperty</a></li>
</ul>
@@ -99,44 +106,60 @@
</ul>
</div>
<hr />
-<h1 id="deltaspike-configuration-mechanism-basics">DeltaSpike Configuration Mechanism - Basics</h1>
+<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
-configured via DeltaSpikes own mechanism in a very flexible and powerful way.</p>
+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)
-will get moved to the Production system. Thus we need a way to</p>
-<p>The Apache DeltaSpike configuration system makes it possible to provide default configuration
-inside the binary and to amend this configuration (e.g. database credentials) from outside,
-like environment settings or JNDI or the current [ProjectStage].</p>
+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,
+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.
By adding some JAR to the classpath, all it's contained configuration will get picked up
and considered in the property value evaluation.</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.
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>
-<p>DeltaSpike also provides a mechanism to inject those configured values using <code>@ConfigProperty</code></p>
-<h2 id="configresolver">ConfigResolver</h2>
+<h3 id="userland-configuration">Userland Configuration</h3>
+<p>DeltaSpike also provides a mechanism to inject those configured values using the
+<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>
-<p>The method <code>ConfigResolver#getPropertyValue</code> allows to provide a string based key and
+<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>
-<p><code>ConfigResolver#getAllPropertyValues</code> has a similar contract but it returns a list which might
+<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">ConfigResolver</span><span class="o">.</span><span class="na">getPropertyValue</span><span class="o">(</span><span class="s">"myKey"</span><span class="o">);</span>
+<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">"myKey"</span><span class="o">);</span>
</pre></div>
+<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>
+<p>This is done by first looking up the ProjectStage (this internally happens with the
+DeltaSpike ConfigResolver as well) and then go down the following lookup chain until
+we found a configured value.</p>
+<ul>
+<li>key + '.' + projectStage , e.g. "databaseconfig.username.Production"</li>
+<li>key alone , 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>
-<h3 id="propertyfileconfig">PropertyFileConfig</h3>
-<p>TODO</p>
-<h2 id="configsource">ConfigSource</h2>
+<h1 id="configsource">ConfigSource</h1>
<p>A <code>ConfigSource</code> is exactly what it's name says: a source for configured values.
The <code>ConfigResolver</code> uses all configured implementations of <code>ConfigSource</code> to lookup the property in question.</p>
<p>Per default there are implementations for the following config sources (listed in the lookup order):</p>
@@ -161,7 +184,7 @@ That means, you have to add e.g. <code>d
<p><strong>Hint:</strong></p>
<p>In case of <strong>property files</strong> which are supported by default (<code>/META-INF/apache-deltaspike.properties</code>)
every file is handled as independent config-source, but all of them have ordinal 400 by default (and can be reordered in a fine-grained manner).</p>
-<h3 id="custom-config-sources">Custom Config-Sources</h3>
+<h2 id="custom-config-sources">Custom Config-Sources</h2>
<p>To add a custom config-source, you have to implement the interface <code>ConfigSourceProvider</code> (and <code>ConfigSource</code>)
and activate the implementation of <code>ConfigSourceProvider</code> with the std. SPI mechanism provided
by Java via the <code>ServiceLoader</code> (that means you have to create
@@ -176,6 +199,8 @@ via a <code>ConfigSourceProvider</code>,
<p>Have a look at the abstract base-implementation of <code>ConfigSource</code> DeltaSpike is using internally,
if a custom implementation should load the ordinal value from the config-source
like the default implementations provided by DeltaSpike do.</p>
+<h2 id="propertyfileconfig">PropertyFileConfig</h2>
+<p>TODO</p>
<h2 id="type-safe-config">Type-safe config</h2>
<h3 id="configproperty">@ConfigProperty</h3>
<p>TODO</p>