deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From strub...@apache.org
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

URL: http://svn.apache.org/r1492573
Log:
improve ConfigSource documentation

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=1492573&r1=1492572&r2=1492573&view=diff
==============================================================================
--- 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
order):
 
-  - System properties
-  - Environment properties
-  - JNDI values
-  - Properties file values (apache-deltaspike.properties)
+  - 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 (apache-deltaspike.properties) (deltaspike_ordinal = 100, default
filename is "META-INF/apache-deltaspike.properties")
 
 **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!
+
 **Hint:**
 
 In case of **property files** which are supported by default (`/META-INF/apache-deltaspike.properties`)
@@ -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
 `/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSource`
-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
way.
+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 `myproject.properties` 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
-
-TODO
-
-
-
-## 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 "myconfig.properties";
+        }
+    }
+
+
+## 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;
 
-TODO
+        ...
+     }
 



Mime
View raw message