deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1492573 - /deltaspike/site/trunk/content/configuration.mdtext
Date Thu, 13 Jun 2013 08:50:23 GMT
Author: struberg
Date: Thu Jun 13 08:50:22 2013
New Revision: 1492573

improve ConfigSource documentation


Modified: deltaspike/site/trunk/content/configuration.mdtext
--- deltaspike/site/trunk/content/configuration.mdtext (original)
+++ deltaspike/site/trunk/content/configuration.mdtext Thu Jun 13 08:50:22 2013
@@ -134,12 +134,21 @@ default value which gets returned instea
 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.
+Each 'ConfigSource' has a specified 'ordinal' which can be configured using the key `deltaspike_ordinal`.
+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 `deltaspike_ordinal` than the ones who pickup the
values from
+within the release binaries.
+### ConfigSources provided by default
 Per default there are implementations for the following config sources (listed in the lookup
-  - System properties
-  - Environment properties
-  - JNDI values
-  - Properties file values (
+  - System properties (deltaspike_ordinal = 400)
+  - Environment properties (deltaspike_ordinal = 300)
+  - JNDI values (deltaspike_ordinal = 200, the base name is "java:comp/env/deltaspike/")
+  - Properties file values ( (deltaspike_ordinal = 100, default
filename is "META-INF/")
 **It's possible to change this order and to add custom config sources.**
@@ -158,6 +167,9 @@ Example with `/META-INF/apache-deltaspik
 **before** the other implementations, you have to configure an ordinal > 400.
 That means, you have to add e.g. `deltaspike_ordinal=401`.
+Each single property file is treated as own `ConfigSource` and thus can have different
+`deltaspike_ordinal` values!
 In case of **property files** which are supported by default (`/META-INF/`)
@@ -165,15 +177,17 @@ every file is handled as independent con
 ## 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).
+ConfigSources are picked up using the `java.util.ServiceLoader' mechanism.
-If you have a simple standalone `ConfigSource` you can also register it directly by creating
a file
+To add a custom config-source, you have to implement the interface `ConfigSource` and register
+your implementation in a file
-which contains the fully qualified class name of your `ConfigSource`.
+by writing the fully qualified class name of the custom implementation/s into it.
+If you need dynamic ConfigSources you can also register a `ConfigSourceProvider` in a similar
+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 `` files from all the JARs in your classpath.
 Please note that a single `ConfigSource` should be either registered directly or
 via a `ConfigSourceProvider`, but never both ways.
@@ -184,15 +198,41 @@ Have a look at the abstract base-impleme
 if a custom implementation should load the ordinal value from the config-source
 like the default implementations provided by DeltaSpike do.
-## PropertyFileConfig
-## Type-safe config
+### PropertyFileConfig
-### @ConfigProperty
+For registering all your own property files of a certain name in your classpath
+to get picked up as `ConfigSource`s you can also provide a class
+which implements the `PropertyFileConfig` interface.
+    :::java
+    public class MyCustomPropertyFileConfig implements PropertyFileConfig
+    {
+        @Override
+        public String getPropertyFileName()
+        {
+            return "";
+        }
+    }
+## Type-safe configuration
+DeltaSpike provides a way to directly inject configured values into your code
+via the qualifier `@ConfigProperty`.
+    :::java
+    @ApplicationScoped
+    public class SomeRandomService
+    {
+        @Inject
+        @ConfigProperty(name = "endpoint.poll.interval")
+        private Integer pollInterval;
+        @Inject
+        @ConfigProperty(name = "endpoint.poll.servername")
+        private String pollUrl;
+        ...
+     }

View raw message