Repository: incubator-tamaya
Updated Branches:
  refs/heads/master fa47e3c90 -> 6228b1719


TAMAYA-8: added Javadocs and doku.


Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/6228b171
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/6228b171
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/6228b171

Branch: refs/heads/master
Commit: 6228b17199f24690ba7c80b1343dc42e058b3511
Parents: fa47e3c
Author: anatole <anat...@apache.org>
Authored: Sat Nov 29 09:21:22 2014 +0100
Committer: anatole <anat...@apache.org>
Committed: Sat Nov 29 09:21:22 2014 +0100

----------------------------------------------------------------------
 .../tamaya/annot/ConfigChangeListener.java      |  36 +++++
 .../org/apache/tamaya/annot/ConfigChanged.java  |  33 ----
 .../tamaya/annot/ConfiguredProperties.java      |   4 +-
 .../apache/tamaya/annot/ConfiguredProperty.java |  43 +++++-
 ...DefaultConfigurationManagerSingletonSpi.java |   7 +-
 .../core/internal/inject/ConfiguredType.java    |   2 +-
 ...tionManagerSingletonSpiSingletonSpiTest.java | 151 +++++++++----------
 .../tamaya/core/env/EnvironmentManagerTest.java |  21 +--
 .../samples/annotations/ConfigTemplate.java     |   1 -
 .../samples/annotations/ConfiguredClass.java    |   4 +-
 docs/design/2_CoreConcepts.adoc                 |  51 +++++++
 .../apache/tamaya/ext/cdi/ConfiguredClass.java  |   4 +-
 12 files changed, 227 insertions(+), 130 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/api/src/main/java/org/apache/tamaya/annot/ConfigChangeListener.java
----------------------------------------------------------------------
diff --git 
a/api/src/main/java/org/apache/tamaya/annot/ConfigChangeListener.java 
b/api/src/main/java/org/apache/tamaya/annot/ConfigChangeListener.java
new file mode 100644
index 0000000..dcf895e
--- /dev/null
+++ b/api/src/main/java/org/apache/tamaya/annot/ConfigChangeListener.java
@@ -0,0 +1,36 @@
+/*
+ * 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.
+ */
+package org.apache.tamaya.annot;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to annotate a method on a class to be informed on config changes.
+ * The exact behaviour, when configuration change events are sent can be 
configured
+ * on each configured property/method by adding the {@link 
org.apache.tamaya.annot.WithLoadPolicy}
+ * annotation.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.METHOD })
+public @interface ConfigChangeListener {
+
+}

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/api/src/main/java/org/apache/tamaya/annot/ConfigChanged.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/ConfigChanged.java 
b/api/src/main/java/org/apache/tamaya/annot/ConfigChanged.java
deleted file mode 100644
index fbb1aa5..0000000
--- a/api/src/main/java/org/apache/tamaya/annot/ConfigChanged.java
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * 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.
- */
-package org.apache.tamaya.annot;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Annotation to annotate a method on a class to be informed on config changes.
- */
-@Retention(RetentionPolicy.RUNTIME)
-@Target(value = { ElementType.METHOD })
-public @interface ConfigChanged {
-
-}

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java
----------------------------------------------------------------------
diff --git 
a/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java 
b/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java
index 40a049d..f97b63b 100644
--- a/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java
+++ b/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java
@@ -24,7 +24,9 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation to enable injection of a configured property.
+ * Annotation to enable injection of multiple {@link 
org.apache.tamaya.annot.ConfiguredProperty}
+ * annotations. Hereby the ordering of annotations imply the defaulting. The 
first value that
+ * could be resolved successfully in the chain of annotations will be used.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.FIELD, ElementType.METHOD })

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperty.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperty.java 
b/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperty.java
index 478bed2..6b4320f 100644
--- a/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperty.java
+++ b/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperty.java
@@ -21,7 +21,48 @@ package org.apache.tamaya.annot;
 import java.lang.annotation.*;
 
 /**
- * Annotation to enable injection of a configured property.
+ * Annotation to enable injection of a configured property or define the 
returned data for
+ * a configuration template method. Hereby this annotation can be used in 
multiple ways and combined
+ * with other annotations such as {@link org.apache.tamaya.annot.DefaultValue},
+ * {@link org.apache.tamaya.annot.WithLoadPolicy}, {@link 
org.apache.tamaya.annot.WithConfig},
+ * {@link org.apache.tamaya.annot.WithConfigOperator}, {@link 
org.apache.tamaya.annot.WithPropertyAdapter}.
+ *
+ * Below the most simple variant of a configured class is given:
+ * {@code
+ * pubic class ConfiguredItem{
+ *
+ *   @ConfiguredProperty
+ *   private String aValue;
+ * }
+ * When this class is configured, e.g. by passing it to {@link 
org.apache.tamaya.Configuration#configure(Object)},
+ * the following is happening:
+ * <ul>
+ *     <li>The current valid Configuration is evaluated by calling {@code 
Configuration cfg = Configuration.of();}</li>
+ *     <li>The current property String value is evaluated by calling {@code 
cfg.get("aValue");}</li>
+ *     <li>if not successful, an error is thrown ({@link 
org.apache.tamaya.ConfigException}.</li>
+ *     <li>On success, since no type conversion is involved, the value is 
injected.</li>
+ *     <li>The configured bean is registered as a weak change listener in the 
config system's underlying
+ *     configuration, so future config changes can be propagated (controlled 
by {@link org.apache.tamaya.annot.WithLoadPolicy}
+ *     annotations).</li>
+ * </ul>
+ *
+ * In the next example we explicitly define the property value:
+ * {@code
+ * pubic class ConfiguredItem{
+ *
+ *   @ConfiguredProperty
+ *   @ConfiguredProperty("a.b.value")
+ *   @configuredProperty("a.b.deprecated.value")
+ *   @DefaultValue("${env:java.version}")
+ *   private String aValue;
+ * }
+ *
+ * Within this example we evaluate multiple possible keys. Evaluation is 
aborted if a key could be successfully
+ * resolved. Hereby the ordering of the annotations define the ordering of 
resolution, so in the example above
+ * resolution equals to {@code "aValue", "a.b.value", "a.b.deprecated.value"}. 
If no value could be read
+ * from the configuration, it uses the value from the {@code DefaultValue} 
annotation. Interesting here
+ * is that this value is not static, it is evaluated by calling
+ * {@link 
org.apache.tamaya.Configuration#evaluateValue(org.apache.tamaya.Configuration, 
String)}.
  */
 @Repeatable(ConfiguredProperties.class)
 @Retention(RetentionPolicy.RUNTIME)

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/core/src/main/java/org/apache/tamaya/core/internal/DefaultConfigurationManagerSingletonSpi.java
----------------------------------------------------------------------
diff --git 
a/core/src/main/java/org/apache/tamaya/core/internal/DefaultConfigurationManagerSingletonSpi.java
 
b/core/src/main/java/org/apache/tamaya/core/internal/DefaultConfigurationManagerSingletonSpi.java
index 34b9c30..aa1cfba 100644
--- 
a/core/src/main/java/org/apache/tamaya/core/internal/DefaultConfigurationManagerSingletonSpi.java
+++ 
b/core/src/main/java/org/apache/tamaya/core/internal/DefaultConfigurationManagerSingletonSpi.java
@@ -18,6 +18,7 @@
  */
 package org.apache.tamaya.core.internal;
 
+import org.apache.tamaya.core.internal.inject.ConfigurationInjector;
 import org.apache.tamaya.core.spi.ConfigurationProviderSpi;
 import org.apache.tamaya.core.spi.ExpressionEvaluator;
 
@@ -86,7 +87,7 @@ public class DefaultConfigurationManagerSingletonSpi 
implements ConfigurationMan
 
     @Override
     public void configure(Object instance) {
-        throw new UnsupportedOperationException("Not yet implemented.");
+        ConfigurationInjector.configure(instance);
     }
 
     private String getConfigId(Annotation... qualifiers) {
@@ -111,12 +112,12 @@ public class DefaultConfigurationManagerSingletonSpi 
implements ConfigurationMan
 
     @Override
     public void addPropertyChangeListener(PropertyChangeListener listener) {
-        throw new UnsupportedOperationException("Not yet implemented.");
+        Configuration.of().addPropertyChangeListener(listener);
     }
 
     @Override
     public void removePropertyChangeListener(PropertyChangeListener listener) {
-        throw new UnsupportedOperationException("Not yet implemented.");
+        Configuration.of().removePropertyChangeListener(listener);
     }
 
     @Override

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/core/src/main/java/org/apache/tamaya/core/internal/inject/ConfiguredType.java
----------------------------------------------------------------------
diff --git 
a/core/src/main/java/org/apache/tamaya/core/internal/inject/ConfiguredType.java 
b/core/src/main/java/org/apache/tamaya/core/internal/inject/ConfiguredType.java
index b84a3d4..56bbe6e 100644
--- 
a/core/src/main/java/org/apache/tamaya/core/internal/inject/ConfiguredType.java
+++ 
b/core/src/main/java/org/apache/tamaya/core/internal/inject/ConfiguredType.java
@@ -65,7 +65,7 @@ public class ConfiguredType {
             }
         }
         for (Method m : type.getDeclaredMethods()) {
-            ConfigChanged mAnnot = m.getAnnotation(ConfigChanged.class);
+            ConfigChangeListener mAnnot = 
m.getAnnotation(ConfigChangeListener.class);
             if(mAnnot!=null) {
                 if (m.getParameterTypes().length != 1) {
                     continue;

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/core/src/test/java/org/apache/tamaya/DefaultConfigurationManagerSingletonSpiSingletonSpiTest.java
----------------------------------------------------------------------
diff --git 
a/core/src/test/java/org/apache/tamaya/DefaultConfigurationManagerSingletonSpiSingletonSpiTest.java
 
b/core/src/test/java/org/apache/tamaya/DefaultConfigurationManagerSingletonSpiSingletonSpiTest.java
index f7ed72a..6ca1063 100644
--- 
a/core/src/test/java/org/apache/tamaya/DefaultConfigurationManagerSingletonSpiSingletonSpiTest.java
+++ 
b/core/src/test/java/org/apache/tamaya/DefaultConfigurationManagerSingletonSpiSingletonSpiTest.java
@@ -22,98 +22,95 @@ import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertTrue;
-import static org.junit.Assert.fail;
 
+import org.apache.tamaya.annot.ConfiguredProperty;
+import org.apache.tamaya.annot.DefaultValue;
 import org.apache.tamaya.core.internal.DefaultConfigurationManagerSingletonSpi;
 import org.junit.Test;
 
+import java.beans.PropertyChangeListener;
+
 /**
  * Test class for {@link 
org.apache.tamaya.core.internal.DefaultConfigurationManagerSingletonSpi}.
  */
-public class DefaultConfigurationManagerSingletonSpiSingletonSpiTest{
-
+public class DefaultConfigurationManagerSingletonSpiSingletonSpiTest {
 
+    private static final PropertyChangeListener LISTENER = System.out::println;
 
-       @Test
-       public void testSEConfigurationService() {
-               new DefaultConfigurationManagerSingletonSpi();
-       }
+    @Test
+    public void testSEConfigurationService() {
+        new DefaultConfigurationManagerSingletonSpi();
+    }
 
-       @Test
-       public void testGetConfigurationString() {
-               Configuration config = Configuration.of("default");
-               assertNotNull(config);
+    @Test
+    public void testGetConfigurationString() {
+        Configuration config = Configuration.of("default");
+        assertNotNull(config);
         assertTrue(config.toString().contains("default"));
         assertNotNull(config.getMetaInfo());
         assertTrue(config.getMetaInfo().toString().contains("default"));
         System.out.println("CONFIG: " + config);
-               assertEquals(System.getProperty("java.version"),
-                               config.get("java.version"));
-               
-               config = Configuration.of("system.properties");
-               assertNotNull(config);
+        assertEquals(System.getProperty("java.version"),
+                config.get("java.version").get());
+
+        config = Configuration.of("system.properties");
+        assertNotNull(config);
         assertNotNull(config.getMetaInfo());
         
assertTrue(config.getMetaInfo().toString().contains("system.properties"));
-               assertEquals(System.getProperty("java.version"),
-                               config.get("java.version"));
-       }
-
-       @Test
-       public void testGetConfigurationStringEnvironment() {
-               fail("Not yet implemented");
-       }
-
-       @Test
-       public void testIsConfigurationDefined() {
-               assertTrue(Configuration.isDefined("test"));
-               assertFalse(Configuration.isDefined("sdksajdsajdlkasj 
dlkjaslkd"));
-       }
-
-       @Test
-       public void testGetCurrentEnvironment() {
-               Environment env = Environment.of();
-               assertNotNull(env);
-               assertEquals(System.getProperty("java.version"),
-                               env.get("java.version").get());
-       }
-
-       @Test
-       public void testGetRootEnvironment() {
-               DefaultConfigurationManagerSingletonSpi s = new 
DefaultConfigurationManagerSingletonSpi();
-               Environment env =  Environment.getRootEnvironment();
-               assertNotNull(env);
-               assertEquals(System.getProperty("java.version"),
-                               env.get("java.version").get());
-       }
-
-       @Test
-       public void testQueryConfiguration() {
-               fail("Not yet implemented");
-       }
-
-       @Test
-       public void testCreateConfiguration() {
-               fail("Not yet implemented");
-       }
-
-       @Test
-       public void testUpdateConfiguration() {
-               fail("Not yet implemented");
-       }
-
-       @Test
-       public void testAddConfigChangeListener() {
-               fail("Not yet implemented");
-       }
-
-       @Test
-       public void testRemoveConfigChangeListener() {
-               fail("Not yet implemented");
-       }
-
-       @Test
-       public void testConfigure() {
-               fail("Not yet implemented");
-       }
+        assertEquals(System.getProperty("java.version"),
+                config.get("java.version").get());
+    }
+
+    @Test
+    public void testIsConfigurationDefined() {
+        assertTrue(Configuration.isDefined("test"));
+        assertFalse(Configuration.isDefined("sdksajdsajdlkasj dlkjaslkd"));
+    }
+
+    @Test
+    public void testGetCurrentEnvironment() {
+        Environment env = Environment.of();
+        assertNotNull(env);
+        assertEquals(System.getProperty("java.version"),
+                env.get("java.version").get());
+    }
+
+    @Test
+    public void testGetRootEnvironment() {
+        DefaultConfigurationManagerSingletonSpi s = new 
DefaultConfigurationManagerSingletonSpi();
+        Environment env = Environment.getRootEnvironment();
+        assertNotNull(env);
+        assertEquals(System.getProperty("java.version"),
+                env.get("java.version").get());
+    }
+
+    @Test
+    public void testAddRemoveGlobalConfigChangeListener() {
+        Configuration.addGlobalPropertyChangeListener(LISTENER);
+        Configuration.removeGlobalPropertyChangeListener(LISTENER);
+        Configuration.addGlobalPropertyChangeListener(LISTENER);
+        Configuration.addGlobalPropertyChangeListener(LISTENER);
+        Configuration.removeGlobalPropertyChangeListener(LISTENER);
+        Configuration.removeGlobalPropertyChangeListener(LISTENER);
+        Configuration.removeGlobalPropertyChangeListener(LISTENER);
+    }
+
+    @Test
+    public void testConfigure() {
+        ConfigureTest test = new ConfigureTest();
+        Configuration.configure(test);
+        assertEquals(test.mustBeTrue, true);
+        assertEquals(test.val1, "YES, it works!");
+    }
+
+    private static class ConfigureTest {
+        @ConfiguredProperty
+        @DefaultValue("YES, it works!")
+        String val1;
+
+        @ConfiguredProperty
+        @DefaultValue("true")
+        boolean mustBeTrue;
+    }
 
 }

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/core/src/test/java/org/apache/tamaya/core/env/EnvironmentManagerTest.java
----------------------------------------------------------------------
diff --git 
a/core/src/test/java/org/apache/tamaya/core/env/EnvironmentManagerTest.java 
b/core/src/test/java/org/apache/tamaya/core/env/EnvironmentManagerTest.java
index 341b6ef..0e57b66 100644
--- a/core/src/test/java/org/apache/tamaya/core/env/EnvironmentManagerTest.java
+++ b/core/src/test/java/org/apache/tamaya/core/env/EnvironmentManagerTest.java
@@ -75,21 +75,24 @@ public class EnvironmentManagerTest {
         List<String> envOrder = Environment.getEnvironmentHierarchy();
         assertNotNull(envOrder);
         assertTrue(envOrder.size()>0);
-        assertTrue(envOrder.contains("root(root)"));
-        assertTrue(envOrder.contains("system(system)"));
-        assertTrue(envOrder.contains("myEar1(ear)"));
-        assertTrue(envOrder.contains("MyApp1(application)"));
-        assertTrue(envOrder.get(0).equals("MyApp1(application)"));
+        assertTrue(envOrder.contains("root"));
+        assertTrue(envOrder.contains("system"));
+        assertTrue(envOrder.contains("myEar1"));
+        assertTrue(envOrder.contains("MyApp1"));
+        assertTrue(envOrder.get(0).equals("MyApp1"));
     }
 
     @Test
     public void testEnvironmentId(){
         String envId = Environment.of().getEnvironmentId();
         assertNotNull(envId);
-        assertTrue(envId.contains("root(root)"));
-        assertTrue(envId.contains("system(system)"));
-        assertTrue(envId.contains("myEar1(ear)"));
-        assertTrue(envId.contains("MyApp1(application)"));
+        assertEquals(envId, "MyApp1");
+        envId = Environment.of().getParentEnvironment().getEnvironmentId();
+        assertEquals(envId, "myEar1");
+        envId = 
Environment.of().getParentEnvironment().getParentEnvironment().getEnvironmentId();
+        assertEquals(envId, "system");
+        envId = Environment.getRootEnvironment().getEnvironmentId();
+        assertEquals(envId, "root");
     }
 
     @Test

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/core/src/test/java/org/apache/tamaya/samples/annotations/ConfigTemplate.java
----------------------------------------------------------------------
diff --git 
a/core/src/test/java/org/apache/tamaya/samples/annotations/ConfigTemplate.java 
b/core/src/test/java/org/apache/tamaya/samples/annotations/ConfigTemplate.java
index 5ef226a..8d9e89b 100644
--- 
a/core/src/test/java/org/apache/tamaya/samples/annotations/ConfigTemplate.java
+++ 
b/core/src/test/java/org/apache/tamaya/samples/annotations/ConfigTemplate.java
@@ -18,7 +18,6 @@
  */
 package org.apache.tamaya.samples.annotations;
 
-import org.apache.tamaya.annot.ConfigChanged;
 import org.apache.tamaya.annot.ConfiguredProperty;
 import org.apache.tamaya.annot.DefaultValue;
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/core/src/test/java/org/apache/tamaya/samples/annotations/ConfiguredClass.java
----------------------------------------------------------------------
diff --git 
a/core/src/test/java/org/apache/tamaya/samples/annotations/ConfiguredClass.java 
b/core/src/test/java/org/apache/tamaya/samples/annotations/ConfiguredClass.java
index fc3098f..1480e9a 100644
--- 
a/core/src/test/java/org/apache/tamaya/samples/annotations/ConfiguredClass.java
+++ 
b/core/src/test/java/org/apache/tamaya/samples/annotations/ConfiguredClass.java
@@ -18,7 +18,7 @@
  */
 package org.apache.tamaya.samples.annotations;
 
-import org.apache.tamaya.annot.ConfigChanged;
+import org.apache.tamaya.annot.ConfigChangeListener;
 import org.apache.tamaya.annot.ConfiguredProperty;
 import org.apache.tamaya.annot.DefaultValue;
 import org.apache.tamaya.annot.WithConfig;
@@ -69,7 +69,7 @@ public class ConfiguredClass{
     @ConfiguredProperty("BD")
     private BigDecimal bigNumber;
 
-    @ConfigChanged
+    @ConfigChangeListener
     public void changeListener1(PropertyChangeEvent configChange){
         // will be called
     }

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/docs/design/2_CoreConcepts.adoc
----------------------------------------------------------------------
diff --git a/docs/design/2_CoreConcepts.adoc b/docs/design/2_CoreConcepts.adoc
index c7eb766..5becc30 100644
--- a/docs/design/2_CoreConcepts.adoc
+++ b/docs/design/2_CoreConcepts.adoc
@@ -429,6 +429,55 @@ ConfigSecurity securityContext = 
Configuration.of().query(ConfigSecurity::target
 
 NOTE: +ConfigSecurity+ is an arbitrary class.
 
+=== Configuration Injection
+
+The +Configuration+ interface provides static methods that allow to anykind of 
instances be configured
+ny just passing the instances calling +Configuration.configure(instance);+. 
The classes passed hereby must
+be annotated with +@ConfiguredProperty+ to define the configured properties. 
Hereby this annotation can be
+used in multiple ways and combined with other annotations such as 
+@DefaultValue+,
++@WithLoadPolicy+, +@WithConfig+, +@WithConfigOperator+, 
+@WithPropertyAdapter+.
+
+To illustrate the mechanism below the most simple variant of a configured 
class is given:
+
+[source,java]
+.Most simple configured class
+--------------------------------------------
+pubic class ConfiguredItem{
+  @ConfiguredProperty
+  private String aValue;
+}
+--------------------------------------------
+
+When this class is configured, e.g. by passing it to 
+Configuration.configure(Object)+,
+the following is happening:
+
+* The current valid +Configuration+ is evaluated by calling +Configuration cfg 
= Configuration.of();+
+* The current property value (String) is evaluated by calling 
+cfg.get("aValue");+
+* if not successful, an error is thrown (+ConfigException+)
+* On success, since no type conversion is involved, the value is injected.
+* The configured bean is registered as a weak change listener in the config 
system's underlying
+  configuration, so future config changes can be propagated (controllable by 
applying the
+  +@WithLoadPolicy+ annotation).
+
+In the next example we explicitly define the property value:
+[source,java]
+--------------------------------------------
+pubic class ConfiguredItem{
+
+  @ConfiguredProperty
+  @ConfiguredProperty("a.b.value")
+  @configuredProperty("a.b.deprecated.value")
+  @DefaultValue("${env:java.version}")
+  private String aValue;
+}
+--------------------------------------------
+
+Within this example we evaluate multiple possible keys. Evaluation is aborted 
if a key could be successfully
+resolved. Hereby the ordering of the annotations define the ordering of 
resolution, so in the example above
+resolution equals to +"aValue", "a.b.value", "a.b.deprecated.value"+. If no 
value could be read
+from the configuration, it uses the value from the +@DefaultValue+ annotation. 
Interesting here
+is that this value is not static, it is evaluated by calling 
+Configuration.evaluateValue(Configuration, String)+.
+
 === Environment
 
 The environment basically is also a kind of property/value provider similar to 
+System.getProperties()+ and +System
@@ -505,3 +554,5 @@ System.out.println(env.getEnvironmentId());      // system
 env = env.getParentEnvironment();
 // env is null now!
 --------------------------------------------
+
+

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/6228b171/modules/cdi/src/test/java/org/apache/tamaya/ext/cdi/ConfiguredClass.java
----------------------------------------------------------------------
diff --git 
a/modules/cdi/src/test/java/org/apache/tamaya/ext/cdi/ConfiguredClass.java 
b/modules/cdi/src/test/java/org/apache/tamaya/ext/cdi/ConfiguredClass.java
index ef737ef..3b62f4b 100644
--- a/modules/cdi/src/test/java/org/apache/tamaya/ext/cdi/ConfiguredClass.java
+++ b/modules/cdi/src/test/java/org/apache/tamaya/ext/cdi/ConfiguredClass.java
@@ -1,6 +1,6 @@
 package org.apache.tamaya.ext.cdi;
 
-import org.apache.tamaya.annot.ConfigChanged;
+import org.apache.tamaya.annot.ConfigChangeListener;
 import org.apache.tamaya.annot.ConfiguredProperty;
 import org.apache.tamaya.annot.DefaultValue;
 import org.apache.tamaya.annot.WithConfig;
@@ -58,7 +58,7 @@ public class ConfiguredClass{
     @ConfiguredProperty("double1")
     private double doubleValue;
 
-    @ConfigChanged
+    @ConfigChangeListener
     public void changeListener1(PropertyChangeEvent configChange){
         // will be called
     }

Reply via email to