svn commit: r1492559 - /deltaspike/site/trunk/content/configuration.mdtext

[st...@apache.org]

Author: struberg
Date: Thu Jun 13 08:15:56 2013
New Revision: 1492559

URL: http://svn.apache.org/r1492559
Log:
add docs for getPropertyAwarePropertyValue

Modified:
    deltaspike/site/trunk/content/configuration.mdtext

Modified: deltaspike/site/trunk/content/configuration.mdtext
URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/configuration.mdtext?rev=1492559&r1=1492558&r2=1492559&view=diff
==============================================================================
--- deltaspike/site/trunk/content/configuration.mdtext (original)
+++ deltaspike/site/trunk/content/configuration.mdtext Thu Jun 13 08:15:56 2013
@@ -24,7 +24,7 @@ Notice:    Licensed to the Apache Softwa
 
 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.
 
 
@@ -32,24 +32,32 @@ maintained via DeltaSpikes own configura
 
 Once a binary like a WAR file or an EAR got created and tested, it must _not_ 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!
 
 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 [ProjectStage](projectstage.html).
 
 ### Drop-In Configuration
 
-This also allows for dynamic configuration in case of a JAR drop-in.
+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.
+You could also use this mechanism to switch implementations of some SPI
+(Service Provider Interface) in your own code.
 
 ### CDI-Extension Configuration
 
 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 `@Exclude`, etc.
+
+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.
+
+Currently this is e.g. used to configure the value of the current [ProjectStage](projectstage.html),
+configured values which can be used in the expressions for `@Exclude`, '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 `ConfigResolver` which resolves and caches `ConfigSource`s per application.
@@ -63,20 +71,20 @@ DeltaSpike also provides a mechanism to 
 
 The `ConfigResolver` is the central point to pick up configured values in DeltaSpike.
 
-### getPropertyValue
+### getPropertyValue()
 
 The method `ConfigResolver#getPropertyValue(String key)` allows to provide a string based key and
-returns the configured value as `String` or `null` if no value has been found.
+returns the configured value as `String`, or `null` if no value has been found.
 
 `ConfigResolver#getAllPropertyValues(String key)` has a similar contract but it returns a list which might
 be empty if there are no configured values for the given key.
 
-Simple lookup in the low-level config:
+This is a code excerpt about how to do a simple lookup in the deltaspike configuration:
 
     :::java
-    String myValue = ConfigResolver.getPropertyValue("myKey");
+    String dbUserName = ConfigResolver.getPropertyValue("databaseconfig.username");
 
-### getProjectStageAwarePropertyValue
+### getProjectStageAwarePropertyValue()
 
 The method `ConfigResolver#getProjectStageAwarePropertyValue(String key)` utilizes the
 [DeltaSpike ProjectStage](projectstage.html) mechanism to allow configured values
@@ -89,6 +97,32 @@ we found a configured value.
 * key + '.' + projectStage , e.g. "databaseconfig.username.Production"
 * key alone , e.g. "databaseconfig.username"
 
+### getPropertyAwarePropertyValue()
+
+The method `ConfigResolver#getProjectStageAwarePropertyValue(String key, String property)`
+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 [DeltaSpike ProjectStage](projectstage.html)
+mechanism into account.
+
+Given we have the following code in our program:
+
+    :::java
+    String dbUserName = ConfigResolver.getPropertyAwarePropertyValue("databaseconfig.username", "dbvendor");
+
+This will end up in the following lookup sequences. First we need to resolve the value of the property:
+
+* propertyValue = property + '.'  + projectStage, e.g. "dbvendor.Production"
+* if nothing found: propertyValue = property, e.g. "dbvendor"
+
+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:
+
+* key + '.' + property + projectstage, e.g. "databaseconfig.username.mysql.Production"
+* key + '.' + property, e.g. "databaseconfig.username.mysql"
+* key + '.' + projectstage, e.g. "databaseconfig.username.Production"
+* key,  e.g. "databaseconfig.username"
+
+
 ### handling of default values
 
 There is a 2nd variant of all those methods where it is possible to provide a