deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r865525 - in /websites/staging/deltaspike/trunk/content: ./ configuration.html
Date Thu, 13 Jun 2013 08:50:28 GMT
Author: buildbot
Date: Thu Jun 13 08:50:28 2013
New Revision: 865525

Staging update by buildbot for deltaspike

    websites/staging/deltaspike/trunk/content/   (props changed)

Propchange: websites/staging/deltaspike/trunk/content/
--- cms:source-revision (original)
+++ cms:source-revision Thu Jun 13 08:50:28 2013
@@ -1 +1 @@

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:50:28 2013
@@ -95,13 +95,13 @@
 <li><a href="#configsource">ConfigSource</a><ul>
+<li><a href="#configsources-provided-by-default">ConfigSources provided by default</a></li>
 <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>
+<li><a href="#custom-config-sources">Custom Config-Sources</a><ul>
 <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>
+<li><a href="#type-safe-configuration">Type-safe configuration</a></li>
@@ -192,12 +192,19 @@ default value which gets returned instea
 <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>Each 'ConfigSource' has a specified 'ordinal' which can be configured using the
key <code>deltaspike_ordinal</code>.
+This ordinal get's used to determine the importance of the values taken from the very ConfigSource.
+A higher ordinal means that the values taken from this ConfigSource will override values
from less important
+ConfigSources. This is the trick which allows to amend configuration from outside a binary
- given
+those outside ConfigSources have a higher <code>deltaspike_ordinal</code> than
the ones who pickup the values from
+within the release binaries.</p>
+<h3 id="configsources-provided-by-default">ConfigSources provided by default</h3>
 <p>Per default there are implementations for the following config sources (listed in
the lookup order):</p>
-<li>System properties</li>
-<li>Environment properties</li>
-<li>JNDI values</li>
-<li>Properties file values (</li>
+<li>System properties (deltaspike_ordinal = 400)</li>
+<li>Environment properties (deltaspike_ordinal = 300)</li>
+<li>JNDI values (deltaspike_ordinal = 200, the base name is "java:comp/env/deltaspike/")</li>
+<li>Properties file values ( (deltaspike_ordinal = 100,
default filename is "META-INF/")</li>
 <p><strong>It's possible to change this order and to add custom config sources.</strong></p>
 <p><strong>Note:</strong> Important Hints esp. for custom implementations:
@@ -211,29 +218,58 @@ the system property with the ordinal key
 <p>Example with <code>/META-INF/</code>: If
the properties file/s should be used
 <strong>before</strong> the other implementations, you have to configure an ordinal
&gt; 400.
 That means, you have to add e.g. <code>deltaspike_ordinal=401</code>.</p>
+<p>Each single property file is treated as own <code>ConfigSource</code>
and thus can have different
+<code>deltaspike_ordinal</code> values!</p>
 <p>In case of <strong>property files</strong> which are supported by default
 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>
 <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
which contains
-the fully qualified class name of the custom implementation/s).</p>
-<p>If you have a simple standalone <code>ConfigSource</code> you can also
register it directly by creating a file
+<p>ConfigSources are picked up using the `java.util.ServiceLoader' mechanism.</p>
+<p>To add a custom config-source, you have to implement the interface <code>ConfigSource</code>
and register
+your implementation in a file
-which contains the fully qualified class name of your <code>ConfigSource</code>.
-Please note that a single <code>ConfigSource</code> should be either registered
directly or
+by writing the fully qualified class name of the custom implementation/s into it.</p>
+<p>If you need dynamic ConfigSources you can also register a <code>ConfigSourceProvider</code>
in a similar way.
+This is useful if you like to dynamically pick up multiple ConfigSources of the same kind.
+E.g. if you like to pick up all <code></code> files from
all the JARs in your classpath.</p>
+<p>Please note that a single <code>ConfigSource</code> should be either
registered directly or
 via a <code>ConfigSourceProvider</code>, but never both ways.</p>
 <p><strong>Important Hint:</strong></p>
 <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>
-<h2 id="type-safe-config">Type-safe config</h2>
-<h3 id="configproperty">@ConfigProperty</h3>
+<h3 id="propertyfileconfig">PropertyFileConfig</h3>
+<p>For registering all your own property files of a certain name in your classpath
+to get picked up as <code>ConfigSource</code>s you can also provide a class
+which implements the <code>PropertyFileConfig</code> interface.</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">MyCustomPropertyFileConfig</span>
<span class="kd">implements</span> <span class="n">PropertyFileConfig</span>
+<span class="o">{</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="n">String</span>
<span class="nf">getPropertyFileName</span><span class="o">()</span>
+    <span class="o">{</span>
+        <span class="k">return</span> <span class="s">&quot;;</span><span
+    <span class="o">}</span>
+<span class="o">}</span>
+<h2 id="type-safe-configuration">Type-safe configuration</h2>
+<p>DeltaSpike provides a way to directly inject configured values into your code
+via the qualifier <code>@ConfigProperty</code>.</p>
+<div class="codehilite"><pre><span class="nd">@ApplicationScoped</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
+<span class="o">{</span>
+    <span class="nd">@Inject</span>
+    <span class="nd">@ConfigProperty</span><span class="o">(</span><span
class="n">name</span> <span class="o">=</span> <span class="s">&quot;endpoint.poll.interval&quot;</span><span
+    <span class="kd">private</span> <span class="n">Integer</span>
<span class="n">pollInterval</span><span class="o">;</span>
+    <span class="nd">@Inject</span>
+    <span class="nd">@ConfigProperty</span><span class="o">(</span><span
class="n">name</span> <span class="o">=</span> <span class="s">&quot;endpoint.poll.servername&quot;</span><span
+    <span class="kd">private</span> <span class="n">String</span>
<span class="n">pollUrl</span><span class="o">;</span>
+    <span class="o">...</span>
+ <span class="o">}</span>

View raw message