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.
