You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by an...@apache.org on 2018/11/18 21:20:50 UTC
[4/8] incubator-tamaya-site git commit: TAMAYA-274 Updated
documentation. TAMAYA-355 Updated documentation. TAMAYA-353 Updated
documentation.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_collections.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_collections.adoc
index 93cc4be,93cc4be..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_collections.adoc
+++ /dev/null
@@@ -1,245 -1,245 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Collection Support
--
--toc::[]
--
--[[Collections]]
--== Tamaya Collections Support (Extension Module)
--
--Tamaya _Collections_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--All configuration in Tamaya is expressed as simple key, value pairs. Nevertheless this concept allows similarly
--the modelling of collection typed values such as lists, sets, maps or simple collections of things. The Tamaya
--Collections extension adds this functionality to the Tamaya eco-system.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use Tamaya collection support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-collections</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Overview
--
--Tamaya Collections adds +PropertyConverter+ implementations that are able to access configuration data
--as _lists, maps_ or _sets_. By default this works out of the box as easy as accessing any other type of
--configuration data, e.g.
--
--[source, java]
-------------------------------------------------
--Configuration config = ConfigurationProvider.getConfiguration();
--
--// Without any content specification, a list of String is returned.
--List<String> simpleList = config.get("my.list.config.entry", List.class);
--
--// Using a TypeLiteral allows to use every convertible sub type supported by the system.
--List<Integer> intList = config.get("my.list.config.entry", new TypeLiteral<List<Integer>>(){});
-------------------------------------------------
--
--Configuration in that case, by default, is a simple comma-separated list of entries, e.g.
--
--[source, properties]
-------------------------------------------------
--my.list.config.entry=1,34454,23,344545,3445
-------------------------------------------------
--
--Additionally the module allows adding additional meta-entries, which allows to tweak some of the
--inner-workings, e.g.
--
--* using your own +PropertyConverter+ implementation for parsing entries.
--* specifying a custom separator to split the items (default is {{','}}.
--* specifying a custom separator to split key/value pairs when parsing map entries.
--* specifying the implementation type of the collection item to be returned.
--* specifying the implementation type of the collection to be returned.
--
--
--=== Supported Types
--
--This module currently supports the following types:
--
--* +java.util.Collection+
--* +java.util.List+
--* +java.util.ArrayList+
--* +java.util.LinkedList+
--* +java.util.Set+
--* +java.util.SortedSet+
--* +java.util.TreeSet+
--* +java.util.HashSet+
--* +java.util.Map+
--* +java.util.SortedMap+
--* +java.util.HashMap+
--* +java.util.TreeMap+
--
--Hereby the collection type is determined by the parameter type accessed, e.g.
--+config.get("mylist", ArrayList.class)+ will always return an +ArrayList+
--as result.
--
--NOTE: This means that depending on your use case you can access different
--collection types based on the same configuration values, as long as their is
--a +PropertyConverter+ that can convert the _raw configuration value_ to the
--required target type.
--
--
--==== Configuring the target implementation type
--
--Tamaya Collections allows you to configure the _default_ target collection type by adding the
--following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part
--+java.util.+ can be ommitted:
--
--[ source, properties]
-------------------------------------------------
--mylist=a,b,c
--_mylist.collection-type=LinkedList
-------------------------------------------------
--
--When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect,
--so you will still get an +ArrayList+ as a result. However when you call +config.get("mylist",
--List.class)+ you will get a +LinkedList+ as implementation type.
--
--This mechanism similarly applies to all kind of collections, so you can use it similarly to define the implementation
--type returned when accessing +List+, +Map+ or +Collection+.
--
--
--=== Collecting Configuration Entries instead of Overriding
--
--By default Tamaya applies always an overriding +CombinationPolicy+, where only the configuration entry for
--the most significant configuration entry is used. In case of collections (and maybe also other use cases),
--overriding is not always the mechanism of choice. E.g. when you want to have all entries added to your
--configuration to be *combined* to a new entry containing all values provided by any property sources.
--
--Therefore _Tamaya Collections_ also provides a more sophistiated +CombinationPolicy+ (automatically configured)
--that allows to adapt the way how configuration entries are combined. All you must do is declaring
--the mechanism to be applied by an according _meta-configuration_ parameter, e.g. for +my.list+ your config may
--look as follows:
--
--[source, properties]
-------------------------------------------------
--# from PropertSource 1
--my.list=1,2,3
--
--# from PropertSource 2, with higher precedence
--my.list=4,5,6
--
--# without any additional meta-info these entries would be combined to
--my.list=4,5,6
-------------------------------------------------
--
--With Tamaya Collections you can now configure the combination policy as follows:
--
--[source, properties]
-------------------------------------------------
--# use one of the default policies: override / collect
--_my.list.combination-policy=collect
--
--# or use your own custom CombinationPolicy to combine the values
--_my.list.combination-policy=com.mycomp.app.MyCombincationPolicy
-------------------------------------------------
--
--So declaring the +collect+ policy the resulting raw output of the entry looks as follows:
--
--[source, properties]
-------------------------------------------------
--# result when applying the collect policy:
--my.list=1,2,3,4,5,6
-------------------------------------------------
--
--The customizable policy mechanism of Tamaya Collections also honors the +item-separator+ meta-configuration
--parameter explained later in this document.
--
--
--=== Format of Collection Configuration
--
--By default collections are modelled as simple String values, that are tokenized into individual parts using a
--defined +item-separator+ (by default +','+). So a given configuration entry of +1,2,3+ is mapped to +"1","2","3".
--If the target context type is something different than String the smae conversion logic is used as when mapping
--configuration parameters directly to non-String target types (implemented as +PropertyConverter+ classes, manahed
--within the current +ConfigurationContext+. The procedure is identical for all collection types, including +Map+ types,
--with the difference that each token in the list is parsed once more for separating it into a +key+ and a +value+.
--The default separator for map entries hereby is +"::"+. Map keys, as of now, are always of type +String+, whereas
--for values the same logic is applied as for non-map collection types.
--
--[source, properties]
-------------------------------------------------
--# a list, using the default format
--list=1,2,3,4,5,6
--
--# a map, using the default format
--map=a::b, c::d
-------------------------------------------------
--
--
--==== Trimming of entries
--
--By default all tokens parsed are trimmed _before_ adding them to the final collection. In case of map entries this is
--also the case for key/value entries. So the following configuration results in the identical values for
--+list1,list2+ and +map1,map2+:
--
--[source, properties]
-------------------------------------------------
--# a list, using the default format
--list1=1,2,3,4,5,6
--list2=1, 2, 3, 4, 5, 6
--
--# a map, using the default format
--map1=a::b, c::d
--map2=a :: b, c :: d
-------------------------------------------------
--
--Nevertheless truncation can be controlled by the usage of brackets, e.g. the last list or map entry will have a single
--space character as value:
--
--[source, properties]
-------------------------------------------------
--# a list, with a ' ' value at the end
--list3=1, 2, 3, 4, 5, [ ]
--
--# a map, with a ' ' value for key '0'
--map3=1 :: a, 2 :: b, 0::[ ]
-------------------------------------------------
--
--Hereby +\[+ escapes the sequence.
--
--
--==== Customizing the format
--
--The item and entry separators (by default +','+ and +"::"+) can be customized by setting corresponding meta-data
--entries as follows, resulting in the same values as in the prevoius listing:
--
--[source, properties]
-------------------------------------------------
--# a list, with a ' ' value at the end
--list3=1__2__3__ 4__ 5__[ ]
--_list3.item-separator=__
--
--# a map, with a ' ' value for key '0'
--map3=1->a, 2->b, 0->[ ]
--_map3.map-entry-separator=->
-------------------------------------------------
--
--Of course these settings also can be combined:
--
--[source, properties]
-------------------------------------------------
--# a reformatted map
--redefined-map=0==none | 1==single | 2==any
--_redefined-map.map-entry-separator===
--_redefined-map.item-separator=|
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_consul.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_consul.adoc
index 96c0b98,96c0b98..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_consul.adoc
+++ /dev/null
@@@ -1,66 -1,66 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration with consul (Hashicorp)
--
--toc::[]
--
--
--[[Consul]]
--== Integration with consul (Extension Module)
--
--Tamaya _Consul_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Consul_ provides different artifacts which allows use of
--link:http://www.consul.io[Consul from Hashicorp] as configuration backend. Basically the
--module supports read-only integration (as a +ConsulonfigSource+ as well
--as a writing configuration changes back (based on Tamaya's +MutableConfiguration+ API
--defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension module.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _tamaya-consul_ you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-consul</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Extensions Provided
--
--Consul integration comes basically with 2 artifacts:
--
--* The +org.apache.tamaya.etcd.ConsulConfigSource+ is a +ConfigSource+ with a default
-- ordinal of 100 and the name 'consul', which is automatically registered.
--* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
-- by accessing a +MutableConfiguration+ using the URI +config:consul+.
--
--Access of consul key/value pairs is through the normal Tamaya API.
--
--
--=== The ConsulConfigSource
--
--The +ConsulConfigSource+ is automatically registered and allows the consul servers to be used to be configured. This
--enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
--in microservice containers to connect with the according consul cluster:
--
--* The config source reads the +tamaya.consul.urls+ system and environment property to evaluate possible consul servers
-- (comma separated), which can be connected to. On failure the API just performs a Round-Robin through the list of
-- configured servers. Without any configuration +http://127.0.0.1:2400+ is used. If no connection to any consul
-- server can be established a warning will be logged, but deployment will not fail.
--* The +ConsulConfigSource+ finally also allows the values read from the consul cluster to be mapped to prefixed
-- context. This can be activated by setting the `-Dtamaya.consul.prefix=<PREFIX>` system property. E.g. when the prefix is
-- set to `cluster-config.` a consul key of `host:known/all` is mapped to `cluster-config.host:known/all`.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_etcd.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_etcd.adoc
index dac6ab7,dac6ab7..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_etcd.adoc
+++ /dev/null
@@@ -1,192 -1,192 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration with etcd (Core OS)
--
--toc::[]
--
--
--[[Etcd]]
--== Integration with etcd (Extension Module)
--Tamaya _Etcd_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Etcd_ provides different artifacts which allows using link:https://github.com/coreos/etcd[etcd] as a
--configuration backend. Basically the module adds a read-only property source (+EtcdConfigSource+). If
--the _tamaya-mutable-config_ extension is loaded it is alos possible to write configuration
--changes to _etcd_ using +MutableConfiguration+.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _etcd_ as a configuration backend you only must add the corresponding dependency to
--your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-etcd</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Extensions Provided
--
--Tamaya's _etcd_ integration provides basically the following artifacts:
--
--* The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint
-- root. The accessor basically provides a simple Java API for communicating with the _etcd_ server. The
-- accessor hereby allows reading of single properties, or whole subtrees. Also the basic non
-- atomic write methods are implemented.
--* The +org.apache.tamaya.etcd.EtcdConfigSource+ is a +ConfigSource+ with a default ordinal of 100 and the name
-- 'etcd', which is automatically registered.
--* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the etcd cluster,
-- by accessing a +MutableConfiguration+ using the URI +config:etcd+.
--
--=== The EtcdAccessor
--
--The accessor implements the basic read and write API for communicating with an _etcd_ server.
--Hereby the accessor also provides _etcd_ specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+
--returned. Hereby the concept of _etcd_ is used where keys starting with an '_' represent meta-configuration
--that will be hidden from the overall properties map, being only directly/explicitly accessible:
--
--[source, java]
-------------------------------------------------
--public class EtcdAccessor {
--
-- /**
-- * Creates a new instance with the basic access url.
-- * @param server server url, e.g. {@code http://127.0.0.1:4001}.
-- * @throws MalformedURLException
-- */
-- public EtcdAccessor(String server) throws MalformedURLException;
--
-- /**
-- * Get the etcd server version.
-- * @return the etcd server version, never null.
-- */
-- public String getVersion();
--
-- /**
-- * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd:
-- * <pre>
-- * key=value
-- * _key.source=[etcd]http://127.0.0.1:4001
-- * _key.createdIndex=12
-- * _key.modifiedIndex=34 // optional
-- * _key.ttl=300 // optional
-- * _key.expiration=... // optional
-- * </pre>
-- * @param key the requested key
-- * @return the mapped result, including meta-entries.
-- */
-- public Map<String,String> get(String key);
--
-- /**
-- * Creates/updates an entry in etcd without any ttl set.
-- * The response is as follows:
-- * <pre>
-- * key=value
-- * _key.source=[etcd]http://127.0.0.1:4001
-- * _key.createdIndex=12
-- * _key.modifiedIndex=34 // optional
-- * _key.prevNode.createdIndex=12 // optional
-- * _key.prevNode.modifiedIndex=34 // optional
-- * </pre>
-- * @param key the property key, not null
-- * @param value the value to be set
-- * @return the result map as described above.
-- */
-- public Map<String,String> set(String key, String value);
--
-- /**
-- * Creates/updates an entry in etcd. The response is as follows:
-- * <pre>
-- * key=value
-- * _key.source=[etcd]http://127.0.0.1:4001
-- * _key.createdIndex=12
-- * _key.modifiedIndex=34 // optional
-- * _key.ttl=300 // optional
-- * _key.expiry=... // optional
-- * _key.prevNode.createdIndex=12 // optional
-- * _key.prevNode.modifiedIndex=34 // optional
-- * _key.prevNode.ttl=300 // optional
-- * _key.prevNode.expiration=... // optional
-- * </pre>
-- * @param key the property key, not null
-- * @param value the value to be set
-- * @param ttlSeconds the ttl in seconds (optional)
-- * @return the result map as described above.
-- */
-- public Map<String,String> set(String key, String value, Integer ttlSeconds);
--
--
-- /**
-- * Deletes a given key. The response is as follows:
-- * <pre>
-- * _key.source=[etcd]http://127.0.0.1:4001
-- * _key.createdIndex=12
-- * _key.modifiedIndex=34
-- * _key.ttl=300 // optional
-- * _key.expiry=... // optional
-- * _key.prevNode.createdIndex=12 // optional
-- * _key.prevNode.modifiedIndex=34 // optional
-- * _key.prevNode.ttl=300 // optional
-- * _key.prevNode.expiration=... // optional
-- * _key.prevNode.value=... // optional
-- * </pre>
-- * @param key the key to be deleted.
-- * @return the response mpas as described above.
-- */
-- public Map<String,String> delete(String key);
--
--
-- /**
-- * Access regular Tamaya properties map as follows:
-- * <pre>
-- * key1=myvalue
-- * _key1.source=[etcd]http://127.0.0.1:4001
-- * _key1.createdIndex=12
-- * _key1.modifiedIndex=34 // optional
-- * _key1.ttl=300 // optional
-- * _key1.expiration=... // optional
-- *
-- * key2=myvaluexxx
-- * _key2.source=[etcd]http://127.0.0.1:4001
-- * _key2.createdIndex=12
-- *
-- * key3=val3
-- * _key3.source=[etcd]http://127.0.0.1:4001
-- * _key3.createdIndex=12
-- * _key3.modifiedIndex=2
-- * </pre>
-- */
-- public Map<String,String> getProperties(String directory, boolean recursive);
--
--}
-------------------------------------------------
--
--
--=== The EtcdConfigSource
--
--The +EtcdConfigSource+ is automatically registered and allows to configure the _etcd_ servers to be used. This
--enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
--in microservice containers to connect with the according etcd cluster:
--
--* The property source reads the +tamaya.etcd.server.urls+ system and environment property to evaluate possible etcd servers
-- (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
-- configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd
-- server can be established a warning will be logged, but deployment will not fail.
--* Additionally also the accessor allows to configure the socket/connection timeouts by setting
-- +tamaya.etcd.timeout+ in seconds either as system or environment property.
--* The +EtcdConfigSource+ finally also allows the values read from the _etcd_ cluster to be mapped to prefixed
-- context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is
-- set to `cluster-config.` a etcd key of `host:known/all` is mapped to `cluster-config.host:known/all`.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_events.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_events.adoc
index 9061d13,9061d13..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_events.adoc
+++ /dev/null
@@@ -1,308 -1,308 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Events
--
--toc::[]
--
--
--[[Events]]
--== Tamaya Events (Extension Module)
--
--Tamaya _Events_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Events_ provides a mechanism to publish and subscribe to +ConfigEvent<T>+ instances.
--This module implements +ConfigChange+ or +ConfigSourceChange+ as possible payloads, but
--the module itself is not constraint to this payload types.
--These payload types describe detected changes of key/values of a +Config+ or a +ConfigSource+.
--The extension also provides a _Singleton accessor_ which allows to register/unregister
--listeners for changes and the period, when configuration should be scanned for
--any changes.
--
--Summarizing with the events module you can easily observe configuration changes, record the
--state of any configuration and compare configuration states to create and publish related
--change events.
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--=== Installation
--
--To benefit from configuration event support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-events</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Core Architecture
--
--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 interface ConfigEvent<T> {
--
-- Class<T> getResourceType();
-- T getResource();
-- String getVersion();
-- long getTimestamp();
--}
--
--@FunctionalInterface
--public interface ConfigEventListener {
--
-- void onConfigEvent(ConfigEvent<?> event);
--
--}
----------------------------------------------
--
--Hereby the payload _T_ can be basically of an arbitrary type as long as
--it implements the +ConfigEvent+ interface. The next sections
--give more details on the the event types provided by this extension
--and their usage.
--
--Also the technology to be used for publishing these event types is adaptable.
--In SE the module uses a simple in-memory implementation based on the
--Google _Guava_ library. But users can replace this mechanism as needed. For
--more details refer to the SPI section later in this guide.
--
--
--=== 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
--
--* additional, _new_ configuration entries
--* _removed_ configuration entries
--* _changes_ on existing entries
--
--
--A collection of changes
--
--* on a +Config+ is modelled by the +ConfigChange+ class
--* on a +ConfigSource+ is modelled by the +ConfigSourceChange+ class
--
--
--==== Configuration Changes
--
--A set of changes on a +Config+ is described by a +ConfigChange+
--as follows:
--
--[source,java]
---------------------------------------------------------
--public final class ConfigChange implements ConfigEvent<Config>, Serializable{
--
-- public static ConfigChange emptyChangeSet(Config configuration);
--
-- @Override
-- public Config getResource();
-- @Override
-- public Class<Config> getResourceType();
-- @Override
-- public String getVersion();
-- @Override
-- public long getTimestamp();
--
-- // Event specific methods
--
-- public Collection<PropertyChangeEvent> getChanges();
-- public int getRemovedSize();
-- public int getAddedSize();
-- public int getUpdatedSize();
--
-- public boolean isKeyAffected(String key);
-- public boolean isRemoved(String key);
-- public boolean isAdded(String key);
-- public boolean isUpdated(String key);
-- public boolean containsKey(String key);
-- public boolean isEmpty();
--}
--
---------------------------------------------------------
--
--New instances of +ConfignChange+ hereby can be created using a
--fluent +ConfigChangeBuilder+:
--
--[source,java]
---------------------------------------------------------
--Config config = ...;
--ConfigChange change = ConfigChangeBuilder.of(config)
-- .addChange("MyKey", "newValue")
-- .removeKeys("myRemovedKey").build();
---------------------------------------------------------
--
--Also it is possible to directly compare 2 instances of +Config+,
--which results in a +ConfigChange+ that
--reflects the differences between the two configurations passed:
--
--[source,java]
--Comparing 2 configurations
---------------------------------------------------------
--Config config = ...;
--Config changedConfig = ...;
--ConfigChange change = ConfigChangeBuilder.of(config)
-- .addChanges(changedConfig).build();
---------------------------------------------------------
--
--So a +ConfigChange+ describes all the changes detected on a +Config+.
--This allows you to publish instances of this class as events to all registered
--listeners (observer pattern).
--For listening to +ConfigChange+ events you must implement the
--+ConfigEventListener+ functional interface:
--
--[source,java]
--.Implementing a ConfigChangeListener
---------------------------------------------------------
--public final class MyConfigChangeListener implements ConfigEventListener<ConfigChange>{
--
-- private Config config = ConfigProvider.getConfig();
--
-- public void onConfigEvent(ConfigEvent<?> event){
-- if(event.getResourceType()==Config.class){
-- if(event.getConfiguration()==config){
-- // do something
-- }
-- }
-- }
--
--}
---------------------------------------------------------
--
--You can *register* your implementation as illustrated below:
--
--. Manually by calling +ConfigEventManager.addListener(new MyConfigChangeListener())+
--. Automatically by registering your listener using the +ServiceLoader+ under
-- +META-INF/services/org.apache.tamaya.events.ConfigEventListener+
--
--Registering programmatically also allows you to define additional constraint,
--to filter out all kind of events you are not interested in.
--
--NOTE: By default detection of configuration changes is not enabled. To enable it, call
--+ConfigEventManager.enableChangeMonitoring(true)+.
--
--
--=== ConfigSource Changes
--
--Beside that a whole +Config+ changes, also a +ConfigSource+ can change,
--e.g. by a configuration file edited on the fly. This is similarly to a
--+ConfigChange+ reflected by the classes +ConfigSourceChange,
--ConfigSourceChangeBuilder+.
--
--
--==== Monitoring of configuration changes
--
--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 +Config+ for
--any kind of changes. If a change has been encountered Tamaya identifies it and triggers corresponding
--+ConfigChange+ events automatically.
--
--
--=== Freezing Configs and ConfigSources
--
--+Config+ instances as well as +ConfigSources+ are explicitly not required to be serializable. To enable easy
--serialization of these types a +Config+'s *current state can be frozen* (e.g. for later comparison with a newly
--loaded version). Freezing hereby means
--
--* all key/values are read-out by calling the +getProperties()+ method.
--* a meta data entry is added of the form +_frozenAt=223273777652325677+, whichdefines the UTC timestamp in
-- milliseconds when this instance was frozen.
--* if not already defined an +_id+ property will be added to the +Config+ containing the
-- identifier of the configuration.
--
--In code freezing is a no-brainer:
--
--[source,java]
--.Freezing the current Config
----------------------------------------------------
--Config config = ConfigProvider.getConfig();
--Config frozenConfig = FrozenConfig.of(config);
----------------------------------------------------
--
--... and similarly for a +ConfigSource+:
--
--[source,java]
--.Freezing a ConfigSource
----------------------------------------------------
--ConfigSource configSource = ...;
--ConfigSource frozenSource = FrozenConfigSource.of(configSource);
----------------------------------------------------
--
--
--
--=== SPIs
--
--This component also defines SPIs, which allows to adapt the implementation of the main +ConfigEventManager+
--singleton. This enables, for example, using external eventing systems, such as CDI, instead of the default provided
--simple SE based implementation. By default implementations must be registered using the current +ServiceContext+
--active (by default using the Java +ServiceLoader+ mechanism).
--
--[source,java]
--.SPI: ConfigEventSpi
----------------------------------------------------
--public interface ConfigEventManagerSpi {
--
-- <T> void addListener(ConfigEventListener l);
-- <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
-- void removeListener(ConfigEventListener l);
-- <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
-- Collection<? extends ConfigEventListener> getListeners();
-- Collection<? extends ConfigEventListener> getListeners(Class<? extends ConfigEvent> eventType);
--
-- void fireEvent(ConfigEvent<?> event);
-- void fireEventAsynch(ConfigEvent<?> event);
--
-- long getChangeMonitoringPeriod();
-- void setChangeMonitoringPeriod(long millis);
-- boolean isChangeMonitorActive();
-- void enableChangeMonitor(boolean enable);
--}
----------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_features.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_features.adoc
index 454cf48,454cf48..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_features.adoc
+++ /dev/null
@@@ -1,87 -1,87 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Features Check
--
--toc::[]
--
--
--[[Features]]
--== Tamaya Features Check (Extension Module)
--Tamaya _Features_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Features_ provides a simple +Features+ singleton that allows to check
--which Tamaya Extensions are currently on the classpath.
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use Tamaya _Features_ you only must add the corresponding dependency to
--your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-features</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Functionality Provided
--
--Main artifact is the +Features+ singleton, which provides various static methods
--to check, which Tamaya extensions are currently loaded.
--
--[source, java]
-------------------------------------------------
--public final class Features {
--
-- private Features(){}
--
-- public static boolean eventsAvailable();
-- public static boolean formatsAvailable();
-- public static boolean tamayaCoreAvailable();
-- public static boolean injectionAvailable();
-- public static boolean injectionCDIAvailable();
-- public static boolean mutableConfigAvailable();
-- public static boolean optionalAvailable();
-- public static boolean resolverAvailable();
-- public static boolean resourcesAvailable();
-- public static boolean spiSupportAvailable();
-- public static boolean filterSupportAvailable();
-- public static boolean springAvailable();
-- public static boolean jndiAvailable();
--
-- public static boolean extSpringCoreAvailable();
-- public static boolean extJndiAvailable();
-- public static boolean extOSGIAvailable();
--
-- public static boolean checkClassIsLoadable(String classname);
--}
-------------------------------------------------
--
--* +eventsAvailable();+ checks for the link:mod_events.html[_tamaya_events_] module.
--* +formatsAvailable();+ checks for the link:mod_formats.html[_tamaya_formats_] module.
--* +tamayaCoreAvailable();+ checks if the link:core.html[_Tamaya core_] implementation is loaded.
--* +injectionAvailable();+ checks for the link:mod_injection.html[_tamaya_injection_] SE module.
--* +injectionCDIAvailable();+ checks for the link:mod_cdi.html[_tamaya CDI_] modules.
--* +mutableConfigAvailable();+ checks for the link:mod_mutableconfig.html[_tamaya_mutableconfig_] module.
--* +optionalAvailable();+ checks for the link:mod_optional.html[_tamaya_optional_] module.
--* +resolverAvailable();+ checks for the link:mod_resolver.html[_tamaya_resolver_] module.
--* +resourcesAvailable();+ checks for the link:mod_reources.html[_tamaya_resources_] module.
--* +spiSupportAvailable();+ checks for the link:mod_spisupport.html[_tamaya_spisupport_] module.
--* +filterSupportAvailable();+ checks for the link:mod_filter.html[_tamaya_filter_] module.
--* +springAvailable();+ checks for the link:mod_spring.html[_tamaya_spring_] module.
--* +jndiAvailable();+ checks for the link:mod_jndi.html[_tamaya_jndi_] module.
--* +extJndiAvailable();+ checks if creation of a new `InitialContext` is successful.
--* +extSpringCoreAvailable();+ checks if Spring Core is on the classpath.
--* +extOSGIAvailable();+ checks the OSGI framework is on the classpath.
--* Finally +checkClassIsLoaded(String)+ tries to load a class. If it fails, `false` is returned.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_filter.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_filter.adoc
index 8de64d8,8de64d8..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_filter.adoc
+++ /dev/null
@@@ -1,117 -1,117 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: User Filtering
--
--toc::[]
--
--
--[[Filter]]
--== User Filtering (Extension Module)
--
--Tamaya _Filter_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Filter_ provides a simple singleton accessor that allows to explicitly add +Filter+ instances
--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.
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To benefit from filter support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-filter</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Extensions Provided
--
--Tamaya Filter comes basically with 3 artifacts:
--
--* The +org.apache.tamaya.filter.ConfigurationFilter+ provides several static methods to register +Filter+
--instances on the current thread:
--
--[source, java]
-------------------------------------------------
--public final class ConfigurationFilter implements Filter{
--
-- ...
--
-- /**
-- * Seactivates metadata filtering also on global map access for this thread.
-- * @see #clearFilters()
-- * @param active true,to enable metadata filtering (default).
-- */
-- public static void setFilterMetadata(boolean active);
--
-- /**
-- * Access the filtering configuration that is used for filtering single property values accessed.
-- * @return the filtering config, never null.
-- */
-- public static FilterContext getSingleFilterContext();
--
-- /**
-- * Access the filtering configuration that is used for filtering configuration properties accessed as full
-- * map.
-- * @return the filtering config, never null.
-- */
-- public static FilterContext getMapFilters();
--
-- /**
-- * Removes all programmable filters active on the current thread.
-- */
-- public static void clearFilters();
--
-- ...
--
--}
-------------------------------------------------
--
--For using regular expression when filtering configuration keys a corresponding implementation of a +PropertyFilter+
--is part of this module, So you can add a customized filter as follows:
--
--[source, java]
-------------------------------------------------
--try {
-- ConfigurationFilter.getMapFilters().addFilter(new myFilter());
--
-- // do your code with filtering active
--}
--finally {
-- // cleanup
-- ConfigurationFilter.clearFilters();
--}
-------------------------------------------------
--
--
--The +FilterChain+ is a simple compound structure combining multiple filters into one new (chained) filter:
--
--[source, java]
-------------------------------------------------
--public final class FilterChain implements Filter {
--
-- public void addFilter(Filter filter);
-- public void addFilter(int pos, Filter filter);
-- public Filter removeFilter(int pos);
-- public void clearFilters();
-- public void setFilters(Filter... filters);
-- public void setFilters(Collection<Filter> filters);
-- public List<Filter> getFilters();
--
--}
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_formats.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_formats.adoc
index fa7b1a5,fa7b1a5..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_formats.adoc
+++ /dev/null
@@@ -1,290 -1,290 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Formats
--
--toc::[]
--
--
--[[Formats]]
--== Tamaya Formats (Extension Module)
--
--Tamaya _Formats_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Formats_ provides an abstraction for configuration formats provding the following benefits:
--
--* Parsing of resources in can be implemented separately from interpreting the different aspects/parts parsed. As an
-- example a file format can define different sections. Depending on the company specific semantics of the sections
-- a different set of +ConfigSource+ instances must be created.
--* Similarly the configuration abstraction can also be used as an interface for integrating Tamaya with alternate
-- frameworks that provide logic for reading configuration files, such as Apache commons.configuration.
--
--=== Compatibility
--
--The module is based on Java 7, so it can be used with Java 7 and beyond.
--
--=== Installation
--
--To use the formats module you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-formats</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== 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). 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 +ConfigSources+ (they can have different ordinal semantics).
--
--
--==== ConfigurationData
--
--Configuration formats can be very different. Some are simple key/value pairs, whereas other also consist of multiple sections (e.g. ini-files) or
--hierarchical data (e.g. yaml, xml). This is solved in Tamaya by mapping the configuration read into a normalized intermediary format called
--+ConfigurationData+:
--
--[source,java]
--.ConfigurationData
---------------------------------------------------------
--public final class ConfigurationData {
--
-- public ConfigurationFormat getFormat();
-- public String getResource();
--
-- public Set<String> getSectionNames();
-- public Map<String,String> getSection(String name);
--
-- public boolean hasDefaultProperties();
-- public Map<String,String> getDefaultProperties();
-- public Map<String,String> getCombinedProperties();
--
-- public boolean isEmpty();
--}
---------------------------------------------------------
--
--In detail the data read from a file is organized into _sections_ as follows:
--
--* with +getResource()+ and +getFormat()+ the underlying resource and the format that read this data can be accessed.
--* properties can be owned by
-- ** named sections
-- ** an (unnamed) default section
--* each section section contains a map of properties. Hereby the same key can be part of the default section and multiple
-- named sections, depending on the configuration format.
--* The method +getSectionNames()+ returns a set of all section names.
--* With +getSection(String name)+ a named section can be accessed.
--* With +getDefaultSection()+ the 'default' section can be accessed. This is a convenience method.
--* With +getCombinedProperties()+ a flattened entry map can be accessed built up (by default) out of
-- ** all entries from the default section, without any changes.
-- ** all entries from named sections, where the key for each entry is prefix with the section name and a '::' separator.
--* The configuration format used determines the mapping of configuration data read into this structure. The format
-- implementation can as well provide alternate implementations of how the data read should be mapped into the
-- combined properties map.
--
--
--==== ConfigurationFormat
--
--A ConfigurationFormat is basically an abstraction that reads a configuration resource (modelled by an InputStream) and
--creates a corresponding +ConfigurationData+ instance.
--
--[source,java]
---------------------------------------------------------
--public interface ConfigurationFormat {
--
-- String getName();
-- boolean accepts(URL url);
-- ConfigurationData readConfiguration(String resource, InputStream inputStream);
--}
---------------------------------------------------------
--
--=== Creating a default ConfigSource for a ConfigurationFormat
--
--The module defines a singleton +ConfigurationFormats+ which provides
--an easy to use API for creating +ConfigurationData+ and +ConfigSources+
--using abstract +ConfigurationFormat+ implementations:
--
--[source,java]
---------------------------------------------------------
--public final class ConfigurationFormats {
--
-- public static List<ConfigurationFormat> getFormats();
-- public static List<ConfigurationFormat> getFormats(String... formatNames);
-- public static List<ConfigurationFormat> getFormats(final URL url);
--
-- public static ConfigurationData readConfigurationData(final URL url)
-- throws IOException;
-- public static ConfigurationData readConfigurationData(URL url, ConfigurationFormat... formats)
-- throws IOException;
-- public static ConfigurationData readConfigurationData(URL url, Collection<ConfigurationFormat> formats)
-- throws IOException;
-- public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, ConfigurationFormat... formats);
-- public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, Collection<ConfigurationFormat> formats);
-- public static ConfigurationData readConfigurationData(String resource, InputStream inputStream,
-- ConfigurationFormat... formats)
-- throws IOException;
-- public static ConfigurationData readConfigurationData(String resource, InputStream inputStream,
-- Collection<ConfigurationFormat> formats)
-- throws IOException;
--
-- public static ConfigSource createConfigSource(URL url, ConfigurationFormat... formats)
-- throws IOException;
-- public static ConfigSource createConfigSource(URL url, Collection<ConfigurationFormat> formats)
-- throws IOException;
-- public static ConfigSource createConfigSource(String resource, InputStream inputStream,
-- ConfigurationFormat... formats);
-- public static ConfigSource createConfigSource(String resource, InputStream inputStream,
-- Collection<ConfigurationFormat> formats);
--}
---------------------------------------------------------
--
--* +getFormats()+ returns all registered formats.
--* +getFormats(String...)+ allows to access all formats with a given name.
--* +getFormats(URL url)+ allows to access all formats that declare that can optionally read an input from
-- a given `URL`.
--* +readConfigurationData(...)+ reads data from an input and creates a corresponding +ConfigurationData+,
-- either trying all known formats that declare its compatibility with the given input or the formats
-- passed explicitly.
--* +createConfigSource(...)+ allows to create a +ConfigSource+ reading a given input and the formats
-- to be used or known. Hereby a default property mapping is applied.
--
--So creating a +ConfigSource+ from a resource is basically a one liner:
--
--[source,java]
---------------------------------------------------------
--URL url = ...;
--ConfigSource configSource = ConfigurationFormats.createConfigSource(url);
--
--// constraining the formats to be used (assumption: json and yaml extensions are loaded)
--ConfigSource configSource = ConfigurationFormats.createConfigSource(
-- url,
-- ConfigurationFormats.getFormats("json", "yaml"));
---------------------------------------------------------
--
--
--=== Customize how ConfigurationData maps to ConfigSource
--
--For for the conversion of +ConfigurationData+ into a +ConfigSource+ different approaches can be useful:
--
--. The +ConfigurationFormat+ that reads the data can provides all properties read either as sectioned properties
-- or/and as default properties. The most simple cases is, where all properties have been added as 'default'
-- properties. In this case the default properties can be used as the property sources properties without any change.
--. If the format did also add section based properties, the combined properties returned can be used, hereby
-- replacing the '::' separator with a '.' separator.
--. In all other cases a custom mapping is useful, which can be acomplished by using the +MappedConfigurationDataConfigSource+
-- and overriding the +Map<String,String> populateData(ConfigurationData data)+ method.
--
--In most cases the usage of a +MappedConfigurationDataConfigSource+, is a good choice to start. This class
--provides a convenient default mapping and also allows to customized the mapping easily:
--
--[source,java]
---------------------------------------------------------
--ConfigurationData data = ...;
--MappedConfigurationDataConfigSource ps =
-- new MappedConfigurationDataConfigSource(data){
-- protected Map<String, String> populateData(ConfigurationData data) {
-- ...
-- }
-- };
---------------------------------------------------------
--
--Nevertheless, depending on the context, where a configuration source was read (classloader, time, source etc.) the
--resulting properties can have different semnatics, especially different priorities. Also section
--names may be mapped into different ordinals instead of using them as key prefixes (e.g. imagine configuration formats
--with a 'default', 'main', and 'overrides' sections). For such more complex or custom cases no simple mapping
--can be defined. Consequently the functionality mapping the normalized +ConfigurationData+ read to the
--appropriate collection of +ConfigSource+ instances must be implemented.
--
--For this scenario the +BaseFormatConfigSourceProvider+ can be used, defining the following mapping
--function that mus be implemented:
--
--[source,java]
---------------------------------------------------------
--/**
-- * Method to create a {@link org.apache.tamaya.spi.ConfigSource} based on the given entries read.
-- *
-- * @param data the configuration data, not null.
-- * @return the {@link org.apache.tamaya.spi.ConfigSource} instance ready to be registered.
-- */
--protected abstract Collection<ConfigSource> getConfigSources(ConfigurationData data);
---------------------------------------------------------
--
--When using Java 8 these mappings can be asily passed as parameters to the +createConfigSource+
--methods.
--
--
--=== Predefined formats
--
--The _formats_ module ships with 3 predefined formats:
--
--* `.ini` files, commonly known from Microsoft based systems, registered as `ini`.
--* `.properties` files, as defined by `java.util.Properties`, registered as `properties`.
--* `.xml` properties files, as defined by `java.util.Properties`, registered as `xml-properties`.
--
--
--==== ini Config File Mapping
--
--This module implements the ini file format with the class
--+org.apache.tamaya.format.formats.IniConfigurationFormat+.
--
--The default mapping is bext illustrated by a small example, so consider the
--following `.ini` file:
--
--[source,listing]
---------------------------------------------------------
--a=valA
--a.b=valB
--
--[section1]
--aa=sectionValA
--aa.b.c=SectionValC
--
--[section2]
--a=val2Section2
---------------------------------------------------------
--
--This file content by default is mapped to the following Tamaya properties:
--
--[source,listing]
---------------------------------------------------------
--a=valA
--a.b=valB
--section1::valA=sectionValA
--section1::a.b.c=SectionValC
--section2::a=val2Section2
---------------------------------------------------------
--
--Summarizing
--
--* entries without a section are mapped to the _default_ section.
--* entries with a section are mapped to a corresponding section, hereby everything between
-- the brackets is used as section name (trimmed).
--* section names are separated using a double colon (`::`).
--
--+ConfigurationData+ allows to access all the different parts:
--
--* the _default_ properties (a, a.b)
--* the section +section1+, with properties +aa, aa.b.c+
--* the section +section2+, with properties +a+
--
--
--==== XML Property and ordinary Property Files
--
--This module also ships with +ConfigurationFormat+ implementations that reuse the parsing
--functionality provided with +java.util.Properties+:
--
--* `org.apache.tamaya.format.formats.PropertiesFormat` uses `Properties.read(InputStream)`.
--* `org.apache.tamaya.format.formats.PropertiesXmlFormat` uses `Properties.readFromXml(InputStream)`.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_functions.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_functions.adoc
index bd52219,bd52219..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_functions.adoc
+++ /dev/null
@@@ -1,136 -1,136 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Functions
--
--toc::[]
--
--[[Functions]]
--== Tamaya Functions (Extension Module)
--
--Tamaya _Functions_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Functions_ provides several functional extensions using the +UnaryOperator<Config>,Function<Config, T>+ extension
--points. Most functional extension are accessible from the +ConfigurationFunctions+ singleton. Since the JSR API
--does not provide any functional extension points it is recommended to adapt the +Config+ instance into .+FunctionalConfig+.
--Then, when importing the functional methods statically they can very easily applied, e.g.
--
--[source,java]
---------------------------------------------------------------------
--import static org.apache.tamaya.functions.ConfigurationFunctions.*;
--
--FunctionalConfig fc = FunctionalConfig.of(ConfigProvider.getConfig());
--Set<String> sections = fc.with(areas("a", false).with(transitiveAreas());
---------------------------------------------------------------------
--
--The expression above returns all fully qualified section names that are child sections of the root section 'a'.
--So given the entries +a.b.entry1, a.b.entry2, a.a.entry3, a.b.c.entry4+ the reult would be +a, a.a, a.b, a.b.c+.
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--=== Installation
--
--For using the functionality shown in this document you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-functions</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== FunctionalConfig
--
--The +FunctionalConfig+ actually adds the functional extension points +with+ and +query+ to .+Config+ instance, which
--allow to chain expressions as seen in the introductionary snippet:
--
--[source, java]
-------------------------------------------------
--public interface FunctionalConfig extends Config, ConfigContextSupplier {
--
-- /**
-- * Enriches a {@link Config} instance with functional access points.
-- * @param config the config, not null
-- * @return a functional config instance.
-- */
-- static FunctionalConfig of(Config config){
-- ...
-- }
--
-- default FunctionalConfig with(UnaryOperator<Config> operator);
-- default <T> T query(Function<Config, T> query);
--}
-------------------------------------------------
--
--
--=== The Provided Functions
--
--==== Functions on +ConfigurationFunctions+
--
--The following sections explain the provided functions defined by +ConfigurationFunctions+ singleton.
--
--* *UnaryOperator<Config> filter(PropertyMatcher matcher)* creates a +UnaryOperator<Config>+ that creates a +Configuration+
-- containing only keys that are selected by the given _matcher predicate_. The +PropertyMatcher+ hereby allows to evaluate not only
-- the _key_, but also the _value_.
--* *UnaryOperator<Config> map(KeyMapper keyMapper)* creates a +UnaryOperator<Config>+ that maps the keys as defined
-- by the given _keyMapper_.
--* *UnaryOperator<Config> section(String section)* creates a +UnaryOperator<Config>+ that creates a +Configuration+ containing only
-- entries that are direct or indirect members of the given section.
--* *UnaryOperator<Config> section(String areaKey, boolean stripKeys)* creates a +UnaryOperator<Config>+ that creates a +Configuration+
-- containing only entries that are direct or indirect members of the given section. Hereby _stripKeys_ allows to determine
-- if the returned entries should be relative to the search criteria {{stripKeys=true}} or absolute keys.
--* *isKeyInSection(String section, String sectionKey)* allows to easily determine if a given _key_ is a direct or indirect member
-- of a given section.
--* *boolean isKeyInSections(String key, String... sectionKeys)* allows to easily determine if one key of given
-- _key_ is a direct or indirect member of at least one of the given _sectionKeys_.
--* *Function<Config,Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that
-- also have parameters present).
--* *Function<Config,Set<String>> transitiveSections()* allows to query all the contained fully qualified section names,
-- including the transitive closure of sections.
--* *Function<Config,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
-- qualified section names that are selected by the given _predicate_.
--* *Function<Config,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
-- qualified section names that are selected by the given _predicate_, including the transitive closure of sections
-- identified.
--* *UnaryOperator<Config> sectionsRecursive(String... sectionKeys)* provides a +UnaryOperator<Config>+ that filters all sections identified
-- by the given _sectionKeys_ and its child sections.
--* *UnaryOperator<Config> sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +UnaryOperator<Config>+
-- that filters all sections identified by the given _sectionKeys_ and its child sections. _stripKeys_ allows to
-- determine if the resulting configuration should be relative to the selected areas ({{stripKeys=true}}) or
-- absolute (filtering only).
--* *Function<Config,String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+
-- representation.
--
--
--==== Functions on +ConfigSourceFunctions+
--
--The following sections explain the provided functions defined by +ConfigSourceFunctions+ singleton.
--
--* *ConfigSource addMetaData(ConfigSource propertySource, Map<String,String> metaData)* Creates a new +ConfigSource+
-- with the given metadata added.
--* *boolean isKeyInSection(String key, String sectionKey)* Checks if the given _key_ is a direct or indirect member of
-- one of the given _sectionKey_.
--* *boolean isKeyInSections(String key, String... sectionKeys)* Checks if the given _key_ is a direct or indirect member of
-- one of one of the given _sectionKeys_.
--* *Set<String> sections(Map<String, String> properties)* Extracts the sections from the given properties.
--* *Set<String> transitiveSections(Map<String, String> properties)* Extracts the transitive sections from the given
-- properties.
--* *Set<String> sections(Map<String, String> properties, final Predicate<String> predicate)* Extracts the sections
-- from the given properties, also filtering with the given predicate.
--* *Set<String> transitiveSections(Map<String, String> properties, Predicate<String> predicate)* Extracts the transitive
-- sections from the given properties, also filtering with the given predicate.
--* *Map<String,String> sectionsRecursive(Map<String, String> properties, String... sectionKeys)* Creates w +ConfigSource+
-- only containing the sections that a direct or indirect children of the given _sectionKeys_.
--* *Map<String,String> sectionRecursive(Map<String, String> properties, boolean stripKeys, String... sectionKeys)* Creates w +ConfigSource+
-- only containing the sections that a direct or indirect children of the given _sectionKeys_. With _stripKeys_ one can
-- select of the returned values should be relative to its selection of be fully qualified.
--* *String stripSectionKeys(String key, String... sectionKeys)* This function strips away the matching section key as given
-- in _sectionKeys_ from a given _key_.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_hazelcast.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_hazelcast.adoc
index e17aad6,e17aad6..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_hazelcast.adoc
+++ /dev/null
@@@ -1,118 -1,118 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration with Hazelcast
--
--toc::[]
--
--
--[[Consul]]
--== Integration with Hazelcast (Extension Module)
--
--Tamaya _Hazelcast_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Hazelcast_ provides a property source which uses
--link:http://www.hazelcast.org[Hazelcast] as configuration backend. Hereby the
--module supports read-only integration (as a +HazelcastConfigSource+ as well
--as a writing configuration changes back (based on Tamaya's +MutableConfiguration+ API
--defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension module.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _tamaya-hazelcast_ you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-hazelcast</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Extensions Provided
--
--Hazelcast integration comes basically with 2 artifacts:
--
--* The +org.apache.tamaya.hazelcast.HazelcastConfigSource+ is a +ConfigSource+. The property source is not automatically
-- registered. Either register it using the _ServiceLoader_ yourself or implement
-- and register a corresponding `ConfigSourceProvider`.
--* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
-- by accessing a +MutableConfiguration+ using the URI +config:hazelcast+.
--
--Access of consul key/value pairs is through the normal Tamaya API.
--
--
--=== The HazelcastConfigSource
--
--The +HazelcastConfigSource+ is not automatically registered and provides different options how to integrate
--Tamaya with Hazelcast.
--
--[source, java]
-------------------------------------------------
--/**
-- * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and
-- * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}.
-- */
--public HazelcastConfigSource();
--
--/**
-- * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and the
-- * given hazelcast instance.
-- * @param hazelcastInstance the hazelcast instance, not null.
-- */
--public HazelcastConfigSource(HazelcastInstance hazelcastInstance);
--
--/**
-- * Creates a new instance, hereby using the given property source name and
-- * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}.
-- * @param name the property source name, not null.
-- */
--public HazelcastConfigSource(String name);
--
--/**
-- * Creates a new instance, hereby using the given property source name and
-- * a creating a new hazelcast backend using the given Hazelcast {@link Config}.
-- * @param config the hazelcast config, not null.
-- * @param name the property source name, not null.
-- */
--public HazelcastConfigSource(String name, Config config);
--
--/**
-- * Creates a new instance, hereby using the given property source name and the
-- * hazelcast instance.
-- * @param name
-- * @param hazelcastInstance
-- */
--public HazelcastConfigSource(String name, HazelcastInstance hazelcastInstance);
-------------------------------------------------
--
--To use hazelcast as a configuration backend, you simply create the corresponding Hazelcast instance
--and use it to initialize the Tamaya property source. Given that a hazelcast backedn configuration
--can be easily created asillustrated below:
--
--[source, java]
-------------------------------------------------
--// define config settings
--HazelcastInstance hazelcastInstance = Hazelcast.newInstance(hazelcastConfig);
--HazelcastConfigSource cs = new HazelcastConfigSource(hazelcastInstance);
--cs.setName("myHazelcast-config");
--cs.setOrdinal(2000);
--// Build your own configuration
--ConfigBuilder b = ConfigProviderResolver.getInstance().getBuilder();
--b.addDiscoveredConverters().addDefaultSources().addDiscoveredSources();
--// Add the hazelcast property source (as most significant)
--b.awithSource(cs);
--// build and use the configuration
--Config config = b.build();
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_injection.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_injection.adoc
index 831e098,831e098..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_injection.adoc
+++ /dev/null
@@@ -1,481 -1,481 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Injection
--
--toc::[]
--
--
--[[Injection]]
--== Tamaya Injection (Extension Module)
--
--Tamaya _Injection_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Injection_ provides functionality for injecting configured values into beans, or creating configuration
--template instances.
--
--Inversion of Control (aka IoC/Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate
--code. In Java there are different frameworks available that all provide IoC mechanisms. Unfortunately IoC is not a
--built-in language feature. So for a portable solution that works also in Java SE Tamaya itself has to provide the
--according injection services. This module adds this functionality to Tamaya.
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--=== Installation
--
--The basic injection API is defined by the configuration JSRßs API. Nevertheless Tamaya's adds some
--useful extensions. These extensions are deployed as optional API artifact:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-injection-api</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--To use injection with Java SE you must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-injection</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--Similarly there are other injection implementations available, targetig platforms such as
--
--* link:mod_spring.html[Spring, Spring Boot]
--* link:mod_CDI.html[Java EE/CDI]
--
--
--=== Core Concepts
--
--Basically you annotate fields or methods in your beans with +@ConfigProperty+ to enable configuration injection. Tamaya
--additionally defines further annotations that allo you to define additional aspects such as default values, custom
--converters etc. The following example illustrates the basic functionality:
--code snippet:
--
--[source,java]
--.Annotated Example Class
----------------------------------------------
--package foo.bar;
--
--public class ConfiguredClass {
--
-- // resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty
-- private String testProperty;
--
-- // Trying to resolve mutiple keys, with a default value, if none could be resolved
-- @ConfigProperty(key="a.b.c.key1", defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
-- @ConfigFaööbackKeys({"a.b.legacyKey",area1.key2"})
-- String value1;
--
-- // Typical case
-- @ConfigProperty(key="a.b.c.key2")
-- private int value2;
--
-- // resolved by default as foo.bar.ConfiguredClass.accessUrl
-- // Using a (default) String -> URL converter
-- @ConfigProperty(defaultValue="http://127.0.0.1:8080/res/api/v1/info.json")
-- private URL accessUrl;
--
-- // Config injection disabled for this property
-- @NoConfig
-- private Integer int1;
--
-- // Overriding the String -> BigDecimal converter with a custom implementation.
-- @ConfigProperty(key="BD")
-- @WithConverter(MyBigDecimalRoundingAdapter.class)
-- private BigDecimal bigNumber;
--
-- ...
--}
----------------------------------------------
--
--
--When configuring data or configuration classes it is also possible to auto-inject the fields identified. For activating
--this feature a class must be annotated with +@ConfigAutoDetect+:
--
--[source, java]
--.An autoinjected bean class
----------------------------------------------
--package a.b;
--
--@ConfigAutoDetect
--public final class Tenant {
-- private int id;
-- private String name;
-- private String description;
-- @NoConfig // prevents auto detection for this field
-- private String id2;
--
-- public int getId(){
-- return id;
-- }
-- public String getName(){
-- return name;
-- }
-- public String getDescription(){
-- return description;
-- }
--}
----------------------------------------------
--
--These examples do not show all possibilities provided. Configuring instance of these
--class using Tamaya is very simple: Just pass the instance to Tamaya to let
--Tamaya inject the configuration:
--
--[source,java]
--.Configuring the +ConfiguredClass+ Instance
----------------------------------------------
--ConfiguredClass classInstance = new ConfiguredClass();
--ConfigurationInjector.configure(configuredClass);
--
--Tenant tenant = new Tenant();
--ConfigurationInjector.configure(tenant);
----------------------------------------------
--
--NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used
--with CDI, Spring or within an OSGI container. For further details refer also to the corresponding integration module's
--documentation.
--
--
--==== 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 +@ConfigProperty+ for being configurable.
--
--
--==== Accessing Supplier instances
--
--In many cases you want to create a supplier that simply creates instances that are correctly configured as defined
--by the current context. This can be done using +Suppliers+:
--
--[source, java]
----------------------------------------------
--Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
-- new Supplier<Tenant>(){
-- public Tenant get(){
-- return new Tenant();
-- }
--});
----------------------------------------------
--
--With Java 8 it's even more simple:
--
--[source, java]
----------------------------------------------
--Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
-- Tenant::new);
----------------------------------------------
--
--Hereby this annotation can be used in multiple ways and combined with other annotations such as
--+@WithLoadPolicy+, +@WithConverter+.
--
--
--==== Minimal Example
--
--To illustrate the mechanism below the most simple variant of a configured class is given:
--
--[source,java]
--.Most simple configured class
----------------------------------------------
--pubic class ConfiguredItem{
-- @Config
-- private String aValue;
--}
----------------------------------------------
--
--When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+,
--the following is happening:
--
--* The current valid +Config+ is evaluated by calling +Config cfg = ConfigProvider.getConfig();+
--* The current property value (String) is evaluated by calling +cfg.getValue("aValue", Type.class);+
-- for each possible key (mutliple keys are possible).
--* if not successful, an error is thrown
--* On success, since no type conversion is involved, the value is injected.
--
--
--=== The Annotations in detail
--
--==== Using `@ConfigProperty`
--
--This is the main JSR annotation targeting a field in a class for configuration injection.
--
--
--===== Evaluating of _configuration keys_
--
--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
----------------------------------------------
--
--
--This behaviour can be adapted, e.g. by using the `@ConfigDefaultSections` annotation on the
--declaring type:
--
----------------------------------------------
--@ConfigDefaultSections("a.b.c", "deprecated")
--pubic class MyClass{
-- @ConfigProperty
-- private String myField;
--}
----------------------------------------------
--
--This will result in a modified lookup chain as illustrated below:
--
--[source, listing]
----------------------------------------------
--a.b.c.myField
--a.b.c.my-field
--deprecated.myField
--deprecated.my-field
----------------------------------------------
--
--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{
-- @ConfigProperty("myField" /* relative */)
-- @ConfigFallbackKeys("[absolute.key]")
-- private String myField;
--}
----------------------------------------------
--
--This will result in a lookup chain as illustrated below:
--
--[source, listing]
----------------------------------------------
--a.b.c.myField
--absolute.key # default sections are ignored
----------------------------------------------
--
--
--===== Using defaults
--
--In the next example we explicitly define the _default_ property value:
--[source,java]
----------------------------------------------
--pubic class ConfiguredItem{
--
-- @ConfigProperty(key="aValue", defaultValue="${env:java.version}")
-- @ConfigFallbackKeys({"a.b.value","a.b.deprecated.value"})
-- private String aValue;
--}
----------------------------------------------
--
--
--==== Automatically inject all items using `@ConfigAutoInject`
--
--Using `@ConfigAutoDetect` allows you to automatically select all properties found for
--configuration injection:
--
--[source,java]
----------------------------------------------
--@ConfigAutoDetect
--pubic class ConfiguredItem{
--
-- private transient int sum;
--
-- private String a;
-- private String b;
-- Private String c;
--}
----------------------------------------------
--
--Adding the `@NoConfig` annotation prevents a field or method to be auto-detected from
--configuration. This is especially useful, if a type is annotated as @ConfigAutoDetect 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 property converters using `@WithConverter`
--
--The @WithConverter annotation allows you to define a class of type +Converter+, to be applied
--on a property configured to convert the String value to the expected injected type. This can be used for
--various use cases, e.g. adding custom formats, config models, decryption.
--
--[source,java]
----------------------------------------------
--
--pubic class ConfiguredItem{
--
-- @WithConverter(MyPropertyConverter.class)
-- @ConfigProperty
-- private String a;
--
--}
----------------------------------------------
--
--
--==== Inject a `DynamicValue`
--
--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{
--
-- @ConfigProperty(key="aValue", defaultValue="${env:java.version}")
-- private DynamicValue aValue;
--}
----------------------------------------------
--
--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 LoadPolicy 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
--
--Similar to CDI Tamaya publishes Configuration events, when instances were configured. It depends on the effective
--event backend in use, if and how events are published:
--
--* when you have the CDI extension active events are published using the default CDI event mechanism.
--* in all other scenarios events are delegated to the +tamaya-events+ module, if available,
--* if no event delegation is available no events are published.
--
--The event published is very simple:
--
--[source,java]
----------------------------------------------
--public interface ConfiguredType {
-- Class getType();
-- String getName();
-- Collection<ConfiguredField> getConfiguredFields();
-- Collection<ConfiguredMethod> getConfiguredMethods();
-- void configure(Object instance, Configuration config);
--}
--
--public interface ConfiguredField {
-- Class<?> getType();
-- Collection<String> getConfiguredKeys();
-- String getName();
-- String getSignature();
-- Field getAnnotatedField();
-- void configure(Object instance, Configuration config);
--}
--
--public interface ConfiguredMethod {
-- Collection<String> getConfiguredKeys();
-- Class<?>[] getParameterTypes();
-- Method getAnnotatedMethod();
-- String getName();
-- String getSignature();
-- void configure(Object instance, Configuration config);
--}
------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_jndi.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_jndi.adoc
index a167e9e,a167e9e..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_jndi.adoc
+++ /dev/null
@@@ -1,68 -1,68 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration with JNDI
--
--toc::[]
--
--
--[[JNDI]]
--== Integration with JNDI (Extension Module)
--Tamaya _JNDI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _JNDI_ provides a simple +ConfigySource+ that reads values from a
--JNDI context.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _jndi_ as a configuration backend you only must add the corresponding dependency to
--your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-jndi</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Functionality Provided
--
--Main artifact is the +JNDIConfigSource+ class, which implements a
--property source based on a JNDI context:
--
--[source, java]
-------------------------------------------------
--public class JNDIPropertySource extends BasePropertySource {
--
-- public JNDIPropertySource(String name, Context context);
-- public JNDIPropertySource(String name) throws NamingException;
-- public JNDIPropertySource() throws NamingException;
--
-- public void setScannable(boolean scannable);
--
-- [...]
--}
-------------------------------------------------
--
--By default the property source is _non scannable_, so a call the `getProperties()`
--will return an empty map instance. After calling `setScannable(true);` a call to
--`getProperties()` will return a String representation of the JNDI tree. Hereby
--leaves of the tree are converted using `String.valueOf(leaveObject)`.
--
--This module automatically registers an instance of +JNDIConfigSource+ with a
--default ordinal of +200+.
--
--You can extend this class or manually instantiate it, e.g. as part of a
--+ConfigSourceProvider+. If no `Context` is passed explicitly, a new
--+InitialContext+ is created, without any environment parameters set.