deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r865513 - in /websites/staging/deltaspike/trunk/content: ./ configuration.html core.html
Date Thu, 13 Jun 2013 07:16:02 GMT
Author: buildbot
Date: Thu Jun 13 07:16:02 2013
New Revision: 865513

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 07:16:02 2013
@@ -1 +1 @@

Added: websites/staging/deltaspike/trunk/content/configuration.html
--- websites/staging/deltaspike/trunk/content/configuration.html (added)
+++ websites/staging/deltaspike/trunk/content/configuration.html Thu Jun 13 07:16:02 2013
@@ -0,0 +1,214 @@
+<!DOCTYPE html>
+<html lang="en">
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="deltaspike-generate-pages">
+    <meta name="author" content="chm">
+    <title>Apache DeltaSpike - Configuration</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor
license agreements.  See the NOTICE file distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file to you under the Apache License,
Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at .
. Unless required by applicable law or agreed to in writing, software distributed under the
License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, either express or implied.  See the License for the specific language governing
permissions and limitations under the License. -->
+    <!-- Styles -->
+    <link href="./resources/css/bootstrap.css" rel="stylesheet">    
+    <!--<link href="./resources/css/prettify.css" rel="stylesheet" /> -->
+    <link href="./resources/css/codehilite.css" rel="stylesheet" />
+    <link href="./resources/css/bootstrap-responsive.css" rel="stylesheet">
+    <style type="text/css">
+        body {
+            padding-top: 60px;
+            padding-bottom: 40px;
+        }
+    </style>
+	<script type="text/javascript">
+	  var _gaq = _gaq || [];
+	  _gaq.push(['_setAccount', 'UA-36103647-1']);
+	  _gaq.push(['_trackPageview']);
+	  (function() {
+		var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+		ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '';
+		var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+	  })();
+	</script>
+    <div class="navbar navbar-fixed-top">
+        <div class="navbar-inner">
+            <div class="container">
+                <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
+                    <span class="icon-bar"></span>
+                    <span class="icon-bar"></span>
+                    <span class="icon-bar"></span>
+                </a>
+                <a class="brand" href="index.html"><img src="./resources/images/deltaspike-logo-medium.png"/></a>
+                <div class="nav-collapse">
+                    <ul class="nav">
+                        <li class="active"><a href="./index.html">Home</a></li>
+                        <li><a href="./documentation.html">Documentation</a></li>
+                        <li><a href="./source.html">Source</a></li>
+                        <!-- <li><a href="./download.html">Download</a></li>
+                        <li><a href="./community.html">Community</a></li>
+                        <!-- <li><a href="./support.html">Support</a></li>
+                        <li><a href="./news.html">News</a></li>
+                        <li><a href="./migration-guide.html">Migration</a></li>
+                    </ul>
+                </div><!--/.nav-collapse -->
+                <form id="search-form" action="" method="get"
 class="navbar-search pull-right" >
+                    <input value="" name="sitesearch" type="hidden"/>
+                    <input class="search-query" name="q" id="query" type="text" />
+                </form>
+            </div>
+        </div>
+    </div>
+    <div class="container">
+      <div class="row">
+          <div class="span12">
+              <div class="page-title">
+                <h1>Configuration</h1>
+              </div>
+              <div class="toc">
+<li><a href="#deltaspike-configuration-mechanism-basics">DeltaSpike Configuration
Mechanism - Basics</a><ul>
+<li><a href="#configresolver">ConfigResolver</a><ul>
+<li><a href="#propertyfileconfig">PropertyFileConfig</a></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>
+<li><a href="#type-safe-config">Type-safe config</a><ul>
+<li><a href="#configproperty">@ConfigProperty</a></li>
+<hr />
+<h1 id="deltaspike-configuration-mechanism-basics">DeltaSpike Configuration Mechanism
- 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>
+<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
+then further propagated to the Staging environment and finally (if all all are happy with
+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
+inside the binary and to amend this configuration (e.g. database credentials) from outside,
+like environment settings or JNDI or the current [ProjectStage].</p>
+<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>
+<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>,
+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>
+<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
+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
+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">&quot;myKey&quot;</span><span class="o">);</span>
+<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>
+<h2 id="configsource">ConfigSource</h2>
+<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>
+<li>System properties</li>
+<li>Environment properties</li>
+<li>JNDI values</li>
+<li>Properties file values (</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:
+  - The config-source with the highest ordinal gets used first.
+  - If a custom implementation should be invoked <em>before</em> the default
implementations, use an ordinal-value &gt; 400
+  - If a custom implementation should be invoked <em>after</em> the default implementations,
use an ordinal-value &lt; 100</p>
+<h3 id="reordering-of-the-default-order-of-config-sources">Reordering of the default
order of Config-Sources</h3>
+<p>To change the lookup order, you have to configure the ordinal in the corresponding
config source
+(e.g. to change the config ordinal of the config source for system properties, you have to
+the system property with the ordinal key 'deltaspike_ordinal' and the new value).</p>
+<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>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>
+<h3 id="custom-config-sources">Custom Config-Sources</h3>
+<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
+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
+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="type-safe-config">Type-safe config</h2>
+<h3 id="configproperty">@ConfigProperty</h3>
+          </div>
+      </div>
+      <hr>
+      <footer>
+        <p>Copyright © 20011-2012 The Apache Software Foundation, Licensed under
the Apache License, Version 2.0.</p>
+        <p>Apache and the Apache feather logo are trademarks of The Apache Software
+      </footer>
+    </div> <!-- /container -->
+    <!-- Javascript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <!--<script src="./resources/js/prettyfy.js"></script> -->
+    <script src="./resources/js/prettyprint.js"></script>
+    <script src="./resources/js/jquery.js"></script>
+    <script src="./resources/js/bootstrap-transition.js"></script>
+    <script src="./resources/js/bootstrap-alert.js"></script>
+    <script src="./resources/js/bootstrap-modal.js"></script>
+    <script src="./resources/js/bootstrap-dropdown.js"></script>
+    <script src="./resources/js/bootstrap-scrollspy.js"></script>
+    <script src="./resources/js/bootstrap-tab.js"></script>
+    <script src="./resources/js/bootstrap-tooltip.js"></script>
+    <script src="./resources/js/bootstrap-popover.js"></script>
+    <script src="./resources/js/bootstrap-button.js"></script>
+    <script src="./resources/js/bootstrap-collapse.js"></script>
+    <script src="./resources/js/bootstrap-carousel.js"></script>
+    <script src="./resources/js/bootstrap-typeahead.js"></script>

Modified: websites/staging/deltaspike/trunk/content/core.html
--- websites/staging/deltaspike/trunk/content/core.html (original)
+++ websites/staging/deltaspike/trunk/content/core.html Thu Jun 13 07:16:02 2013
@@ -81,6 +81,7 @@
               <div class="toc">
 <li><a href="#core-api">Core - API</a><ul>
+<li><a href="#deltaspike-configuration">DeltaSpike Configuration</a></li>
 <li><a href="#beanprovider">BeanProvider</a></li>
 <li><a href="#beanmanagerprovider">BeanManagerProvider</a></li>
 <li><a href="#type-safe-projectstage">Type-safe ProjectStage</a><ul>
@@ -147,6 +148,8 @@
 <hr />
 <h1 id="core-api">Core - API</h1>
+<h2 id="deltaspike-configuration">DeltaSpike Configuration</h2>
+<p>This is described in an own chapter solely targeting our [configuration] mechanics,
API and SPI.</p>
 <h2 id="beanprovider">BeanProvider</h2>
 <p>The <code>BeanProvider</code> is a class which provides (static) util
methods which allow to lookup beans if it isn't possible to inject them via <code>@Inject</code>
or if the lookup depends on dynamic conditions. Instead of using the term 'bean', the term
'contextual instance' is used because that's the term used by CDI itself.</p>
 <p>The following example shows a simple lookup. With the second parameter it's possible
to specify if the contextual instance is optional. If it isn't expected that the contextual
instance is optional, but no instance has been found, an <code>IllegalStateException</code>
will be thrown.</p>

View raw message