tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject incubator-tamaya-site git commit: Improved docs.
Date Fri, 10 Feb 2017 21:57:43 GMT
Repository: incubator-tamaya-site
Updated Branches:
  refs/heads/master 9d5fb59c8 -> 7708b830f


Improved docs.


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

Branch: refs/heads/master
Commit: 7708b830ffff3a7da0ceb0bc7b95d713fc6c7e02
Parents: 9d5fb59
Author: anatole <anatole@apache.org>
Authored: Fri Feb 10 22:57:36 2017 +0100
Committer: anatole <anatole@apache.org>
Committed: Fri Feb 10 22:57:36 2017 +0100

----------------------------------------------------------------------
 .../documentation/extensions/mod_events.adoc    |  86 +++---
 .../documentation/extensions/mod_filter.adoc    |   7 +-
 .../documentation/extensions/mod_formats.adoc   |  29 +-
 .../documentation/extensions/mod_injection.adoc | 271 ++++++++++++-------
 4 files changed, 240 insertions(+), 153 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7708b830/content/documentation/extensions/mod_events.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_events.adoc b/content/documentation/extensions/mod_events.adoc
index 880d80d..8ef0dcf 100644
--- a/content/documentation/extensions/mod_events.adoc
+++ b/content/documentation/extensions/mod_events.adoc
@@ -45,13 +45,13 @@ To benefit from configuration event support you only must add the corresponding
 
 === Core Architecture
 
-The core of the module are the +ConfigEventListener+ interface and the +ConfigEvent+ class,
which defines an abstraction
-for event handling and observation:
+The core of the module are the +ConfigEventListener+ and the +ConfigEvent+ interfaces,
+which defines an abstraction for event handling and observation:
 
 [source,java]
 .ConfigEvent
 --------------------------------------------
-public final interface ConfigEvent<T> {
+public interface ConfigEvent<T> {
 
     Class<T> getResourceType();
     T getResource();
@@ -78,7 +78,44 @@ Google _Guava_ library. But users can replace this mechanism as needed.
For
 more details refer to the SPI section later in this guide.
 
 
-=== Modelling Changes
+=== The ConfigEventManager Singleton
+
+Main entry point of the events module is the +ConfigEventManager+ singleton class, which
provides static accessor
+methods to the extension's functionality:
+
+* _Adding/removing_ of +ConfigChangeListener+ instances, either globally or per event type.
+* _Firing configuration events_ synchronously or asyncronously (mostly called by framework
code).
+* _Configuring the monitor_ that periodically checks for changes on the global +Configuration+
provided
+  by +ConfigurationProvider.getConfiguration()+.
+
+[source,java]
+-------------------------------------------------------
+public final class ConfigEventManager {
+
+    private ConfigEventManager() {}
+
+    public static void addListener(ConfigEventListener l);
+    public static <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T>
eventType);
+    public static void removeListener(ConfigEventListener l);
+    public static <T extends ConfigEvent> void removeListener(ConfigEventListener l,
Class<T> eventType);
+    public static <T extends ConfigEvent>
+        Collection<? extends ConfigEventListener> getListeners();
+    public static <T extends ConfigEvent>
+        Collection<? extends ConfigEventListener> getListeners(Class<T> type);
+
+    public static <T> void fireEvent(ConfigEvent<?> event);
+    public static <T> void fireEventAsynch(ConfigEvent<?> event);
+
+    public static void enableChangeMonitoring(boolean enable);
+    public static boolean isChangeMonitoring();
+    public long getChangeMonitoringPeriod();
+    public void setChangeMonitoringPeriod(long millis);
+
+}
+-------------------------------------------------------
+
+
+=== Modelling configuration changes as events
 
 This module provides a serializable and thread-safe abstraction modelling a
 configuration change, which is anything of the following
@@ -200,47 +237,10 @@ e.g. by a configuration file edited on the fly. This is similarly to
a
 PropertySourceChangeBuilder+.
 
 
-=== The ConfigEventManager Singleton
-
-Main entry point of the events module is the +ConfigEventManager+ singleton class, which
provides static accessor
-methods to the extension's functionality:
-
-* _Adding/removing_ of +ConfigChangeListener+ instances, either globally or per event type.
-* _Firing configuration events_ synchronously or asyncronously (mostly called by framework
code).
-* _Configuring the monitor_ that periodically checks for changes on the global +Configuration+
provided
-  by +ConfigurationProvider.getConfiguration()+.
-
-[source,java]
--------------------------------------------------------
-public final class ConfigEventManager {
-
-    private ConfigEventManager() {}
-
-    public static void addListener(ConfigEventListener l);
-    public static <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T>
eventType);
-    public static void removeListener(ConfigEventListener l);
-    public static <T extends ConfigEvent> void removeListener(ConfigEventListener l,
Class<T> eventType);
-    public static <T extends ConfigEvent>
-        Collection<? extends ConfigEventListener> getListeners();
-    public static <T extends ConfigEvent>
-        Collection<? extends ConfigEventListener> getListeners(Class<T> type);
-
-    public static <T> void fireEvent(ConfigEvent<?> event);
-    public static <T> void fireEventAsynch(ConfigEvent<?> event);
-
-    public static void enableChangeMonitoring(boolean enable);
-    public static boolean isChangeMonitoring();
-    public long getChangeMonitoringPeriod();
-    public void setChangeMonitoringPeriod(long millis);
-
-}
--------------------------------------------------------
-
-
 ==== Monitoring of configuration changes
 
-The +ConfigEventManager+ also supports active monitoring of the current configuration to
trigger corresponding change
-events to listeners registered. This feature is deactivated by default, but can be enabled
by calling
+The +ConfigEventManager+ supports *active monitoring of the current configuration* to trigger
corresponding change
+events to listeners registered. *This feature is deactivated by default*, but can be enabled
by calling
 +ConfigEventManager.enableChangeMonitoring(true);+. This feature avoids regularly polling
your local +Configuration+ for
 any kind of changes. If a change has been encountered Tamaya identifies it and triggers corresponding
 +ConfigurationChange+ events automatically.

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7708b830/content/documentation/extensions/mod_filter.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_filter.adoc b/content/documentation/extensions/mod_filter.adoc
index 581f33d..3595cd4 100644
--- a/content/documentation/extensions/mod_filter.adoc
+++ b/content/documentation/extensions/mod_filter.adoc
@@ -15,7 +15,8 @@ Tamaya _Filter_ is an extension module. Refer to the link:../extensions.html[ext
 === What functionality this module provides ?
 
 Tamaya _Filter_ provides a simple singleton accessor that allows to explicitly add +PropertyFilter+
instances
-active on the current thread only. This can be very useful in many scenarios. Additionally
this module adds
+active on the current thread only. This can be very useful in many scenarios, especially
within
+Java EE web filters or similar. Additionally this module adds
 standard filters that hide metadata entries when the full configuration map is accessed.
When keys are accessed
 explicitily no filtering is applied and everything is visible.
 
@@ -26,7 +27,7 @@ The module is based on Java 7, so it will not run on Java 7 and beyond.
 
 === Installation
 
-To benefit from configuration builder support you only must add the corresponding dependency
to your module:
+To benefit from filter support you only must add the corresponding dependency to your module:
 
 [source, xml]
 -----------------------------------------------
@@ -48,7 +49,7 @@ instances on the current thread.
  an underscore ('_'), when a full property map is accessed.
 
 
-=== The ConfigurationFilter
+==== The ConfigurationFilter
 
 The accessor mentioned implements the API for for adding +PropertyFilters+ to the current
thread (as thread local):
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7708b830/content/documentation/extensions/mod_formats.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_formats.adoc b/content/documentation/extensions/mod_formats.adoc
index f87b720..073b4aa 100644
--- a/content/documentation/extensions/mod_formats.adoc
+++ b/content/documentation/extensions/mod_formats.adoc
@@ -28,7 +28,7 @@ The module is based on Java 7, so it can be used with Java 7 and beyond.
 
 === Installation
 
-To benefit from dynamic value resolution you only must add the corresponding dependency to
your module:
+To use the formats module you only must add the corresponding dependency to your module:
 
 [source, xml]
 -----------------------------------------------
@@ -40,10 +40,17 @@ To benefit from dynamic value resolution you only must add the corresponding
dep
 -----------------------------------------------
 
 
-=== The Idea
+=== Basic Concept
 
 Formats should be reusable, meaning you should have to write a format parser only once and
then be able to map the data read into whatever
-data structure (in our cases: property sources).
+data structure (in our cases: property sources). So it is useful to separate concerns into
+
+* an arbitrary configuration format (textual or binary)
+* a parser (+ConfigurationFormat+) that transfers a given format into an intermediate
+  representation (+ConfigurationData+).
+* an optional customization, implemented by a _factory method pattern_ to adapt the mapping
of +ConfigurationData+ read
+  to a collection of +PropertySources+ (they can have different ordinal semantics).
+
 
 ==== ConfigurationData
 
@@ -105,7 +112,7 @@ public interface ConfigurationFormat {
 -------------------------------------------------------
 
 
-=== How to tranform ConfigurationData into a PropertySource
+=== Customize how ConfigurationData maps to PropertySource
 
 For for the conversion of +ConfigurationData+ into a +PropertySource+ different approaches
can be useful:
 
@@ -137,6 +144,20 @@ with a 'default', 'main', and 'overrides' sections). For such more complex
or cu
 can be defined. Consequently the functionality mapping the normalized +ConfigurationData+
read to the
 appropriate collection of +PropertySource+ instances must be implemented.
 
+For this scenario the +BaseFormatPropertySourceProvider+ can be used, defining the following
mapping
+function that mus be implemented:
+
+[source,java]
+-------------------------------------------------------
+/**
+ * Method to create a {@link org.apache.tamaya.spi.PropertySource} based on the given entries
read.
+ *
+ * @param data the configuration data, not null.
+ * @return the {@link org.apache.tamaya.spi.PropertySource} instance ready to be registered.
+ */
+protected abstract Collection<PropertySource> getPropertySources(ConfigurationData
data);
+-------------------------------------------------------
+
 
 === Examples
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7708b830/content/documentation/extensions/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_injection.adoc b/content/documentation/extensions/mod_injection.adoc
index 2699065..ceb1986 100644
--- a/content/documentation/extensions/mod_injection.adoc
+++ b/content/documentation/extensions/mod_injection.adoc
@@ -51,9 +51,8 @@ To use injection with Java SE you must add the corresponding dependency
to your
 
 Similarly there are other injection implementations available, targetig platforms such as
 
-* Spring, Spring Boot
-* Java EE/CDI
-* OSGI, Apache Felix/Apache Karaf
+* link:mod_spring.html[Spring, Spring Boot]
+* link:mod_CDI.html[Java EE/CDI]
 
 
 === Core Concepts
@@ -147,34 +146,11 @@ with CDI, Spring or within an OSGI container. For further details refer
also to
 documentation.
 
 
-=== The Annotations in detail
 ==== The ConfigurationInjector
 
 The +ConfigurationInjector+ interface provides methods that allow any kind of instances to
be configured
 by passing the instances to +T ConfigurationInjector.getInstance().configure(T);+. The classes
passed
-hereby must not be annotated with +@Config+ for being configurable. By default Tamaya
-tries to determine configuration for each property of an instance passed, using the following
resolution policy:
-
-Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the following keys:
-[source, listing]
---------------------------------------------
-a.b.MyClass.myField
-a.b.MyClass.my-field
-MyClass.myField
-MyClass.my-field
-myField
-my-field
---------------------------------------------
-
-So given the following properties:
-
-[source, properties]
---------------------------------------------
-a.b.Tenant.id=1234
-Tenant.description=Any kind of tenant.
-name=<unnamed>
---------------------------------------------
-
+hereby must not be annotated with +@Config+ for being configurable.
 
 ==== Accessing Supplier instances
 
@@ -202,6 +178,7 @@ Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().
 Hereby this annotation can be used in multiple ways and combined with other annotations such
as
 +@WithLoadPolicy+, +@WithConfigOperator+, +@WithPropertyConverter+.
 
+
 ==== Minimal Example
 
 To illustrate the mechanism below the most simple variant of a configured class is given:
@@ -224,102 +201,96 @@ the following is happening:
 * if not successful, an error is thrown (+ConfigException+)
 * On success, since no type conversion is involved, the value is injected.
 
-==== Using @DefaultValue
 
-In the next example we explicitly define the property value:
-[source,java]
---------------------------------------------
-pubic class ConfiguredItem{
+=== The Annotations in detail
 
-  @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
-  private String aValue;
-}
---------------------------------------------
+==== Using `@Config`
 
-==== Inject a DynamicValue Property
+This is the main annotation targeting a field in a class for configuration injection.
 
-Within this example we evaluate a dynamic value. This mechanism allows you to listen for
configuration changes and to
-commit new values exactly, when convenient for you.
+===== Evaluating of _configuration keys_
 
-[source,java]
---------------------------------------------
-pubic class ConfiguredItem{
+By default Tamaya tries to determine configuration for each property of an instance
+passed, using the following resolution policy:
 
-  @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
-  private DynamicValue aValue;
-}
+* Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the
+  following keys:
+
+[source, listing]
+--------------------------------------------
+a.b.MyClass.myField
+a.b.MyClass.my-field
+MyClass.myField
+MyClass.my-field
+myField
+my-field
 --------------------------------------------
 
-The +DynamicValue+ provides you the following functionality:
 
-[source,java]
---------------------------------------------
-public interface DynamicValue<T> {
+This behaviour can be adapted, e.g. by using the `@ConfigDefaultSections` annotation on the
+declaring type:
 
-    enum UpdatePolicy{
-        IMMEDIATE,
-        EXPLCIT,
-        NEVER,
-        LOG_AND_DISCARD
-    }
+--------------------------------------------
+@ConfigDefaultSections("a.b.c", "deprecated")
+pubic class MyClass{
+  @Config
+  private String myField;
+}
+--------------------------------------------
 
-    T get();
-    T getNewValue();
-    T evaluateValue();
-    T commitAndGet();
-    void commit();
-    void discard();
-    boolean updateValue();
+This will result in a modified lookup chain as illustrated below:
 
-    void setUpdatePolicy(UpdatePolicy updatePolicy);
-    UpdatePolicy getUpdatePolicy();
-    void addListener(PropertyChangeListener l);
-    void removeListener(PropertyChangeListener l);
+[source, listing]
+--------------------------------------------
+a.b.c.myField
+a.b.c.my-field
+deprecated.myField
+deprecated.my-field
+--------------------------------------------
 
-    boolean isPresent();
-    T orElse(T other);
-    // Enabled with Java 8
-    // T orElseGet(ConfiguredItemSupplier<? extends T> other);
-    // <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X>
exceptionSupplier) throws X;
+This helps to reduce redundancy when referring to you configuration keys. Additionally
+it is also possible to define absolute key entries, e.g.
 
+--------------------------------------------
+@ConfigDefaultSections("a.b.c")
+pubic class MyClass{
+  @Config("myField" /* relative */, "[absolute.key]")
+  private String myField;
 }
 --------------------------------------------
 
-Summarizing this class looks somehow similar to the new +Optional+ class added with Java
8. It provides
-a wrapper class around a configured instance. Additionally this class provides functionality
that gives
-active control, to manage a configured value based on a ++LoadingPolicy+:
+This will result in a lookup chain as illustrated below:
 
-* +IMMEDEATE+ means that when the configuration system detects a change on the underlying
value, the new value
-  is automatically applied without any further notice.
-* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+
property. if +getNewValue()+
-  returns a non null value, the new value can be applied by calling +commit()+. You can always
access the newest value,
-  hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible
ti ignore a change by calling
-  +discard()+.
-* +NEVER+ means the configured value is evaluated once and never updated. All changes are
silently discarded.
-* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.
+[source, listing]
+--------------------------------------------
+a.b.c.myField
+absolute.key # default sections are ignored
+--------------------------------------------
 
-Summarizing a +DynamicValue+ allows you
 
-* to reload actively updates of configured values.
-* update implicitly or explicitly all changes on the value.
-* add listeners that observe changes of a certain value.
+===== Using defaults
 
-Dynamic values also allow on-the-fly reevaluation of the value by calling +evaluateValue()+.
Hereby the value of the
-instance is not changed.
+In the next example we explicitly define the _default_ property value:
+[source,java]
+--------------------------------------------
+pubic class ConfiguredItem{
 
+  @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
+  private String aValue;
+}
+--------------------------------------------
 
-==== Ommitting Injection using @NoConfig
 
-Adding the @NoConfig annotation prevents a field or method to be auto-injected from
-configuration. This is especially useful, if a type is annotated as @ConfigAutoInject with
auto-confiuration
-turned on as follows:
+==== Automatically inject all items using `@ConfigAutoInject`
+
+Using `@ConfigAutoInject` allows you to automatically select all properties found for
+configuration injection:
 
 [source,java]
 --------------------------------------------
 @ConfigAutoInject
 pubic class ConfiguredItem{
 
-  @NoConfig
   private transient int sum;
 
   private String a;
@@ -328,10 +299,21 @@ pubic class ConfiguredItem{
 }
 --------------------------------------------
 
+Adding the `@NoConfig` annotation prevents a field or method to be auto-injected from
+configuration. This is especially useful, if a type is annotated as @ConfigAutoInject with
auto-confiuration
+turned on as follows:
+
+[source,java]
+--------------------------------------------
+@NoConfig
+private transient int sum;
+--------------------------------------------
+
 In this case the fields +a,b,c+ are configured, whereas the field +sum+ is ignored regarding
 configuration.
 
-==== Adding custom operators using @WithConfigOperator
+
+==== Adding custom operators using `@WithConfigOperator`
 
 The @WithConfigOperator annotation allows you define a class of type +ConfigOperator+, to
being applied
 to the final +Configuration+, BEFORE the value is injected. This can be used for various
use cases, e.g.
@@ -350,7 +332,7 @@ pubic class ConfiguredItem{
 --------------------------------------------
 
 
-==== Adding custom property converters using @WithPropertyConverter
+==== Adding custom property converters using `@WithPropertyConverter`
 
 The @WithPropertyConverter annotation allows you to define a class of type +PropertyConverter+,
to be applied
 on a property configured to convert the String value to the expected injected type. This
can be used for
@@ -369,24 +351,107 @@ pubic class ConfiguredItem{
 --------------------------------------------
 
 
-==== Defining the loading policy to be applied to configured values using @WithLoadPolicy
+==== Inject a `DynamicValue`
 
-The @WithLoadPolicy annotation allows to define the loading behaviour to be applied. The
+LoadPolicy+
-enum hereby defines the various loading modes.
+Within this example we evaluate a dynamic value. This mechanism allows you to listen for
configuration changes and to
+commit new values exactly, when convenient for you.
 
 [source,java]
 --------------------------------------------
+pubic class ConfiguredItem{
 
-@WithLoadPolicy(LoadPolicy.NEVER)
-pubic class BootTimeStableConfig{
+  @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
+  private DynamicValue aValue;
+}
+--------------------------------------------
 
-  @WithPropertyConverter(MyPropertyConverter.class)
-  @Config
-  private String a;
+The +DynamicValue+ provides you the following functionality:
+
+[source,java]
+--------------------------------------------
+public interface DynamicValue<T> {
+
+    T get();
+    T getNewValue();
+    T evaluateValue();
+    T commitAndGet();
+    void commit();
+    void discard();
+    boolean updateValue();
+
+    void setUpdatePolicy(UpdatePolicy updatePolicy);
+    UpdatePolicy getUpdatePolicy();
+    void addListener(PropertyChangeListener l);
+    void removeListener(PropertyChangeListener l);
+
+    boolean isPresent();
+    T orElse(T other);
+    // Enabled with Java 8
+    // T orElseGet(ConfiguredItemSupplier<? extends T> other);
+    // <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X>
exceptionSupplier) throws X;
+
+}
 
+public enum UpdatePolicy{
+    IMMEDIATE,
+    EXPLCIT,
+    NEVER,
+    LOG_AND_DISCARD
 }
 --------------------------------------------
 
+//Summarizing +DynamicValue+ looks somehow similar to the new +Optional+ class added with
Java 8. It provides
+//a wrapper class around a configured instance. Additionally this class provides functionality
that gives
+//active control, to manage a configured value based on a ++LoadingPolicy+:
+//
+//* +IMMEDEATE+ means that when the configuration system detects a change on the underlying
value, the new value
+//  is automatically applied without any further notice.
+//* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+
property. if +getNewValue()+
+//  returns a non null value, the new value can be applied by calling +commit()+. You can
always access the newest value,
+//  hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible
ti ignore a change by calling
+//  +discard()+.
+//* +NEVER+ means the configured value is evaluated once and never updated. All changes are
silently discarded.
+//* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.
+
+Summarizing a +DynamicValue+ allows you
+
+* to reload actively updates of configured values.
+* update implicitly or explicitly all changes on the value.
+* add listeners that observe changes of a certain value.
+
+Dynamic values also allow on-the-fly reevaluation of the value by calling +evaluateValue()+.
Hereby the value of the
+instance is not changed.
+
+
+===== The Loading policy enum
+
+The +LoadPolicy+ enum defines different configuration loading behaviour
+to be applied:
+
+[source,java]
+--------------------------------------------
+@Deprecated
+public enum LoadPolicy {
+    /**
+     * The configuration keys is evaluated once, when the owning component is loaded/configured,
but never updated later.
+     */
+    INITIAL,
+    /**
+     * The configuration keys is evaluated exactly once on its first access/use lazily, but
never updated later.
+     * @see DynamicValue#get()
+     * @see DynamicValue#commitAndGet()
+     */
+    LAZY,
+    /**
+     * The configuration value is evaluated every time it is accessed.
+     */
+    ALWAYS
+}
+--------------------------------------------
+
+This enum type currently is used only internally, so avoid using it as of
+now in your code is recommended.
+
 
 === Configuration Events
 


Mime
View raw message