http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/cddd52a8/documentation/extensions/mod_events.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_events.html b/documentation/extensions/mod_events.html index 1600f4a..909c2de 100644 --- a/documentation/extensions/mod_events.html +++ b/documentation/extensions/mod_events.html @@ -125,67 +125,60 @@ <h1>Apache Tamaya - Extension: Events</h1> </div> - <p><em>2018-04-26</em></p> - - <p><div id="preamble"> -<div class="sectionbody"> -<!-- toc disabled --> -</div> -</div> -<div class="sect1"> -<h2 id="Events">Tamaya Events (Extension Module)</h2> -<div class="sectionbody"> -<div class="paragraph"> -<p>Tamaya <em>Events</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> for further details.</p> -</div> -<div class="sect2"> -<h3 id="_what_functionality_this_module_provides">What functionality this module provides ?</h3> -<div class="paragraph"> -<p>Tamaya <em>Events</em> provides a mechanism to publish and subscribe to ConfigEvent<T> instances. -This module implements ConfigChange or PropertySourceChange 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 Configuration or a PropertySource. -The extension also provides a <em>Singleton accessor</em> which allows to register/unregister -listeners for changes and the period, when configuration should be scanned for -any changes.</p> -</div> -<div class="paragraph"> -<p>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.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_compatibility">Compatibility</h3> -<div class="paragraph"> -<p>The module is based on Java 7, so it can be used with Java 7 and beyond.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_installation">Installation</h3> -<div class="paragraph"> -<p>To benefit from configuration event support you only must add the corresponding dependency to your module:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> + <p><em>2018-05-17</em></p> + + <p><div id="preamble"> + <div class="sectionbody"> + <!-- toc disabled --> + </div> +</div> +<div class="sect1"> + <h2 id="Events">Tamaya Events (Extension Module)</h2> + <div class="sectionbody"> + <div class="paragraph"> + <p>Tamaya <em>Events</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> for further details.</p> + </div> + <div class="sect2"> + <h3 id="_what_functionality_this_module_provides">What functionality this module provides ?</h3> + <div class="paragraph"> + <p>Tamaya <em>Events</em> provides a mechanism to publish and subscribe to ConfigEvent<T> instances. This module implements ConfigChange or PropertySourceChange 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 Configuration or a PropertySource. The extension also provides a <em>Singleton accessor</em> which allows to register/unregister listeners for changes and the period, when configuration should be scanned for any changes.</p> + </div> + <div class="paragraph"> + <p>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.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_compatibility">Compatibility</h3> + <div class="paragraph"> + <p>The module is based on Java 7, so it can be used with Java 7 and beyond.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_installation">Installation</h3> + <div class="paragraph"> + <p>To benefit from configuration event support you only must add the corresponding dependency to your module:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> <groupId>org.apache.tamaya.ext</groupId> <artifactId>tamaya-events</artifactId> <version>{tamaya_version}</version> -</dependency></code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_core_architecture">Core Architecture</h3> -<div class="paragraph"> -<p>The core of the module are the ConfigEventListener and the ConfigEvent interfaces, -which defines an abstraction for event handling and observation:</p> -</div> -<div class="listingblock"> -<div class="title">ConfigEvent</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ConfigEvent<T> { +</dependency></code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_core_architecture">Core Architecture</h3> + <div class="paragraph"> + <p>The core of the module are the ConfigEventListener and the ConfigEvent interfaces, which defines an abstraction for event handling and observation:</p> + </div> + <div class="listingblock"> + <div class="title"> + ConfigEvent + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ConfigEvent<T> { Class<T> getResourceType(); T getResource(); @@ -198,45 +191,31 @@ public interface ConfigEventListener { void onConfigEvent(ConfigEvent<?> event); -}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>Hereby the payload <em>T</em> 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.</p> -</div> -<div class="paragraph"> -<p>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 <em>Guava</em> library. But users can replace this mechanism as needed. For -more details refer to the SPI section later in this guide.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_the_configeventmanager_singleton">The ConfigEventManager Singleton</h3> -<div class="paragraph"> -<p>Main entry point of the events module is the ConfigEventManager singleton class, which provides static accessor -methods to the extension’s functionality:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p><em>Adding/removing</em> of ConfigChangeListener instances, either globally or per event type.</p> -</li> -<li> -<p><em>Firing configuration events</em> synchronously or asyncronously (mostly called by framework code).</p> -</li> -<li> -<p><em>Configuring the monitor</em> that periodically checks for changes on the global Configuration provided -by ConfigurationProvider.getConfiguration().</p> -</li> -</ul> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigEventManager { +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Hereby the payload <em>T</em> 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.</p> + </div> + <div class="paragraph"> + <p>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 <em>Guava</em> library. But users can replace this mechanism as needed. For more details refer to the SPI section later in this guide.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_the_configeventmanager_singleton">The ConfigEventManager Singleton</h3> + <div class="paragraph"> + <p>Main entry point of the events module is the ConfigEventManager singleton class, which provides static accessor methods to the extensionâs functionality:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><em>Adding/removing</em> of ConfigChangeListener instances, either globally or per event type.</p> </li> + <li> <p><em>Firing configuration events</em> synchronously or asyncronously (mostly called by framework code).</p> </li> + <li> <p><em>Configuring the monitor</em> that periodically checks for changes on the global Configuration provided by ConfigurationProvider.getConfiguration().</p> </li> + </ul> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigEventManager { private ConfigEventManager() {} @@ -257,51 +236,39 @@ by ConfigurationProvider.getConfiguration().</p> public long getChangeMonitoringPeriod(); public void setChangeMonitoringPeriod(long millis); -}</code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_modelling_configuration_changes_as_events">Modelling configuration changes as events</h3> -<div class="paragraph"> -<p>This module provides a serializable and thread-safe abstraction modelling a -configuration change, which is anything of the following</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>additional, <em>new</em> configuration entries</p> -</li> -<li> -<p><em>removed</em> configuration entries</p> -</li> -<li> -<p><em>changes</em> on existing entries</p> -</li> -</ul> -</div> -<div class="paragraph"> -<p>A collection of changes</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>on a Configuration is modelled by the ConfigurationChange class</p> -</li> -<li> -<p>on a PropertySource is modelled by the PropertySourceChange class</p> -</li> -</ul> -</div> -<div class="sect3"> -<h4 id="_configuration_changes">Configuration Changes</h4> -<div class="paragraph"> -<p>A set of changes on a Configuration is described by a ConfigurationChange -as follows:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigurationChange implements ConfigEvent<Configuration>, Serializable{ +}</code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_modelling_configuration_changes_as_events">Modelling configuration changes as events</h3> + <div class="paragraph"> + <p>This module provides a serializable and thread-safe abstraction modelling a configuration change, which is anything of the following</p> + </div> + <div class="ulist"> + <ul> + <li> <p>additional, <em>new</em> configuration entries</p> </li> + <li> <p><em>removed</em> configuration entries</p> </li> + <li> <p><em>changes</em> on existing entries</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>A collection of changes</p> + </div> + <div class="ulist"> + <ul> + <li> <p>on a Configuration is modelled by the ConfigurationChange class</p> </li> + <li> <p>on a PropertySource is modelled by the PropertySourceChange class</p> </li> + </ul> + </div> + <div class="sect3"> + <h4 id="_configuration_changes">Configuration Changes</h4> + <div class="paragraph"> + <p>A set of changes on a Configuration is described by a ConfigurationChange as follows:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigurationChange implements ConfigEvent<Configuration>, Serializable{ public static ConfigurationChange emptyChangeSet(Configuration configuration); @@ -327,48 +294,43 @@ as follows:</p> public boolean isUpdated(String key); public boolean containsKey(String key); public boolean isEmpty(); -}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>New instances of ConfigurationChange hereby can be created using a -fluent ConfigurationChangeBuilder:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">Configuration config = ...; +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>New instances of ConfigurationChange hereby can be created using a fluent ConfigurationChangeBuilder:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">Configuration config = ...; ConfigurationChange change = ConfigurationChangeBuilder.of(config) .addChange("MyKey", "newValue") - .removeKeys("myRemovedKey").build();</code></pre> -</div> -</div> -<div class="paragraph"> -<p>Also it is possible to directly compare 2 instances of Configuration, -which results in a ConfigurationChange that -reflects the differences between the two configurations passed:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">Comparing 2 configurations + .removeKeys("myRemovedKey").build();</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Also it is possible to directly compare 2 instances of Configuration, which results in a ConfigurationChange that reflects the differences between the two configurations passed:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">Comparing 2 configurations ------------------------------------------------------- Configuration config = ...; Configuration changedConfig = ...; ConfigurationChange change = ConfigurationChangeBuilder.of(config) .addChanges(changedConfig).build(); --------------------------------------------------------</code></pre> -</div> -</div> -<div class="paragraph"> -<p>So a ConfigurationChange describes all the changes detected on a Configuration. -This allows you to publish instances of this class as events to all registered -listeners (observer pattern). -For listening to ConfigurationChange events you must implement the -ConfigEventListener functional interface:</p> -</div> -<div class="listingblock"> -<div class="title">Implementing a ConfigChangeListener</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class MyConfigChangeListener implements ConfigEventListener<ConfigurationChange>{ +-------------------------------------------------------</code></pre> + </div> + </div> + <div class="paragraph"> + <p>So a ConfigurationChange describes all the changes detected on a Configuration. This allows you to publish instances of this class as events to all registered listeners (observer pattern). For listening to ConfigurationChange events you must implement the ConfigEventListener functional interface:</p> + </div> + <div class="listingblock"> + <div class="title"> + Implementing a ConfigChangeListener + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class MyConfigChangeListener implements ConfigEventListener<ConfigurationChange>{ private Configuration config = ConfigurationProvider.getConfiguration(); @@ -380,120 +342,98 @@ ConfigEventListener functional interface:</p> } } -}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>You can <strong>register</strong> your implementation as illustrated below:</p> -</div> -<div class="olist arabic"> -<ol class="arabic"> -<li> -<p>Manually by calling ConfigEventManager.addListener(new MyConfigChangeListener())</p> -</li> -<li> -<p>Automatically by registering your listener using the ServiceLoader under -META-INF/services/org.apache.tamaya.events.ConfigEventListener</p> -</li> -</ol> -</div> -<div class="paragraph"> -<p>Registering programmatically also allows you to define additional constraint, -to filter out all kind of events you are not interested in.</p> -</div> -<div class="admonitionblock note"> -<table> -<tr> -<td class="icon"> -<div class="title">Note</div> -</td> -<td class="content"> -By default detection of configuration changes is not enabled. To enable it, call -ConfigEventManager.enableChangeMonitoring(true). -</td> -</tr> -</table> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_propertysource_changes">PropertySource Changes</h3> -<div class="paragraph"> -<p>Beside that a whole Configuration changes, also a PropertySource can change, -e.g. by a configuration file edited on the fly. This is similarly to a -ConfigurationChange reflected by the classes PropertySourceChange, -PropertySourceChangeBuilder.</p> -</div> -<div class="sect3"> -<h4 id="_monitoring_of_configuration_changes">Monitoring of configuration changes</h4> -<div class="paragraph"> -<p>The ConfigEventManager supports <strong>active monitoring of the current configuration</strong> to trigger corresponding change -events to listeners registered. <strong>This feature is deactivated by default</strong>, but can be enabled by calling -ConfigEventManager.enableChangeMonitoring(true);. This feature avoids regularly polling your local Configuration for -any kind of changes. If a change has been encountered Tamaya identifies it and triggers corresponding -ConfigurationChange events automatically.</p> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_freezing_configurations_and_propertysources">Freezing Configurations and PropertySources</h3> -<div class="paragraph"> -<p>Configuration instances as well as PropertySources are explicitly not required to be serializable. To enable easy -serialization of these types a Configuration's <strong>current state can be frozen</strong> (e.g. for later comparison with a newly -loaded version). Freezing hereby means</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>all key/values are read-out by calling the getProperties() method.</p> -</li> -<li> -<p>a meta data entry is added of the form _frozenAt=223273777652325677, whichdefines the UTC timestamp in -milliseconds when this instance was frozen.</p> -</li> -<li> -<p>if not already defined an _id property will be added to the Configuration containing the -identifier of the configuration.</p> -</li> -</ul> -</div> -<div class="paragraph"> -<p>In code freezing is a no-brainer:</p> -</div> -<div class="listingblock"> -<div class="title">Freezing the current Configuration</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">Configuration config = ConfigurationProvider.getConfiguration(); -Configuration frozenConfig = FrozenConfiguration.of(config);</code></pre> -</div> -</div> -<div class="olist lowerroman"> -<ol class="lowerroman" type="i"> -<li> -<p>and similarly for a PropertySource:</p> -</li> -</ol> -</div> -<div class="listingblock"> -<div class="title">Freezing the current Configuration</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">PropertySource propertySource = ...; -PropertySource frozenSource = FrozenPropertySource.of(propertySource);</code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_spis">SPIs</h3> -<div class="paragraph"> -<p>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).</p> -</div> -<div class="listingblock"> -<div class="title">SPI: ConfigEventSpi</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ConfigEventManagerSpi { +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>You can <strong>register</strong> your implementation as illustrated below:</p> + </div> + <div class="olist arabic"> + <ol class="arabic"> + <li> <p>Manually by calling ConfigEventManager.addListener(new MyConfigChangeListener())</p> </li> + <li> <p>Automatically by registering your listener using the ServiceLoader under META-INF/services/org.apache.tamaya.events.ConfigEventListener</p> </li> + </ol> + </div> + <div class="paragraph"> + <p>Registering programmatically also allows you to define additional constraint, to filter out all kind of events you are not interested in.</p> + </div> + <div class="admonitionblock note"> + <table> + <tbody> + <tr> + <td class="icon"> + <div class="title"> + Note + </div> </td> + <td class="content"> By default detection of configuration changes is not enabled. To enable it, call ConfigEventManager.enableChangeMonitoring(true). </td> + </tr> + </tbody> + </table> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_propertysource_changes">PropertySource Changes</h3> + <div class="paragraph"> + <p>Beside that a whole Configuration changes, also a PropertySource can change, e.g. by a configuration file edited on the fly. This is similarly to a ConfigurationChange reflected by the classes PropertySourceChange, PropertySourceChangeBuilder.</p> + </div> + <div class="sect3"> + <h4 id="_monitoring_of_configuration_changes">Monitoring of configuration changes</h4> + <div class="paragraph"> + <p>The ConfigEventManager supports <strong>active monitoring of the current configuration</strong> to trigger corresponding change events to listeners registered. <strong>This feature is deactivated by default</strong>, but can be enabled by calling ConfigEventManager.enableChangeMonitoring(true);. This feature avoids regularly polling your local Configuration for any kind of changes. If a change has been encountered Tamaya identifies it and triggers corresponding ConfigurationChange events automatically.</p> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_freezing_configurations_and_propertysources">Freezing Configurations and PropertySources</h3> + <div class="paragraph"> + <p>Configuration instances as well as PropertySources are explicitly not required to be serializable. To enable easy serialization of these types a Configuration's <strong>current state can be frozen</strong> (e.g. for later comparison with a newly loaded version). Freezing hereby means</p> + </div> + <div class="ulist"> + <ul> + <li> <p>all key/values are read-out by calling the getProperties() method.</p> </li> + <li> <p>a meta data entry is added of the form _frozenAt=223273777652325677, whichdefines the UTC timestamp in milliseconds when this instance was frozen.</p> </li> + <li> <p>if not already defined an _id property will be added to the Configuration containing the identifier of the configuration.</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>In code freezing is a no-brainer:</p> + </div> + <div class="listingblock"> + <div class="title"> + Freezing the current Configuration + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">Configuration config = ConfigurationProvider.getConfiguration(); +Configuration frozenConfig = FrozenConfiguration.of(config);</code></pre> + </div> + </div> + <div class="olist lowerroman"> + <ol class="lowerroman" type="i"> + <li> <p>and similarly for a PropertySource:</p> </li> + </ol> + </div> + <div class="listingblock"> + <div class="title"> + Freezing the current Configuration + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">PropertySource propertySource = ...; +PropertySource frozenSource = FrozenPropertySource.of(propertySource);</code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_spis">SPIs</h3> + <div class="paragraph"> + <p>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).</p> + </div> + <div class="listingblock"> + <div class="title"> + SPI: ConfigEventSpi + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ConfigEventManagerSpi { <T> void addListener(ConfigEventListener l); <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType); @@ -509,11 +449,11 @@ active (by default using the Java ServiceLoader mechanism).</p> void setChangeMonitoringPeriod(long millis); boolean isChangeMonitorActive(); void enableChangeMonitor(boolean enable); -}</code></pre> -</div> -</div> -</div> -</div> +}</code></pre> + </div> + </div> + </div> + </div> </div></p> <hr /> @@ -525,8 +465,8 @@ active (by default using the Java ServiceLoader mechanism).</p> <div id="footer"> <div class="container"> <p class="muted credit">© 2014-<span>2018</span> Apache Software Foundation | Mixed with <a href="http://getbootstrap.com/";>Bootstrap v3.1.1</a> - | Baked with <a href="http://jbake.org";>JBake <span>v2.5.1</span></a> - at <span>2018-05-03</span> | + | Baked with <a href="http://jbake.org";>JBake <span>v2.6.1</span></a> + at <span>2018-05-17</span> | <a class="twitter-follow-button" data-show-count="false" href="https://twitter.com/tamayaconf";>Follow @tamayaconf</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> </p> <p>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/cddd52a8/documentation/extensions/mod_features.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_features.html b/documentation/extensions/mod_features.html index 9ad4626..ecefb3c 100644 --- a/documentation/extensions/mod_features.html +++ b/documentation/extensions/mod_features.html @@ -125,57 +125,54 @@ <h1>Apache Tamaya - Extension: Features Check</h1> </div> - <p><em>2018-04-26</em></p> + <p><em>2018-05-17</em></p> - <p><div id="preamble"> -<div class="sectionbody"> -<!-- toc disabled --> -</div> -</div> -<div class="sect1"> -<h2 id="Features">Tamaya Features Check (Extension Module)</h2> -<div class="sectionbody"> -<div class="paragraph"> -<p>Tamaya <em>Features</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> for further details.</p> -</div> -<div class="sect2"> -<h3 id="_what_functionality_this_module_provides">What functionality this module provides ?</h3> -<div class="paragraph"> -<p>Tamaya <em>Features</em> provides a simple Features singleton that allows to check -which Tamaya Extensions are currently on the classpath.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_compatibility">Compatibility</h3> -<div class="paragraph"> -<p>The module is based on Java 7, so it will not run on Java 7 and beyond.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_installation">Installation</h3> -<div class="paragraph"> -<p>To use Tamaya <em>Features</em> you only must add the corresponding dependency to -your module:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> + <p><div id="preamble"> + <div class="sectionbody"> + <!-- toc disabled --> + </div> +</div> +<div class="sect1"> + <h2 id="Features">Tamaya Features Check (Extension Module)</h2> + <div class="sectionbody"> + <div class="paragraph"> + <p>Tamaya <em>Features</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> for further details.</p> + </div> + <div class="sect2"> + <h3 id="_what_functionality_this_module_provides">What functionality this module provides ?</h3> + <div class="paragraph"> + <p>Tamaya <em>Features</em> provides a simple Features singleton that allows to check which Tamaya Extensions are currently on the classpath.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_compatibility">Compatibility</h3> + <div class="paragraph"> + <p>The module is based on Java 7, so it will not run on Java 7 and beyond.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_installation">Installation</h3> + <div class="paragraph"> + <p>To use Tamaya <em>Features</em> you only must add the corresponding dependency to your module:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> <groupId>org.apache.tamaya.ext</groupId> <artifactId>tamaya-features</artifactId> <version>{tamaya_version}</version> -</dependency></code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_the_functionality_provided">The Functionality Provided</h3> -<div class="paragraph"> -<p>Main artifact is the Features singleton, which provides various static methods -to check, which Tamaya extensions are currently loaded.</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class Features { +</dependency></code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_the_functionality_provided">The Functionality Provided</h3> + <div class="paragraph"> + <p>Main artifact is the Features singleton, which provides various static methods to check, which Tamaya extensions are currently loaded.</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class Features { private Features(){} @@ -198,66 +195,32 @@ to check, which Tamaya extensions are currently loaded.</p> public static boolean extOSGIAvailable(); public static boolean checkClassIsLoadable(String classname); -}</code></pre> -</div> -</div> -<div class="ulist"> -<ul> -<li> -<p>eventsAvailable(); checks for the <a href="mod_events.html"><em>tamaya_events</em></a> module.</p> -</li> -<li> -<p>formatsAvailable(); checks for the <a href="mod_formats.html"><em>tamaya_formats</em></a> module.</p> -</li> -<li> -<p>tamayaCoreAvailable(); checks if the <a href="core.html"><em>Tamaya core</em></a> implementation is loaded.</p> -</li> -<li> -<p>injectionAvailable(); checks for the <a href="mod_injection.html"><em>tamaya_injection</em></a> SE module.</p> -</li> -<li> -<p>injectionCDIAvailable(); checks for the <a href="mod_cdi.html"><em>tamaya CDI</em></a> modules.</p> -</li> -<li> -<p>mutableConfigAvailable(); checks for the <a href="mod_mutableconfig.html"><em>tamaya_mutableconfig</em></a> module.</p> -</li> -<li> -<p>optionalAvailable(); checks for the <a href="mod_optional.html"><em>tamaya_optional</em></a> module.</p> -</li> -<li> -<p>resolverAvailable(); checks for the <a href="mod_resolver.html"><em>tamaya_resolver</em></a> module.</p> -</li> -<li> -<p>resourcesAvailable(); checks for the <a href="mod_reources.html"><em>tamaya_resources</em></a> module.</p> -</li> -<li> -<p>spiSupportAvailable(); checks for the <a href="mod_spisupport.html"><em>tamaya_spisupport</em></a> module.</p> -</li> -<li> -<p>filterSupportAvailable(); checks for the <a href="mod_filter.html"><em>tamaya_filter</em></a> module.</p> -</li> -<li> -<p>springAvailable(); checks for the <a href="mod_spring.html"><em>tamaya_spring</em></a> module.</p> -</li> -<li> -<p>jndiAvailable(); checks for the <a href="mod_jndi.html"><em>tamaya_jndi</em></a> module.</p> -</li> -<li> -<p>extJndiAvailable(); checks if creation of a new <code>InitialContext</code> is successful.</p> -</li> -<li> -<p>extSpringCoreAvailable(); checks if Spring Core is on the classpath.</p> -</li> -<li> -<p>extOSGIAvailable(); checks the OSGI framework is on the classpath.</p> -</li> -<li> -<p>Finally checkClassIsLoaded(String) tries to load a class. If it fails, <code>false</code> is returned.</p> -</li> -</ul> -</div> -</div> -</div> +}</code></pre> + </div> + </div> + <div class="ulist"> + <ul> + <li> <p>eventsAvailable(); checks for the <a href="mod_events.html"><em>tamaya_events</em></a> module.</p> </li> + <li> <p>formatsAvailable(); checks for the <a href="mod_formats.html"><em>tamaya_formats</em></a> module.</p> </li> + <li> <p>tamayaCoreAvailable(); checks if the <a href="core.html"><em>Tamaya core</em></a> implementation is loaded.</p> </li> + <li> <p>injectionAvailable(); checks for the <a href="mod_injection.html"><em>tamaya_injection</em></a> SE module.</p> </li> + <li> <p>injectionCDIAvailable(); checks for the <a href="mod_cdi.html"><em>tamaya CDI</em></a> modules.</p> </li> + <li> <p>mutableConfigAvailable(); checks for the <a href="mod_mutableconfig.html"><em>tamaya_mutableconfig</em></a> module.</p> </li> + <li> <p>optionalAvailable(); checks for the <a href="mod_optional.html"><em>tamaya_optional</em></a> module.</p> </li> + <li> <p>resolverAvailable(); checks for the <a href="mod_resolver.html"><em>tamaya_resolver</em></a> module.</p> </li> + <li> <p>resourcesAvailable(); checks for the <a href="mod_reources.html"><em>tamaya_resources</em></a> module.</p> </li> + <li> <p>spiSupportAvailable(); checks for the <a href="mod_spisupport.html"><em>tamaya_spisupport</em></a> module.</p> </li> + <li> <p>filterSupportAvailable(); checks for the <a href="mod_filter.html"><em>tamaya_filter</em></a> module.</p> </li> + <li> <p>springAvailable(); checks for the <a href="mod_spring.html"><em>tamaya_spring</em></a> module.</p> </li> + <li> <p>jndiAvailable(); checks for the <a href="mod_jndi.html"><em>tamaya_jndi</em></a> module.</p> </li> + <li> <p>extJndiAvailable(); checks if creation of a new <code>InitialContext</code> is successful.</p> </li> + <li> <p>extSpringCoreAvailable(); checks if Spring Core is on the classpath.</p> </li> + <li> <p>extOSGIAvailable(); checks the OSGI framework is on the classpath.</p> </li> + <li> <p>Finally checkClassIsLoaded(String) tries to load a class. If it fails, <code>false</code> is returned.</p> </li> + </ul> + </div> + </div> + </div> </div></p> <hr /> @@ -269,8 +232,8 @@ to check, which Tamaya extensions are currently loaded.</p> <div id="footer"> <div class="container"> <p class="muted credit">© 2014-<span>2018</span> Apache Software Foundation | Mixed with <a href="http://getbootstrap.com/";>Bootstrap v3.1.1</a> - | Baked with <a href="http://jbake.org";>JBake <span>v2.5.1</span></a> - at <span>2018-05-03</span> | + | Baked with <a href="http://jbake.org";>JBake <span>v2.6.1</span></a> + at <span>2018-05-17</span> | <a class="twitter-follow-button" data-show-count="false" href="https://twitter.com/tamayaconf";>Follow @tamayaconf</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> </p> <p> http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/cddd52a8/documentation/extensions/mod_filter.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_filter.html b/documentation/extensions/mod_filter.html index 45c9a96..39ffc6f 100644 --- a/documentation/extensions/mod_filter.html +++ b/documentation/extensions/mod_filter.html @@ -125,75 +125,65 @@ <h1>Apache Tamaya - Extension: User Filtering</h1> </div> - <p><em>2018-04-26</em></p> + <p><em>2018-05-17</em></p> - <p><div id="preamble"> -<div class="sectionbody"> -<!-- toc disabled --> -</div> -</div> -<div class="sect1"> -<h2 id="Filter">User Filtering (Extension Module)</h2> -<div class="sectionbody"> -<div class="paragraph"> -<p>Tamaya <em>Filter</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> for further details.</p> -</div> -<div class="sect2"> -<h3 id="_what_functionality_this_module_provides">What functionality this module provides ?</h3> -<div class="paragraph"> -<p>Tamaya <em>Filter</em> provides a simple singleton accessor that allows to explicitly add PropertyFilter instances -active on the current thread only. This can be very useful in many scenarios, 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.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_compatibility">Compatibility</h3> -<div class="paragraph"> -<p>The module is based on Java 7, so it will not run on Java 7 and beyond.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_installation">Installation</h3> -<div class="paragraph"> -<p>To benefit from filter support you only must add the corresponding dependency to your module:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> + <p><div id="preamble"> + <div class="sectionbody"> + <!-- toc disabled --> + </div> +</div> +<div class="sect1"> + <h2 id="Filter">User Filtering (Extension Module)</h2> + <div class="sectionbody"> + <div class="paragraph"> + <p>Tamaya <em>Filter</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> for further details.</p> + </div> + <div class="sect2"> + <h3 id="_what_functionality_this_module_provides">What functionality this module provides ?</h3> + <div class="paragraph"> + <p>Tamaya <em>Filter</em> provides a simple singleton accessor that allows to explicitly add PropertyFilter instances active on the current thread only. This can be very useful in many scenarios, 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.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_compatibility">Compatibility</h3> + <div class="paragraph"> + <p>The module is based on Java 7, so it will not run on Java 7 and beyond.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_installation">Installation</h3> + <div class="paragraph"> + <p>To benefit from filter support you only must add the corresponding dependency to your module:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> <groupId>org.apache.tamaya.ext</groupId> <artifactId>tamaya-filter</artifactId> <version>{tamaya_version}</version> -</dependency></code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_the_extensions_provided">The Extensions Provided</h3> -<div class="paragraph"> -<p>Tamaya Filter comes basically with 3 artifacts:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>The org.apache.tamaya.filter.ConfigurationFilter provides several static methods to register PropertyFilter -instances on the current thread.</p> -</li> -<li> -<p>The org.apache.tamaya.filter.DefaultMetdataFilter is a PropertyFilter with hides all entries starting with -an underscore ('_'), when a full property map is accessed.</p> -</li> -</ul> -</div> -<div class="sect3"> -<h4 id="_the_configurationfilter">The ConfigurationFilter</h4> -<div class="paragraph"> -<p>The accessor mentioned implements the API for for adding PropertyFilters to the current thread (as thread local):</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigurationFilter implements PropertyFilter{ +</dependency></code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_the_extensions_provided">The Extensions Provided</h3> + <div class="paragraph"> + <p>Tamaya Filter comes basically with 3 artifacts:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>The org.apache.tamaya.filter.ConfigurationFilter provides several static methods to register PropertyFilter instances on the current thread.</p> </li> + <li> <p>The org.apache.tamaya.filter.DefaultMetdataFilter is a PropertyFilter with hides all entries starting with an underscore ('_'), when a full property map is accessed.</p> </li> + </ul> + </div> + <div class="sect3"> + <h4 id="_the_configurationfilter">The ConfigurationFilter</h4> + <div class="paragraph"> + <p>The accessor mentioned implements the API for for adding PropertyFilters to the current thread (as thread local):</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigurationFilter implements PropertyFilter{ ... @@ -224,16 +214,15 @@ an underscore ('_'), when a full property map is accessed.</p> ... -}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>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:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">try { +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>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:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">try { ConfigurationFilter.getMapFilters().addFilter(new myFilter()); // do your code with filtering active @@ -241,16 +230,15 @@ is part of this module, So you can add a customized filter as follows:</p> finally { // cleanup ConfigurationFilter.clearFilters(); -}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>The FilterContext is a simple structure just providing some handy accessors to the dynamic thread-local -managed filters:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class FilterContext implements PropertyFilter { +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>The FilterContext is a simple structure just providing some handy accessors to the dynamic thread-local managed filters:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class FilterContext implements PropertyFilter { public void addIncludes(PropertyFilter filter); public void addExcludes(int pos, PropertyFilter filter); @@ -260,12 +248,12 @@ managed filters:</p> public void setExcludes(Collection<PropertyFilter> filters); public List<PropertyFilter> getFilters(); -}</code></pre> -</div> -</div> -</div> -</div> -</div> +}</code></pre> + </div> + </div> + </div> + </div> + </div> </div></p> <hr /> @@ -277,8 +265,8 @@ managed filters:</p> <div id="footer"> <div class="container"> <p class="muted credit">© 2014-<span>2018</span> Apache Software Foundation | Mixed with <a href="http://getbootstrap.com/";>Bootstrap v3.1.1</a> - | Baked with <a href="http://jbake.org";>JBake <span>v2.5.1</span></a> - at <span>2018-05-03</span> | + | Baked with <a href="http://jbake.org";>JBake <span>v2.6.1</span></a> + at <span>2018-05-17</span> | <a class="twitter-follow-button" data-show-count="false" href="https://twitter.com/tamayaconf";>Follow @tamayaconf</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> </p> <p> http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/cddd52a8/documentation/extensions/mod_formats.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_formats.html b/documentation/extensions/mod_formats.html index c9bfac3..c704454 100644 --- a/documentation/extensions/mod_formats.html +++ b/documentation/extensions/mod_formats.html @@ -125,91 +125,75 @@ <h1>Apache Tamaya - Extension: Formats</h1> </div> - <p><em>2018-04-26</em></p> + <p><em>2018-05-17</em></p> - <p><div id="preamble"> -<div class="sectionbody"> -<!-- toc disabled --> -</div> -</div> -<div class="sect1"> -<h2 id="Formats">Tamaya Formats (Extension Module)</h2> -<div class="sectionbody"> -<div class="paragraph"> -<p>Tamaya <em>Formats</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> for further details.</p> -</div> -<div class="sect2"> -<h3 id="_what_functionality_this_module_provides">What functionality this module provides ?</h3> -<div class="paragraph"> -<p>Tamaya <em>Formats</em> provides an abstraction for configuration formats provding the following benefits:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>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 PropertySource instances must be created.</p> -</li> -<li> -<p>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.</p> -</li> -</ul> -</div> -</div> -<div class="sect2"> -<h3 id="_compatibility">Compatibility</h3> -<div class="paragraph"> -<p>The module is based on Java 7, so it can be used with Java 7 and beyond.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_installation">Installation</h3> -<div class="paragraph"> -<p>To use the formats module you only must add the corresponding dependency to your module:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> + <p><div id="preamble"> + <div class="sectionbody"> + <!-- toc disabled --> + </div> +</div> +<div class="sect1"> + <h2 id="Formats">Tamaya Formats (Extension Module)</h2> + <div class="sectionbody"> + <div class="paragraph"> + <p>Tamaya <em>Formats</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> for further details.</p> + </div> + <div class="sect2"> + <h3 id="_what_functionality_this_module_provides">What functionality this module provides ?</h3> + <div class="paragraph"> + <p>Tamaya <em>Formats</em> provides an abstraction for configuration formats provding the following benefits:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>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 PropertySource instances must be created.</p> </li> + <li> <p>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.</p> </li> + </ul> + </div> + </div> + <div class="sect2"> + <h3 id="_compatibility">Compatibility</h3> + <div class="paragraph"> + <p>The module is based on Java 7, so it can be used with Java 7 and beyond.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_installation">Installation</h3> + <div class="paragraph"> + <p>To use the formats module you only must add the corresponding dependency to your module:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> <groupId>org.apache.tamaya.ext</groupId> <artifactId>tamaya-formats</artifactId> <version>{tamaya_version}</version> -</dependency></code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_basic_concept">Basic Concept</h3> -<div class="paragraph"> -<p>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</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>an arbitrary configuration format (textual or binary)</p> -</li> -<li> -<p>a parser (ConfigurationFormat) that transfers a given format into an intermediate -representation (ConfigurationData).</p> -</li> -<li> -<p>an optional customization, implemented by a <em>factory method pattern</em> to adapt the mapping of ConfigurationData read -to a collection of PropertySources (they can have different ordinal semantics).</p> -</li> -</ul> -</div> -<div class="sect3"> -<h4 id="_configurationdata">ConfigurationData</h4> -<div class="paragraph"> -<p>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:</p> -</div> -<div class="listingblock"> -<div class="title">ConfigurationData</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigurationData { +</dependency></code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_basic_concept">Basic Concept</h3> + <div class="paragraph"> + <p>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</p> + </div> + <div class="ulist"> + <ul> + <li> <p>an arbitrary configuration format (textual or binary)</p> </li> + <li> <p>a parser (ConfigurationFormat) that transfers a given format into an intermediate representation (ConfigurationData).</p> </li> + <li> <p>an optional customization, implemented by a <em>factory method pattern</em> to adapt the mapping of ConfigurationData read to a collection of PropertySources (they can have different ordinal semantics).</p> </li> + </ul> + </div> + <div class="sect3"> + <h4 id="_configurationdata">ConfigurationData</h4> + <div class="paragraph"> + <p>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:</p> + </div> + <div class="listingblock"> + <div class="title"> + ConfigurationData + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigurationData { public ConfigurationFormat getFormat(); public String getResource(); @@ -222,92 +206,62 @@ ConfigurationData:</p> public Map<String,String> getCombinedProperties(); public boolean isEmpty(); -}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>In detail the data read from a file is organized into <em>sections</em> as follows:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>with getResource() and getFormat() the underlying resource and the format that read this data can be accessed.</p> -</li> -<li> -<p>properties can be owned by</p> -<div class="ulist"> -<ul> -<li> -<p>named sections</p> -</li> -<li> -<p>an (unnamed) default section</p> -</li> -</ul> -</div> -</li> -<li> -<p>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.</p> -</li> -<li> -<p>The method getSectionNames() returns a set of all section names.</p> -</li> -<li> -<p>With getSection(String name) a named section can be accessed.</p> -</li> -<li> -<p>With getDefaultSection() the 'default' section can be accessed. This is a convenience method.</p> -</li> -<li> -<p>With getCombinedProperties() a flattened entry map can be accessed built up (by default) out of</p> -<div class="ulist"> -<ul> -<li> -<p>all entries from the default section, without any changes.</p> -</li> -<li> -<p>all entries from named sections, where the key for each entry is prefix with the section name and a '::' separator.</p> -</li> -</ul> -</div> -</li> -<li> -<p>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.</p> -</li> -</ul> -</div> -</div> -<div class="sect3"> -<h4 id="_configurationformat">ConfigurationFormat</h4> -<div class="paragraph"> -<p>A ConfigurationFormat is basically an abstraction that reads a configuration resource (modelled by an InputStream) and -creates a corresponding ConfigurationData instance.</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ConfigurationFormat { +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>In detail the data read from a file is organized into <em>sections</em> as follows:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>with getResource() and getFormat() the underlying resource and the format that read this data can be accessed.</p> </li> + <li> <p>properties can be owned by</p> + <div class="ulist"> + <ul> + <li> <p>named sections</p> </li> + <li> <p>an (unnamed) default section</p> </li> + </ul> + </div> </li> + <li> <p>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.</p> </li> + <li> <p>The method getSectionNames() returns a set of all section names.</p> </li> + <li> <p>With getSection(String name) a named section can be accessed.</p> </li> + <li> <p>With getDefaultSection() the 'default' section can be accessed. This is a convenience method.</p> </li> + <li> <p>With getCombinedProperties() a flattened entry map can be accessed built up (by default) out of</p> + <div class="ulist"> + <ul> + <li> <p>all entries from the default section, without any changes.</p> </li> + <li> <p>all entries from named sections, where the key for each entry is prefix with the section name and a '::' separator.</p> </li> + </ul> + </div> </li> + <li> <p>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.</p> </li> + </ul> + </div> + </div> + <div class="sect3"> + <h4 id="_configurationformat">ConfigurationFormat</h4> + <div class="paragraph"> + <p>A ConfigurationFormat is basically an abstraction that reads a configuration resource (modelled by an InputStream) and creates a corresponding ConfigurationData instance.</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ConfigurationFormat { String getName(); boolean accepts(URL url); ConfigurationData readConfiguration(String resource, InputStream inputStream); -}</code></pre> -</div> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_creating_a_default_propertysource_for_a_configurationformat">Creating a default PropertySource for a ConfigurationFormat</h3> -<div class="paragraph"> -<p>The module defines a singleton ConfigurationFormats which provides -an easy to use API for creating ConfigurationData and PropertySources -using abstract ConfigurationFormat implementations:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigurationFormats { +}</code></pre> + </div> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_creating_a_default_propertysource_for_a_configurationformat">Creating a default PropertySource for a ConfigurationFormat</h3> + <div class="paragraph"> + <p>The module defines a singleton ConfigurationFormats which provides an easy to use API for creating ConfigurationData and PropertySources using abstract ConfigurationFormat implementations:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public final class ConfigurationFormats { public static List<ConfigurationFormat> getFormats(); public static List<ConfigurationFormat> getFormats(String... formatNames); @@ -336,143 +290,103 @@ using abstract ConfigurationFormat implementations:</p> ConfigurationFormat... formats); public static PropertySource createPropertySource(String resource, InputStream inputStream, Collection<ConfigurationFormat> formats); -}</code></pre> -</div> -</div> -<div class="ulist"> -<ul> -<li> -<p>getFormats() returns all registered formats.</p> -</li> -<li> -<p>getFormats(String...) allows to access all formats with a given name.</p> -</li> -<li> -<p>getFormats(URL url) allows to access all formats that declare that can optionally read an input from -a given <code>URL</code>.</p> -</li> -<li> -<p>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.</p> -</li> -<li> -<p>createPropertySource(...) allows to create a PropertySource reading a given input and the formats -to be used or known. Hereby a default property mapping is applied.</p> -</li> -</ul> -</div> -<div class="paragraph"> -<p>So creating a PropertySource from a resource is basically a one liner:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">URL url = ...; +}</code></pre> + </div> + </div> + <div class="ulist"> + <ul> + <li> <p>getFormats() returns all registered formats.</p> </li> + <li> <p>getFormats(String...) allows to access all formats with a given name.</p> </li> + <li> <p>getFormats(URL url) allows to access all formats that declare that can optionally read an input from a given <code>URL</code>.</p> </li> + <li> <p>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.</p> </li> + <li> <p>createPropertySource(...) allows to create a PropertySource reading a given input and the formats to be used or known. Hereby a default property mapping is applied.</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>So creating a PropertySource from a resource is basically a one liner:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">URL url = ...; PropertySource propertySource = ConfigurationFormats.createPropertySource(url); // constraining the formats to be used (assumption: json and yaml extensions are loaded) PropertySource propertySource = ConfigurationFormats.createPropertySource( url, - ConfigurationFormats.getFormats("json", "yaml"));</code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_customize_how_configurationdata_maps_to_propertysource">Customize how ConfigurationData maps to PropertySource</h3> -<div class="paragraph"> -<p>For for the conversion of ConfigurationData into a PropertySource different approaches can be useful:</p> -</div> -<div class="olist arabic"> -<ol class="arabic"> -<li> -<p>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.</p> -</li> -<li> -<p>If the format did also add section based properties, the combined properties returned can be used, hereby -replacing the '::' separator with a '.' separator.</p> -</li> -<li> -<p>In all other cases a custom mapping is useful, which can be acomplished by using the MappedConfigurationDataPropertySource -and overriding the Map<String,String> populateData(ConfigurationData data) method.</p> -</li> -</ol> -</div> -<div class="paragraph"> -<p>In most cases the usage of a MappedConfigurationDataPropertySource, is a good choice to start. This class -provides a convenient default mapping and also allows to customized the mapping easily:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ConfigurationData data = ...; + ConfigurationFormats.getFormats("json", "yaml"));</code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_customize_how_configurationdata_maps_to_propertysource">Customize how ConfigurationData maps to PropertySource</h3> + <div class="paragraph"> + <p>For for the conversion of ConfigurationData into a PropertySource different approaches can be useful:</p> + </div> + <div class="olist arabic"> + <ol class="arabic"> + <li> <p>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.</p> </li> + <li> <p>If the format did also add section based properties, the combined properties returned can be used, hereby replacing the '::' separator with a '.' separator.</p> </li> + <li> <p>In all other cases a custom mapping is useful, which can be acomplished by using the MappedConfigurationDataPropertySource and overriding the Map<String,String> populateData(ConfigurationData data) method.</p> </li> + </ol> + </div> + <div class="paragraph"> + <p>In most cases the usage of a MappedConfigurationDataPropertySource, is a good choice to start. This class provides a convenient default mapping and also allows to customized the mapping easily:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">ConfigurationData data = ...; MappedConfigurationDataPropertySource ps = new MappedConfigurationDataPropertySource(data){ protected Map<String, String> populateData(ConfigurationData data) { ... } - };</code></pre> -</div> -</div> -<div class="paragraph"> -<p>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 PropertySource instances must be implemented.</p> -</div> -<div class="paragraph"> -<p>For this scenario the BaseFormatPropertySourceProvider can be used, defining the following mapping -function that mus be implemented:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">/** + };</code></pre> + </div> + </div> + <div class="paragraph"> + <p>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 PropertySource instances must be implemented.</p> + </div> + <div class="paragraph"> + <p>For this scenario the BaseFormatPropertySourceProvider can be used, defining the following mapping function that mus be implemented:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">/** * Method to create a {@link org.apache.tamaya.spi.PropertySource} based on the given entries read. * * @param data the configuration data, not null. * @return the {@link org.apache.tamaya.spi.PropertySource} instance ready to be registered. */ -protected abstract Collection<PropertySource> getPropertySources(ConfigurationData data);</code></pre> -</div> -</div> -<div class="paragraph"> -<p>When using Java 8 these mappings can be asily passed as parameters to the createPropertySource -methods.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_predefined_formats">Predefined formats</h3> -<div class="paragraph"> -<p>The <em>formats</em> module ships with 3 predefined formats:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p><code>.ini</code> files, commonly known from Microsoft based systems, registered as <code>ini</code>.</p> -</li> -<li> -<p><code>.properties</code> files, as defined by <code>java.util.Properties</code>, registered as <code>properties</code>.</p> -</li> -<li> -<p><code>.xml</code> properties files, as defined by <code>java.util.Properties</code>, registered as <code>xml-properties</code>.</p> -</li> -</ul> -</div> -<div class="sect3"> -<h4 id="_ini_configuration_file_mapping">ini Configuration File Mapping</h4> -<div class="paragraph"> -<p>This module implements the ini file format with the class -org.apache.tamaya.format.formats.IniConfigurationFormat.</p> -</div> -<div class="paragraph"> -<p>The default mapping is bext illustrated by a small example, so consider the -following <code>.ini</code> file:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">a=valA +protected abstract Collection<PropertySource> getPropertySources(ConfigurationData data);</code></pre> + </div> + </div> + <div class="paragraph"> + <p>When using Java 8 these mappings can be asily passed as parameters to the createPropertySource methods.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_predefined_formats">Predefined formats</h3> + <div class="paragraph"> + <p>The <em>formats</em> module ships with 3 predefined formats:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><code>.ini</code> files, commonly known from Microsoft based systems, registered as <code>ini</code>.</p> </li> + <li> <p><code>.properties</code> files, as defined by <code>java.util.Properties</code>, registered as <code>properties</code>.</p> </li> + <li> <p><code>.xml</code> properties files, as defined by <code>java.util.Properties</code>, registered as <code>xml-properties</code>.</p> </li> + </ul> + </div> + <div class="sect3"> + <h4 id="_ini_configuration_file_mapping">ini Configuration File Mapping</h4> + <div class="paragraph"> + <p>This module implements the ini file format with the class org.apache.tamaya.format.formats.IniConfigurationFormat.</p> + </div> + <div class="paragraph"> + <p>The default mapping is bext illustrated by a small example, so consider the following <code>.ini</code> file:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">a=valA a.b=valB [section1] @@ -480,74 +394,56 @@ aa=sectionValA aa.b.c=SectionValC [section2] -a=val2Section2</code></pre> -</div> -</div> -<div class="paragraph"> -<p>This file content by default is mapped to the following Tamaya properties:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">a=valA +a=val2Section2</code></pre> + </div> + </div> + <div class="paragraph"> + <p>This file content by default is mapped to the following Tamaya properties:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">a=valA a.b=valB section1::valA=sectionValA section1::a.b.c=SectionValC -section2::a=val2Section2</code></pre> -</div> -</div> -<div class="paragraph"> -<p>Summarizing</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>entries without a section are mapped to the <em>default</em> section.</p> -</li> -<li> -<p>entries with a section are mapped to a corresponding section, hereby everything between -the brackets is used as section name (trimmed).</p> -</li> -<li> -<p>section names are separated using a double colon (<code>::</code>).</p> -</li> -</ul> -</div> -<div class="paragraph"> -<p>ConfigurationData allows to access all the different parts:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>the <em>default</em> properties (a, a.b)</p> -</li> -<li> -<p>the section section1, with properties aa, aa.b.c</p> -</li> -<li> -<p>the section section2, with properties a</p> -</li> -</ul> -</div> -</div> -<div class="sect3"> -<h4 id="_xml_property_and_ordinary_property_files">XML Property and ordinary Property Files</h4> -<div class="paragraph"> -<p>This module also ships with ConfigurationFormat implementations that reuse the parsing -functionality provided with java.util.Properties:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p><code>org.apache.tamaya.format.formats.PropertiesFormat</code> uses <code>Properties.read(InputStream)</code>.</p> -</li> -<li> -<p><code>org.apache.tamaya.format.formats.PropertiesXmlFormat</code> uses <code>Properties.readFromXml(InputStream)</code>.</p> -</li> -</ul> -</div> -</div> -</div> -</div> +section2::a=val2Section2</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Summarizing</p> + </div> + <div class="ulist"> + <ul> + <li> <p>entries without a section are mapped to the <em>default</em> section.</p> </li> + <li> <p>entries with a section are mapped to a corresponding section, hereby everything between the brackets is used as section name (trimmed).</p> </li> + <li> <p>section names are separated using a double colon (<code>::</code>).</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>ConfigurationData allows to access all the different parts:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>the <em>default</em> properties (a, a.b)</p> </li> + <li> <p>the section section1, with properties aa, aa.b.c</p> </li> + <li> <p>the section section2, with properties a</p> </li> + </ul> + </div> + </div> + <div class="sect3"> + <h4 id="_xml_property_and_ordinary_property_files">XML Property and ordinary Property Files</h4> + <div class="paragraph"> + <p>This module also ships with ConfigurationFormat implementations that reuse the parsing functionality provided with java.util.Properties:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><code>org.apache.tamaya.format.formats.PropertiesFormat</code> uses <code>Properties.read(InputStream)</code>.</p> </li> + <li> <p><code>org.apache.tamaya.format.formats.PropertiesXmlFormat</code> uses <code>Properties.readFromXml(InputStream)</code>.</p> </li> + </ul> + </div> + </div> + </div> + </div> </div></p> <hr /> @@ -559,8 +455,8 @@ functionality provided with java.util.Properties:</p> <div id="footer"> <div class="container"> <p class="muted credit">© 2014-<span>2018</span> Apache Software Foundation | Mixed with <a href="http://getbootstrap.com/";>Bootstrap v3.1.1</a> - | Baked with <a href="http://jbake.org";>JBake <span>v2.5.1</span></a> - at <span>2018-05-03</span> | + | Baked with <a href="http://jbake.org";>JBake <span>v2.6.1</span></a> + at <span>2018-05-17</span> | <a class="twitter-follow-button" data-show-count="false" href="https://twitter.com/tamayaconf";>Follow @tamayaconf</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> </p> <p>
