Author: struberg
Date: Sun Jun 9 18:31:27 2013
New Revision: 1491257
URL: http://svn.apache.org/r1491257
Log:
separate configuration docs from core
Added:
deltaspike/site/trunk/content/configuration.mdtext (with props)
Added: deltaspike/site/trunk/content/configuration.mdtext
URL:
http://svn.apache.org/viewvc/deltaspike/site/trunk/content/configuration.mdtext?rev=1491257&view=auto
==============================================================================
--- deltaspike/site/trunk/content/configuration.mdtext (added)
+++ deltaspike/site/trunk/content/configuration.mdtext Sun Jun 9 18:31:27 2013
@@ -0,0 +1,85 @@
+Title: Configuration
+Notice: 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
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" 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.
+
+[TOC]
+
+***
+
+# DeltaSpike Configuration Mechanism - Basics
+
+## 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`.
+
+Simple lookup in the low-level config:
+
+ :::java
+ ConfigResolver.getPropertyValue("myKey");
+
+### PropertyFileConfig
+
+TODO
+
+
+## ConfigSource
+
+A `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):
+
+ - System properties
+ - Environment properties
+ - JNDI values
+ - Properties file values (apache-deltaspike.properties)
+
+**It's possible to change this order and to add custom config sources.**
+
+**Note:** Important Hints esp. for custom implementations:
+ - The config-source with the highest ordinal gets used first.
+ - If a custom implementation should be invoked *before* the default
implementations, use an ordinal-value > 400
+ - If a custom implementation should be invoked *after* the default
implementations, use an ordinal-value < 100
+
+### 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`.
+
+**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).
+
+### 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.
+
+
+**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.
+
+## Type-safe config
+
+### @ConfigProperty
+
+TODO
+
Propchange: deltaspike/site/trunk/content/configuration.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
