svn commit: r1492545 - in /deltaspike/site/trunk/content: configuration.mdtext core.mdtext

[st...@apache.org]

Author: struberg
Date: Thu Jun 13 07:14:40 2013
New Revision: 1492545

URL: http://svn.apache.org/r1492545
Log:
move configuration into an own chapter.

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

Modified: deltaspike/site/trunk/content/configuration.mdtext
URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/configuration.mdtext?rev=1492545&r1=1492544&r2=1492545&view=diff
==============================================================================
--- deltaspike/site/trunk/content/configuration.mdtext (original)
+++ deltaspike/site/trunk/content/configuration.mdtext Thu Jun 13 07:14:40 2013
@@ -22,16 +22,53 @@ Notice:    Licensed to the Apache Softwa
 
 # DeltaSpike Configuration Mechanism - Basics
 
+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.
+
+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)
+will get moved to the Production system. Thus we need a way to
+
+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].
+
+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.
+
+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.
+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.
+
+DeltaSpike also provides a mechanism to inject those configured values using `@ConfigProperty`
+
 ## ConfigResolver
 
-In some cases low-level configs are needed e.g. during the bootstrapping process of the CDI container. (Currently it's e.g. used for configuring the value of the current project-stage, configured values which can be used in the expressions for `@Exclude`,...) Usually it isn't used by users directly, but DeltaSpike needs such a low-level approach for several features. Therefore it's possible to use a so called `ConfigResolver` which resolves and caches `ConfigSource`s per application.
-The method `ConfigResolver#getPropertyValue` allows to provide a string based key and returns the configured value as `String` or `null` if no value has been found (`#getAllPropertyValues` has a similar contract but it returns a list which might be empty if there are no configured values for the given key). Optionally it's possible to provide a default value which gets retured instead of `null`.
+The `ConfigResolver` is the central point to pick up configured values in DeltaSpike.
+
+The method `ConfigResolver#getPropertyValue` allows to provide a string based key and
+returns the configured value as `String` or `null` if no value has been found.
+
+`ConfigResolver#getAllPropertyValues` 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:
 
     :::java
     ConfigResolver.getPropertyValue("myKey");
 
+
+There is a 2nd variant of all those methods where it is possible to provide a
+default value which gets returned instead of `null` or if the final result is an empty String.
+
+
 ### PropertyFileConfig
 
 TODO
@@ -39,7 +76,8 @@ TODO
 
 ## ConfigSource
 
-A `ConfigResolver` uses all configured implementations of `ConfigSource` to lookup the property in question.
+A `ConfigSource` is exactly what it's name says: a source for configured values.
+The `ConfigResolver` uses all configured implementations of `ConfigSource` to lookup the property in question.
 
 Per default there are implementations for the following config sources (listed in the lookup order):
 
@@ -57,25 +95,39 @@ Per default there are implementations fo
 
 ### Reordering of the default order of Config-Sources
 
-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 set the system property with the ordinal key 'deltaspike_ordinal' and the new value).
-
-Example with `/META-INF/apache-deltaspike.properties`: If the properties file/s should be used **before** the other implementations, you have to configure an ordinal > 400. That means, you have to add e.g. `deltaspike_ordinal=401`.
+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 set
+the system property with the ordinal key 'deltaspike_ordinal' and the new value).
+
+Example with `/META-INF/apache-deltaspike.properties`: If the properties file/s should be used
+**before** the other implementations, you have to configure an ordinal > 400.
+That means, you have to add e.g. `deltaspike_ordinal=401`.
 
 **Hint:**
 
-In case of **property files** which are supported by default (`/META-INF/apache-deltaspike.properties`) 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).
+In case of **property files** which are supported by default (`/META-INF/apache-deltaspike.properties`)
+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).
 
 ### Custom Config-Sources
 
-To add a custom config-source, you have to implement the interface `ConfigSourceProvider` (and `ConfigSource`) and activate the implementation of `ConfigSourceProvider` with the std. SPI mechanism provided by Java via the `ServiceLoader` (that means you have to create `/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSourceProvider` which contains the fully qualified class name of the custom implementation/s).
-
-If you have a simple standalone `ConfigSource` you can also register it directly by creating a file `/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSource` which contains the fully qualified class name of your `ConfigSource`.
-Please note that a single `ConfigSource` should be either registered directly or via a `ConfigSourceProvider`, but never both ways. 
+To add a custom config-source, you have to implement the interface `ConfigSourceProvider` (and `ConfigSource`)
+and activate the implementation of `ConfigSourceProvider` with the std. SPI mechanism provided
+by Java via the `ServiceLoader` (that means you have to create
+`/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSourceProvider` which contains
+the fully qualified class name of the custom implementation/s).
+
+If you have a simple standalone `ConfigSource` you can also register it directly by creating a file
+`/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSource`
+which contains the fully qualified class name of your `ConfigSource`.
+Please note that a single `ConfigSource` should be either registered directly or
+via a `ConfigSourceProvider`, but never both ways.
 
 
 **Important Hint:**
 
-Have a look at the abstract base-implementation of `ConfigSource` 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.
+Have a look at the abstract base-implementation of `ConfigSource` 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.
 
 ## Type-safe config
 

Modified: deltaspike/site/trunk/content/core.mdtext
URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/core.mdtext?rev=1492545&r1=1492544&r2=1492545&view=diff
==============================================================================
--- deltaspike/site/trunk/content/core.mdtext (original)
+++ deltaspike/site/trunk/content/core.mdtext Thu Jun 13 07:14:40 2013
@@ -22,6 +22,11 @@ Notice:    Licensed to the Apache Softwa
 
 # Core - API
 
+## DeltaSpike Configuration
+
+This is described in an own chapter solely targeting our [configuration] mechanics, API and SPI.
+
+
 ## BeanProvider
 
 The `BeanProvider` is a class which provides (static) util methods which allow to lookup beans if it isn't possible to inject them via `@Inject` 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.