Return-Path: X-Original-To: apmail-tamaya-commits-archive@minotaur.apache.org Delivered-To: apmail-tamaya-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 42181108F8 for ; Sat, 29 Nov 2014 08:21:56 +0000 (UTC) Received: (qmail 66967 invoked by uid 500); 29 Nov 2014 08:21:56 -0000 Delivered-To: apmail-tamaya-commits-archive@tamaya.apache.org Received: (qmail 66947 invoked by uid 500); 29 Nov 2014 08:21:56 -0000 Mailing-List: contact commits-help@tamaya.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@tamaya.incubator.apache.org Delivered-To: mailing list commits@tamaya.incubator.apache.org Received: (qmail 66938 invoked by uid 99); 29 Nov 2014 08:21:56 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 29 Nov 2014 08:21:56 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED,T_RP_MATCHES_RCVD X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO mail.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with SMTP; Sat, 29 Nov 2014 08:21:53 +0000 Received: (qmail 66810 invoked by uid 99); 29 Nov 2014 08:21:33 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 29 Nov 2014 08:21:33 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 1A03594D334; Sat, 29 Nov 2014 08:21:33 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: anatole@apache.org To: commits@tamaya.incubator.apache.org Message-Id: <14009374197540d397acb7c64bca4aa8@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: incubator-tamaya git commit: TAMAYA-8: added Javadocs and doku. Date: Sat, 29 Nov 2014 08:21:33 +0000 (UTC) X-Virus-Checked: Checked by ClamAV on apache.org 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 Authored: Sat Nov 29 09:21:22 2014 +0100 Committer: anatole 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: + *
    + *
  • The current valid Configuration is evaluated by calling {@code Configuration cfg = Configuration.of();}
    • + *
  • The current property String value is evaluated by calling {@code cfg.get("aValue");}
    • + *
  • if not successful, an error is thrown ({@link org.apache.tamaya.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 (controlled by {@link org.apache.tamaya.annot.WithLoadPolicy} + * annotations).
    • + *
+ * + * 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 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 }