http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/cddd52a8/documentation/extensions/mod_optional.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_optional.html b/documentation/extensions/mod_optional.html index 8c93eeb..7d8271b 100644 --- a/documentation/extensions/mod_optional.html +++ b/documentation/extensions/mod_optional.html @@ -125,74 +125,64 @@ <h1>Apache Tamaya - Extension: Optional Tamaya Configuration</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="Optional">Tamaya Optional (Extension Module)</h2> -<div class="sectionbody"> -<div class="paragraph"> -<p>Tamaya <em>Optional</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>Optional</em> is for projects that want to benefit from Tamaya configuration optionally only. -E.g. doing an OSS project you can declare to support configuration with Tamaya as -an optional extension. This module can be added as a hard dependency to your code, hereby adding only -three artifacts. The <em>optional</em> module automatically checks the availability of Tamaya on the -classpath and only if available it tries to access it for configuration evaluation. -Additionally an EvaluationPolicy lets you define the precedence of configured values -(yours, or Tamaya ones, if present).</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>optional</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="Optional">Tamaya Optional (Extension Module)</h2> + <div class="sectionbody"> + <div class="paragraph"> + <p>Tamaya <em>Optional</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>Optional</em> is for projects that want to benefit from Tamaya configuration optionally only. E.g. doing an OSS project you can declare to support configuration with Tamaya as an optional extension. This module can be added as a hard dependency to your code, hereby adding only three artifacts. The <em>optional</em> module automatically checks the availability of Tamaya on the classpath and only if available it tries to access it for configuration evaluation. Additionally an EvaluationPolicy lets you define the precedence of configured values (yours, or Tamaya ones, if present).</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>optional</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-optional</artifactId> <version>{tamaya_version}</version> -</dependency></code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_reading_configuration_using_the_tamaya_optional_module">Reading configuration using the Tamaya Optional Module</h3> -<div class="paragraph"> -<p>Tamaya <em>Optional</em> allows reading configuration with a small subset of functionality only. For more - advanced use cases consider using the Apache Tamaya as your main configuration API. When - creating your OptionalConfiguration instance you also pass the logic to access a value - with your own configuration logic. Tamaya Optional will delegate to your logic as needed - (depending on the <code>EvaluationPolicy</code>).</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">BigDecimal interestRate = +</dependency></code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_reading_configuration_using_the_tamaya_optional_module">Reading configuration using the Tamaya Optional Module</h3> + <div class="paragraph"> + <p>Tamaya <em>Optional</em> allows reading configuration with a small subset of functionality only. For more advanced use cases consider using the Apache Tamaya as your main configuration API. When creating your OptionalConfiguration instance you also pass the logic to access a value with your own configuration logic. Tamaya Optional will delegate to your logic as needed (depending on the <code>EvaluationPolicy</code>).</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">BigDecimal interestRate = OptionalConfiguration.of( EvaluationPolicy.TAMAYA_OVERRIDES_OTHER, (k) -> MyConfigMechanism.get(k) // String get(String key); ) .get("com.mycomp.ratecalculator.rate", BigDecimal.class)) - .orElse(BigDecimal.of(0.05d));</code></pre> -</div> -</div> -</div> -</div> + .orElse(BigDecimal.of(0.05d));</code></pre> + </div> + </div> + </div> + </div> </div></p> <hr /> @@ -204,8 +194,8 @@ Additionally an EvaluationPolicy lets you define the precedence of configured va <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_osgi.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_osgi.html b/documentation/extensions/mod_osgi.html index 072a520..f7c3832 100644 --- a/documentation/extensions/mod_osgi.html +++ b/documentation/extensions/mod_osgi.html @@ -125,59 +125,46 @@ <h1>Apache Tamaya - Extensions: OSGI Integration</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="OSGI">Tamaya OSGI Support</h2> -<div class="sectionbody"> -<div class="paragraph"> -<p>Tamaya <em>OSGI</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>OSGI</em> provides support for integration with OSGI. Hereby Tamaya does actively override or extend the OSGI -ConfigAdmin based configuration with entries stored and managed by Tamaya. Tamaya provides also shell extensions -to enable/perform configuration loading and restoring actions. -Optionally Tamaya also provides extension for automatically trigger configuration updates, when configuration has -been changed and configuration injection using Tamaya’s injection API.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_compatibility">Compatibility</h3> -<div class="paragraph"> -<p>All module described are based on Java 8, so it will run on Java 8 and beyond. -The modules are built against <strong>OSGI Compendium version 5.0</strong>. Tamaya OSGI support -is tested against the following OSGI runtimes:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>Apache Karaf, version 4.0.7</p> -</li> -<li> -<p>Apache Felix, version 5.6.1</p> -</li> -<li> -<p>Eclipse Equinox, version x.x.x.</p> -</li> -</ul> -</div> -</div> -<div class="sect2"> -<h3 id="_installation">Installation</h3> -<div class="paragraph"> -<p>To benefit from Tamaya in an OSGI context you must deploy at least the following modules to -your OSGI runtime environment:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing"># Runtime with OSGI ConfigAdmin support, e.g. + <p><div id="preamble"> + <div class="sectionbody"> + <!-- toc disabled --> + </div> +</div> +<div class="sect1"> + <h2 id="OSGI">Tamaya OSGI Support</h2> + <div class="sectionbody"> + <div class="paragraph"> + <p>Tamaya <em>OSGI</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>OSGI</em> provides support for integration with OSGI. Hereby Tamaya does actively override or extend the OSGI ConfigAdmin based configuration with entries stored and managed by Tamaya. Tamaya provides also shell extensions to enable/perform configuration loading and restoring actions. Optionally Tamaya also provides extension for automatically trigger configuration updates, when configuration has been changed and configuration injection using Tamayaâs injection API.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_compatibility">Compatibility</h3> + <div class="paragraph"> + <p>All module described are based on Java 8, so it will run on Java 8 and beyond. The modules are built against <strong>OSGI Compendium version 5.0</strong>. Tamaya OSGI support is tested against the following OSGI runtimes:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>Apache Karaf, version 4.0.7</p> </li> + <li> <p>Apache Felix, version 5.6.1</p> </li> + <li> <p>Eclipse Equinox, version x.x.x.</p> </li> + </ul> + </div> + </div> + <div class="sect2"> + <h3 id="_installation">Installation</h3> + <div class="paragraph"> + <p>To benefit from Tamaya in an OSGI context you must deploy at least the following modules to your OSGI runtime environment:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-listing" data-lang="listing"># Runtime with OSGI ConfigAdmin support, e.g. org.apache.felix:org.apache.felix.configadmin:{felix_version} # API and core org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0 @@ -186,300 +173,226 @@ org.apache.tamaya:tamaya-spisupport:{tamaya_version} org.apache.tamaya:tamaya-core:{tamaya_version} # Required extensions org.apache.tamaya.ext:tamaya-functions:{tamaya_version} -org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}</code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_tamaya_service_loading_in_osgi">Tamaya Service Loading in OSGI</h3> -<div class="paragraph"> -<p>Important to know is that within OSGI class- and resource loading is not compatible with standard Java SE. Also -in OSGI, bundles can be loaded or unloaded at any time, so Tamaya’s logic must cope with this as well. -These constraints are handled by Tamaya (implemented in tamaya-core and tamaya-osgi) as follows:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>Tamaya registers a OSGIServiceContext which reads all java.util.ServiceLoader configurations and -registers them as OSGI services. Hereby integration is two-way: The core module contains an -OSGI Activator that replaces Tamaya’s default ServiceContext with an OSGI based implementation that -will consume all services from the OSGI service API. Consequently you can also register Tamaya extensions -as OSGI services using standard OSGI tooling (e.g. your own PropertySource instances). Tamaya hereby -also does not store any service references, so the dynamic nature of OSGI is fully honored.</p> -</li> -<li> -<p>Tamaya’s ServiceContext SPI does additionally provide functionality for loading of (classpath) -resources using the bundle’s getEntry(String) method.</p> -</li> -<li> -<p>Tamaya similarly checks the classpath of all bundles for Tamaya SPI services to be registered thus -implementing the ServiceLoader logic in OSGI. Hereby Tamaya will only register services with the -org.apache.tamaya as root package.</p> -</li> -</ul> -</div> -<div class="admonitionblock note"> -<table> -<tr> -<td class="icon"> -<div class="title">Note</div> -</td> -<td class="content"> -Tamaya actually does not replace any existing ConfigAdmin component, Tamaya modifies any existing OSGI - configuration on changes detected and stores backups of any OSGI configuration before applying any - changes. -</td> -</tr> -</table> -</div> -</div> -<div class="sect2"> -<h3 id="_configuring_bundles">Configuring Bundles</h3> -<div class="sect3"> -<h4 id="_mapping_of_pids_and_factorypids">Mapping of pids and factoryPids</h4> -<div class="paragraph"> -<p>When accessing configuration from the OSGI ConfigAdmin a pid and an optional location can be provided. -Tamaya requires all configuration for a PID to be located in keys starting [PID]:</p> -</div> -<div class="listingblock"> -<div class="title">OSGI pid mapping</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing"># OSGI settings +org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}</code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_tamaya_service_loading_in_osgi">Tamaya Service Loading in OSGI</h3> + <div class="paragraph"> + <p>Important to know is that within OSGI class- and resource loading is not compatible with standard Java SE. Also in OSGI, bundles can be loaded or unloaded at any time, so Tamayaâs logic must cope with this as well. These constraints are handled by Tamaya (implemented in tamaya-core and tamaya-osgi) as follows:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>Tamaya registers a OSGIServiceContext which reads all java.util.ServiceLoader configurations and registers them as OSGI services. Hereby integration is two-way: The core module contains an OSGI Activator that replaces Tamayaâs default ServiceContext with an OSGI based implementation that will consume all services from the OSGI service API. Consequently you can also register Tamaya extensions as OSGI services using standard OSGI tooling (e.g. your own PropertySource instances). Tamaya hereby also does not store any service references, so the dynamic nature of OSGI is fully honored.</p> </li> + <li> <p>Tamayaâs ServiceContext SPI does additionally provide functionality for loading of (classpath) resources using the bundleâs getEntry(String) method.</p> </li> + <li> <p>Tamaya similarly checks the classpath of all bundles for Tamaya SPI services to be registered thus implementing the ServiceLoader logic in OSGI. Hereby Tamaya will only register services with the org.apache.tamaya as root package.</p> </li> + </ul> + </div> + <div class="admonitionblock note"> + <table> + <tbody> + <tr> + <td class="icon"> + <div class="title"> + Note + </div> </td> + <td class="content"> Tamaya actually does not replace any existing ConfigAdmin component, Tamaya modifies any existing OSGI configuration on changes detected and stores backups of any OSGI configuration before applying any changes. </td> + </tr> + </tbody> + </table> + </div> + </div> + <div class="sect2"> + <h3 id="_configuring_bundles">Configuring Bundles</h3> + <div class="sect3"> + <h4 id="_mapping_of_pids_and_factorypids">Mapping of pids and factoryPids</h4> + <div class="paragraph"> + <p>When accessing configuration from the OSGI ConfigAdmin a pid and an optional location can be provided. Tamaya requires all configuration for a PID to be located in keys starting [PID]:</p> + </div> + <div class="listingblock"> + <div class="title"> + OSGI pid mapping + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-listing" data-lang="listing"># OSGI settings pid=myBundle key=common.net.port # Corresponding key in Tamaya configuration -[myBundle]key=common.net.port</code></pre> -</div> -</div> -</div> -<div class="sect3"> -<h4 id="_enabling_disabling_tamaya">Enabling/Disabling Tamaya</h4> -<div class="paragraph"> -<p>By default, Tamaya doesn’t do anything, unless it is told to so so. So having installed the Tamaya OSGI plugin, -you will see the bundles are loaded, but your OSGI environment still works the same. This is not accidentally, since -configuration is a crucial part. This means Tamaya, by default, is disabled for all bundles. You have now several -options to enabled Tamaya:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>you can enable Tamaya for <strong>all</strong> bundles by default by</p> -<div class="ulist"> -<ul> -<li> -<p>setting the -Dtamaya-enabled=true system property.</p> -</li> -<li> -<p>by setting tamaya-enabled=true in the OSGI Configuration for the PID TamayaConfigPlugin.</p> -</li> -</ul> -</div> -</li> -<li> -<p>you can enable Tamaya for a single bundle by</p> -<div class="ulist"> -<ul> -<li> -<p>by setting tamaya-enabled=true in the OSGI Configuration for the given bundle.</p> -</li> -<li> -<p>by adding Tamaya-Enabled: true to the bundle’s MANIFEST.</p> -</li> -</ul> -</div> -</li> -</ul> -</div> -<div class="paragraph"> -<p>Similarly you can also combine these options the other way round:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>You can enable Tamaya by default as shown above.</p> -</li> -<li> -<p>You can disable Tamaya for bundles by</p> -<div class="ulist"> -<ul> -<li> -<p>by setting tamaya-enabled=false in the OSGI Configuration for the given bundle.</p> -</li> -<li> -<p>by adding Tamaya-Enabled: false to the bundle’s MANIFEST.</p> -</li> -</ul> -</div> -</li> -</ul> -</div> -</div> -<div class="sect3"> -<h4 id="_controlling_how_tamaya_changes_your_osgi_configuration">Controlling How Tamaya changes your OSGI Configuration</h4> -<div class="paragraph"> -<p>Tamaya supports different policies that define how Tamaya is changing the OSGI configuration:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p><strong>EXTEND</strong>: Only add properties not existing in the OSGI configuration, but never override -or remove existing properties.</p> -</li> -<li> -<p><strong>OVERRIDE</strong>: Override existing properties and also add new properties.</p> -</li> -<li> -<p><strong>UPDATE_ONLY</strong>: Only override existing properties but do not add any properties.</p> -</li> -</ul> -</div> -<div class="paragraph"> -<p>By default, Tamaya uses the <em>OVERRIDE</em> policy. Also this policy can be configured in several -ways and with different scopes:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>You can define the <em>default</em> policy applied, by</p> -<div class="ulist"> -<ul> -<li> -<p>setting the -Dtamaya-policy=POLICY system property.</p> -</li> -<li> -<p>by setting tamaya-policy=POLICY in the OSGI Configuration for the PID TamayaConfigPlugin.</p> -</li> -</ul> -</div> -</li> -</ul> -</div> -<div class="paragraph"> -<p>Hereby, <em>POLICY</em> must be one of OVERRIDE, EXTEND, UPDATE_ONLY.</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>You can also configure the policy individually for a bundle by</p> -<div class="ulist"> -<ul> -<li> -<p>by setting tamaya-policy=POLICY in the OSGI Configuration for the given bundle.</p> -</li> -<li> -<p>by adding Tamaya-Policy: POLICY to the bundle’s MANIFEST.</p> -</li> -</ul> -</div> -</li> -</ul> -</div> -</div> -<div class="sect3"> -<h4 id="_mapping_osgi_pids_to_tamaya_configuration">Mapping OSGI PIDs to Tamaya Configuration</h4> -<div class="paragraph"> -<p>Tamaya configuration is a single Map<String,String> with String keys and String values. Whereas OSGI configuration are -multiple +Dictionary<String,?> (for several PIDs). The Tamaya OSGI extension implements the following mapping:</p> -</div> -<div class="paragraph"> -<p>As an example refer to the followinf Tamaya configuration entries:</p> -</div> -<div class="listingblock"> -<div class="title">Tamaya configuration for PID 'MyPlugin'</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">[MyPlugin]ch.base.pack.Main.customer=Native Inc +[myBundle]key=common.net.port</code></pre> + </div> + </div> + </div> + <div class="sect3"> + <h4 id="_enabling_disabling_tamaya">Enabling/Disabling Tamaya</h4> + <div class="paragraph"> + <p>By default, Tamaya doesnât do anything, unless it is told to so so. So having installed the Tamaya OSGI plugin, you will see the bundles are loaded, but your OSGI environment still works the same. This is not accidentally, since configuration is a crucial part. This means Tamaya, by default, is disabled for all bundles. You have now several options to enabled Tamaya:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>you can enable Tamaya for <strong>all</strong> bundles by default by</p> + <div class="ulist"> + <ul> + <li> <p>setting the -Dtamaya-enabled=true system property.</p> </li> + <li> <p>by setting tamaya-enabled=true in the OSGI Configuration for the PID TamayaConfigPlugin.</p> </li> + </ul> + </div> </li> + <li> <p>you can enable Tamaya for a single bundle by</p> + <div class="ulist"> + <ul> + <li> <p>by setting tamaya-enabled=true in the OSGI Configuration for the given bundle.</p> </li> + <li> <p>by adding Tamaya-Enabled: true to the bundleâs MANIFEST.</p> </li> + </ul> + </div> </li> + </ul> + </div> + <div class="paragraph"> + <p>Similarly you can also combine these options the other way round:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>You can enable Tamaya by default as shown above.</p> </li> + <li> <p>You can disable Tamaya for bundles by</p> + <div class="ulist"> + <ul> + <li> <p>by setting tamaya-enabled=false in the OSGI Configuration for the given bundle.</p> </li> + <li> <p>by adding Tamaya-Enabled: false to the bundleâs MANIFEST.</p> </li> + </ul> + </div> </li> + </ul> + </div> + </div> + <div class="sect3"> + <h4 id="_controlling_how_tamaya_changes_your_osgi_configuration">Controlling How Tamaya changes your OSGI Configuration</h4> + <div class="paragraph"> + <p>Tamaya supports different policies that define how Tamaya is changing the OSGI configuration:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><strong>EXTEND</strong>: Only add properties not existing in the OSGI configuration, but never override or remove existing properties.</p> </li> + <li> <p><strong>OVERRIDE</strong>: Override existing properties and also add new properties.</p> </li> + <li> <p><strong>UPDATE_ONLY</strong>: Only override existing properties but do not add any properties.</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>By default, Tamaya uses the <em>OVERRIDE</em> policy. Also this policy can be configured in several ways and with different scopes:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>You can define the <em>default</em> policy applied, by</p> + <div class="ulist"> + <ul> + <li> <p>setting the -Dtamaya-policy=POLICY system property.</p> </li> + <li> <p>by setting tamaya-policy=POLICY in the OSGI Configuration for the PID TamayaConfigPlugin.</p> </li> + </ul> + </div> </li> + </ul> + </div> + <div class="paragraph"> + <p>Hereby, <em>POLICY</em> must be one of OVERRIDE, EXTEND, UPDATE_ONLY.</p> + </div> + <div class="ulist"> + <ul> + <li> <p>You can also configure the policy individually for a bundle by</p> + <div class="ulist"> + <ul> + <li> <p>by setting tamaya-policy=POLICY in the OSGI Configuration for the given bundle.</p> </li> + <li> <p>by adding Tamaya-Policy: POLICY to the bundleâs MANIFEST.</p> </li> + </ul> + </div> </li> + </ul> + </div> + </div> + <div class="sect3"> + <h4 id="_mapping_osgi_pids_to_tamaya_configuration">Mapping OSGI PIDs to Tamaya Configuration</h4> + <div class="paragraph"> + <p>Tamaya configuration is a single Map<String,String> with String keys and String values. Whereas OSGI configuration are multiple +Dictionary<String,?> (for several PIDs). The Tamaya OSGI extension implements the following mapping:</p> + </div> + <div class="paragraph"> + <p>As an example refer to the followinf Tamaya configuration entries:</p> + </div> + <div class="listingblock"> + <div class="title"> + Tamaya configuration for PID 'MyPlugin' + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">[MyPlugin]ch.base.pack.Main.customer=Native Inc [MyPlugin]ch.base.pack.Main.use=234 -[MyPlugin]ch.base.pack.Main.encoding=UTF-8</code></pre> -</div> -</div> -<div class="paragraph"> -<p>The OSGI Configuration Plugin now provides the following configuration for PID:</p> -</div> -<div class="listingblock"> -<div class="title">OSGI configuration for PID 'MyPlugin'</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">ch.base.pack.Main.use=100 (Integer) +[MyPlugin]ch.base.pack.Main.encoding=UTF-8</code></pre> + </div> + </div> + <div class="paragraph"> + <p>The OSGI Configuration Plugin now provides the following configuration for PID:</p> + </div> + <div class="listingblock"> + <div class="title"> + OSGI configuration for PID 'MyPlugin' + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">ch.base.pack.Main.use=100 (Integer) ch.base.pack.Main.switch=on (Boolean) -ch.base.pack.Main.customer=NONE (String)</code></pre> -</div> -</div> -<div class="paragraph"> -<p>Now using Policy.OVERRIDE (as desribed in the previous section), Tamaya will change the OSGI configuration -as follows:</p> -</div> -<div class="listingblock"> -<div class="title">OSGI configuration after Tamaya update for PID 'MyPlugin'</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">ch.base.pack.Main.use=234 (Integer) +ch.base.pack.Main.customer=NONE (String)</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Now using Policy.OVERRIDE (as desribed in the previous section), Tamaya will change the OSGI configuration as follows:</p> + </div> + <div class="listingblock"> + <div class="title"> + OSGI configuration after Tamaya update for PID 'MyPlugin' + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">ch.base.pack.Main.use=234 (Integer) ch.base.pack.Main.switch=on (Boolean) ch.base.pack.Main.customer=Native Inc (String) -[MyPlugin]ch.base.pack.Main.encoding=UTF-8 (String)</code></pre> -</div> -</div> -<div class="paragraph"> -<p>So Tamaya configuration mapping can be summarized as follows:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>The OSGI PID is mapped to a Tamaya prefix [PID].</p> -</li> -<li> -<p>The OSGI keys are the exact same keys as from Tamaya with the <em>[PID]</em> prefix removed.</p> -</li> -<li> -<p>New entries are added (depending on the Policy) as String values.</p> -</li> -<li> -<p>Types of existing entries are preserved on update (this requires the Tamaya entries to be convertable into -the required target types. Refer to Tamaya’s core documentation for supported types and how -to add custom converters).</p> -</li> -</ul> -</div> -<div class="paragraph"> -<p>Finally, the mapping of the OSGI <em>PID</em> to the Tamaya <em>[PID]</em> prefix also can be customized by</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>adding tamaya-config-root as an OSGI configuration property to the OSGI configuration.</p> -</li> -<li> -<p>adding Tamaya-Config-Root as a MANIFEST entry to the bundle.</p> -</li> -</ul> -</div> -<div class="paragraph"> -<p>The root will replace the default <em>[PID]</em> prefix with the value configured.</p> -</div> -</div> -<div class="sect3"> -<h4 id="_osgi_configuration_backup">OSGI Configuration Backup</h4> -<div class="paragraph"> -<p>Before Tamaya changes any OSGI configuration it creates a <em>Backup</em> of the existing OSGI -configuration dictionary and stores it in serialized form in the plugin’s OSGI configuration. -This allows you to restore the original OSGI configuration in case of problems. Hereby Tamaya -automatically sets the tamaya-enabled=false property to disable Tamaya for the given -configuration (bundle).</p> -</div> -<div class="paragraph"> -<p>The history can be accessed from the Tamaya Configuration Plugin Service -(shown later).</p> -</div> -</div> -<div class="sect3"> -<h4 id="_osgi_configuration_change_log">OSGI Configuration Change Log</h4> -<div class="paragraph"> -<p>All changes applied by Tamaya are logged as well using -ConfigHistory entry items. The history can be accessed from the Tamaya Configuration Plugin Service -(shown later):</p> -</div> -<div class="listingblock"> -<div class="title">OSGI ConfigHistory Entry</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-Java" data-lang="Java">public final class ConfigHistory implements Serializable{ +[MyPlugin]ch.base.pack.Main.encoding=UTF-8 (String)</code></pre> + </div> + </div> + <div class="paragraph"> + <p>So Tamaya configuration mapping can be summarized as follows:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>The OSGI PID is mapped to a Tamaya prefix [PID].</p> </li> + <li> <p>The OSGI keys are the exact same keys as from Tamaya with the <em>[PID]</em> prefix removed.</p> </li> + <li> <p>New entries are added (depending on the Policy) as String values.</p> </li> + <li> <p>Types of existing entries are preserved on update (this requires the Tamaya entries to be convertable into the required target types. Refer to Tamayaâs core documentation for supported types and how to add custom converters).</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>Finally, the mapping of the OSGI <em>PID</em> to the Tamaya <em>[PID]</em> prefix also can be customized by</p> + </div> + <div class="ulist"> + <ul> + <li> <p>adding tamaya-config-root as an OSGI configuration property to the OSGI configuration.</p> </li> + <li> <p>adding Tamaya-Config-Root as a MANIFEST entry to the bundle.</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>The root will replace the default <em>[PID]</em> prefix with the value configured.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_osgi_configuration_backup">OSGI Configuration Backup</h4> + <div class="paragraph"> + <p>Before Tamaya changes any OSGI configuration it creates a <em>Backup</em> of the existing OSGI configuration dictionary and stores it in serialized form in the pluginâs OSGI configuration. This allows you to restore the original OSGI configuration in case of problems. Hereby Tamaya automatically sets the tamaya-enabled=false property to disable Tamaya for the given configuration (bundle).</p> + </div> + <div class="paragraph"> + <p>The history can be accessed from the Tamaya Configuration Plugin Service (shown later).</p> + </div> + </div> + <div class="sect3"> + <h4 id="_osgi_configuration_change_log">OSGI Configuration Change Log</h4> + <div class="paragraph"> + <p>All changes applied by Tamaya are logged as well using ConfigHistory entry items. The history can be accessed from the Tamaya Configuration Plugin Service (shown later):</p> + </div> + <div class="listingblock"> + <div class="title"> + OSGI ConfigHistory Entry + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-Java" data-lang="Java">public final class ConfigHistory implements Serializable{ [...] @@ -509,20 +422,21 @@ ConfigHistory entry items. The history can be accessed from the Tamaya Configura public ConfigHistory setKey(String key) {...} -}</code></pre> -</div> -</div> -</div> -<div class="sect3"> -<h4 id="_the_tamaya_osgi_configuration_service">The Tamaya OSGI Configuration Service</h4> -<div class="paragraph"> -<p>As mentioned Tamaya exposes it’s OSGI functionality, allowing programmatic access to Tamaya configuration -logic with the TamayaConfigService OSGI service:</p> -</div> -<div class="listingblock"> -<div class="title">The exposed TamayaConfigService</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-Java" data-lang="Java">public interface TamayaConfigService{ +}</code></pre> + </div> + </div> + </div> + <div class="sect3"> + <h4 id="_the_tamaya_osgi_configuration_service">The Tamaya OSGI Configuration Service</h4> + <div class="paragraph"> + <p>As mentioned Tamaya exposes itâs OSGI functionality, allowing programmatic access to Tamaya configuration logic with the TamayaConfigService OSGI service:</p> + </div> + <div class="listingblock"> + <div class="title"> + The exposed TamayaConfigService + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-Java" data-lang="Java">public interface TamayaConfigService{ /** The system/config property to set Tamaya's {@link Policy}. */ String TAMAYA_POLICY_PROP = "tamaya-policy"; /** The MANIFEST property to set Tamaya's {@link Policy}. */ @@ -696,19 +610,18 @@ logic with the TamayaConfigService OSGI service:</p> * @return true, if a backup exists. */ boolean containsBackup(String pid); -}</code></pre> -</div> -</div> -</div> -<div class="sect3"> -<h4 id="_the_tamaya_osgi_configuration_service_2">The Tamaya OSGI Configuration Service</h4> -<div class="paragraph"> -<p>Finally Tamaya also provides support for using Tamaya’s injection API with your OSGI project. To enable injection -you must install a few additional bundles:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> +}</code></pre> + </div> + </div> + </div> + <div class="sect3"> + <h4 id="_the_tamaya_osgi_configuration_service_2">The Tamaya OSGI Configuration Service</h4> + <div class="paragraph"> + <p>Finally Tamaya also provides support for using Tamayaâs injection API with your OSGI project. To enable injection you must install a few additional bundles:</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-osgi-injection</artifactId> <version>${tamaya.version}</version> @@ -722,35 +635,27 @@ you must install a few additional bundles:</p> <groupId>org.apache.tamaya.ext</groupId> <artifactId>injection-api</artifactId> <version>${tamaya.version}</version> -</dependency></code></pre> -</div> -</div> -<div class="paragraph"> -<p>Given that you can inject configuration entries</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>on your services by</p> -<div class="ulist"> -<ul> -<li> -<p>setting tamaya-config-inject=true in your service properties.</p> -</li> -<li> -<p>setting Tamaya-Config-Inject: true in your bundle’s manifest.</p> -</li> -</ul> -</div> -</li> -<li> -<p>or by using the registered ConfigInjectionService:</p> -</li> -</ul> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ConfigInjectionService { +</dependency></code></pre> + </div> + </div> + <div class="paragraph"> + <p>Given that you can inject configuration entries</p> + </div> + <div class="ulist"> + <ul> + <li> <p>on your services by</p> + <div class="ulist"> + <ul> + <li> <p>setting tamaya-config-inject=true in your service properties.</p> </li> + <li> <p>setting Tamaya-Config-Inject: true in your bundleâs manifest.</p> </li> + </ul> + </div> </li> + <li> <p>or by using the registered ConfigInjectionService:</p> </li> + </ul> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ConfigInjectionService { /** The manifest entry to enable Tamaya injection. */ String TAMAYA_INJECTION_ENABLED_MANIFEST = "Tamaya-Config-Inject"; /** The OSGI config entry to enable Tamaya injection. */ @@ -830,54 +735,52 @@ you must install a few additional bundles:</p> * @return the configured template. */ <T> T createTemplate(Bundle bundle, Class<T> templateType); -}</code></pre> -</div> -</div> -<div class="admonitionblock note"> -<table> -<tr> -<td class="icon"> -<div class="title">Note</div> -</td> -<td class="content"> -Injection hereby is based on the OSGI ConfigAdmin values only. To use Tamaya configuration you have to additionally -install the Tamaya common OSGI support as described in the previous sections. -</td> -</tr> -</table> -</div> -<div class="paragraph"> -<p>More details on Tamaya’s injection API can be found in the corresponding <a href="mod_injection.html">API documentation</a>.</p> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_special_osgi_platform_support">Special OSGI Platform support</h3> -<div class="sect3"> -<h4 id="_apache_karaf_shell">Apache Karaf Shell</h4> -<div class="paragraph"> -<p>Apache Tamaya provides a Karaf Shell Extension providing commands for performing several actions related -to Tamaya configuration. To use them, simply add the org.apache.tamaya.ext:tamaya-osgi-karaf-shell bundle -to your OSGI runtime. The extension will add the following commands to your Karaf conaole (with prefix tamaya):</p> -</div> -<table class="tableblock frame-1 grid-all spread"> -<colgroup> -<col style="width: 33.3333%;"> -<col style="width: 33.3333%;"> -<col style="width: 33.3334%;"> -</colgroup> -<thead> -<tr> -<th class="tableblock halign-left valign-top"><em>Artifact</em></th> -<th class="tableblock halign-left valign-top"><em>Description</em></th> -<th class="tableblock halign-left valign-top"><em>Options</em></th> -</tr> -</thead> -<tbody> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_apply_config</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Show the current Tamaya configuration.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +}</code></pre> + </div> + </div> + <div class="admonitionblock note"> + <table> + <tbody> + <tr> + <td class="icon"> + <div class="title"> + Note + </div> </td> + <td class="content"> Injection hereby is based on the OSGI ConfigAdmin values only. To use Tamaya configuration you have to additionally install the Tamaya common OSGI support as described in the previous sections. </td> + </tr> + </tbody> + </table> + </div> + <div class="paragraph"> + <p>More details on Tamayaâs injection API can be found in the corresponding <a href="mod_injection.html">API documentation</a>.</p> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_special_osgi_platform_support">Special OSGI Platform support</h3> + <div class="sect3"> + <h4 id="_apache_karaf_shell">Apache Karaf Shell</h4> + <div class="paragraph"> + <p>Apache Tamaya provides a Karaf Shell Extension providing commands for performing several actions related to Tamaya configuration. To use them, simply add the org.apache.tamaya.ext:tamaya-osgi-karaf-shell bundle to your OSGI runtime. The extension will add the following commands to your Karaf conaole (with prefix tamaya):</p> + </div> + <table class="tableblock frame-1 grid-all spread"> + <colgroup> + <col style="width: 33.3333%;"> + <col style="width: 33.3333%;"> + <col style="width: 33.3334%;"> + </colgroup> + <thead> + <tr> + <th class="tableblock halign-left valign-top"><em>Artifact</em></th> + <th class="tableblock halign-left valign-top"><em>Description</em></th> + <th class="tableblock halign-left valign-top"><em>Options</em></th> + </tr> + </thead> + <tbody> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_apply_config</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Show the current Tamaya configuration.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_apply_config [options] pid <b>ARGUMENTS</b> @@ -885,230 +788,228 @@ tamaya:tm_apply_config [options] pid <b>OPTIONS</b> <i>operationMode, -m, --opmode</i> Explicitly set (override) the operation mode to use. <i>dryRun, -d, --dryrun</i> If set to true no OSGI configuration gets changed. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_backup_create</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Creates a backup of a current OSGI configuration.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_backup_create</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Creates a backup of a current OSGI configuration.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_backup_create [options] pid <b>ARGUMENTS</b> <i>pid</i> The target pid to backup. <b>OPTIONS</b> <i>--force, -f</i> Forces to (over)write a backup, even if one already exists. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_backup_delete</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Deletes the OSGI configuration backup of Tamya.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_backup_delete</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Deletes the OSGI configuration backup of Tamya.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_backup_delete pid <b>ARGUMENTS</b> <i>pid</i> Allows to filter on the given PID. '*' removes all backups. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_backup_list</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">List the backed-up OSGI configuration before Tamya applied changes.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_backup_list</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">List the backed-up OSGI configuration before Tamya applied changes.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_backup_list [pid] <b>ARGUMENTS</b> <i>pid</i> Allows to filter on the given PID. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_backup_restore</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Restores the OSGI configuration backup of Tamya and disabled the PID for Tamaya configuration.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_backup_restore</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Restores the OSGI configuration backup of Tamya and disabled the PID for Tamaya configuration.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_backup_restore pid <b>ARGUMENTS</b> <i>pid</i> The target PID. '*' restores all backups. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_config</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Show the current Tamaya configuration.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_config</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Show the current Tamaya configuration.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_config [options] <b>OPTIONS</b> <i>pi, -p, --pid</i> Apply filtering for the given OSGI component PID. <i>section, -s, --section</i> A starting expression selecting the section to be filtered. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_enable</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Enables or disable Tamaya by default for all bundles/services (default: enabled=false). Disabling still allows to explicitly enable - bundles using 'tamaya-enable' manifest or OSGI config entries.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_enable</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Enables or disable Tamaya by default for all bundles/services (default: enabled=false). Disabling still allows to explicitly enable bundles using 'tamaya-enable' manifest or OSGI config entries.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_enable enabled <b>ARGUMENTS</b> <i>enabled</i> The boolean value to enabled/disable Tamaya by default. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_enabled</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Check if Tamaya is currently by default enabled for all bundles/services (default: enabled=false). If disabled still Tamaya allows to - explicitly enable bundles using 'tamaya-enable' manifest or OSGI config entries.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_enabled</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Check if Tamaya is currently by default enabled for all bundles/services (default: enabled=false). If disabled still Tamaya allows to explicitly enable bundles using 'tamaya-enable' manifest or OSGI config entries.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_enabled -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_history</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the getHistory of changes Tamaya applied to the OSGI configuration.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_history</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Gets the getHistory of changes Tamaya applied to the OSGI configuration.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_history [options] [pid] <b>ARGUMENTS</b> <i>pid</i> Allows to filter on the given PID. <i>--type, -t</i> Allows to filter the events types shown. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_history_delete</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Deletes the getHistory of changes Tamaya applied to the OSGI configuration.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_history_delete</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Deletes the getHistory of changes Tamaya applied to the OSGI configuration.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_history_delete pid <b>ARGUMENTS</b> <i>pid</i> Allows to filter on the given PID. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_history_delete_all</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Deletes the full getHistory of changes Tamaya applied to the OSGI configuration.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_history_delete_all</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Deletes the full getHistory of changes Tamaya applied to the OSGI configuration.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_history_delete_all -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_history_maxsize</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Gets the maximal size of stored getHistory entries.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_history_maxsize</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Gets the maximal size of stored getHistory entries.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_history_maxsize -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_history_maxsize_set</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the maximal size of Tamaya getHistory entries.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_history_maxsize_set</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Sets the maximal size of Tamaya getHistory entries.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_history_maxsize_set size <b>ARGUMENTS</b> -<i>size</i>: The maximum number of entries in the getHistory.</p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_info</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Show he current Tamaya status.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +<i>size</i>: The maximum number of entries in the getHistory. +<p></p></pre></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_info</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Show he current Tamaya status.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_info -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_osgi_config</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Show the current OSGI configuration.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_osgi_config</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Show the current OSGI configuration.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_osgi_config [options] pid <b>ARGUMENTS</b> <i>pid</i> The target OSGI component PID. <b>OPTIONS</b> <i>section, -s, --section</i>: A starting expression selecting the keys to be filtered. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_policy</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Get the current Tamaya overriding policy.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_policy</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Get the current Tamaya overriding policy.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_policy -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_policy_set</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Sets the current Tamaya operation policy.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_policy_set</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Sets the current Tamaya operation policy.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_policy_set tm_policy_set <b>ARGUMENTS</b> -<i>tm_policy_set</i>: The operation policy how Tamaya intercepts OSGI configuration.</p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_propagate_updates</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Flag if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +<i>tm_policy_set</i>: The operation policy how Tamaya intercepts OSGI configuration. +<p></p></pre></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_propagate_updates</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Flag if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> -tm_propagate_updates</p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_propagate_updates_set</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Configure if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +tm_propagate_updates +<p></p></pre></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_propagate_updates_set</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Configure if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_propagate_updates_set enabled <b>ARGUMENTS</b> <i>enabled</i>: Set to true to enable Tamaya's updating trigger. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_property</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Get a Tamaya property.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre><b>SYNTAX</b> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_property</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Get a Tamaya property.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre><b>SYNTAX</b> tamaya:tm_property [options] [key] <b>ARGUMENTS</b> <i>key</i>: The target property source id. <b>OPTIONS</b> <i>extended,e</i>: Also print extended property value attributes. <i>propertysource, ps</i>: The target property source id. -</pre></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_propertysource</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Show the current Tamaya entries of a propertysource.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre><b>SYNTAX</b> +</pre> <p></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_propertysource</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Show the current Tamaya entries of a propertysource.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre><b>SYNTAX</b> tamaya:tm_propertysource [propertysource] <b>ARGUMENTS</b> -<i>propertysource</i>: The target property source id.</p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">tm_propertysources</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Get a list of currently registered propertysources.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><pre> +<i>propertysource</i>: The target property source id. +<p></p></pre></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">tm_propertysources</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Get a list of currently registered propertysources.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"> </p><pre> <b>SYNTAX</b> tamaya:tm_propertysources -</pre></p></td> -</tr> -</tbody> -</table> -</div> -<div class="sect3"> -<h4 id="_apache_karaf_ferature">Apache Karaf Ferature</h4> -<div class="paragraph"> -<p>Apache Tamaya provides a Karaf feature with all required dependencies -as org.apache.tamaya.ext:tamaya-karaf-features:{tamaya-version}:features:xml.</p> -</div> -</div> -<div class="sect3"> -<h4 id="_apache_felix_gogo_console">Apache Felix Gogo Console</h4> -<div class="paragraph"> -<p>Apache Tamaya also provides the same commands as described for <em>Karaf</em>, but executable in -plaing Gogo console as used by Apache Felix and Equinox as -org.apache.tamaya.ext:tamaya-gogo-shell:{tamaya-version}. Refer to the previous sections for -a detailed command description.</p> -</div> -</div> -</div> -</div> +</pre> <p></p></td> + </tr> + </tbody> + </table> + </div> + <div class="sect3"> + <h4 id="_apache_karaf_ferature">Apache Karaf Ferature</h4> + <div class="paragraph"> + <p>Apache Tamaya provides a Karaf feature with all required dependencies as org.apache.tamaya.ext:tamaya-karaf-features:{tamaya-version}:features:xml.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_apache_felix_gogo_console">Apache Felix Gogo Console</h4> + <div class="paragraph"> + <p>Apache Tamaya also provides the same commands as described for <em>Karaf</em>, but executable in plaing Gogo console as used by Apache Felix and Equinox as org.apache.tamaya.ext:tamaya-gogo-shell:{tamaya-version}. Refer to the previous sections for a detailed command description.</p> + </div> + </div> + </div> + </div> </div></p> <hr /> @@ -1120,8 +1021,8 @@ a detailed command description.</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_remote.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_remote.html b/documentation/extensions/mod_remote.html index 7e9f713..2be7264 100644 --- a/documentation/extensions/mod_remote.html +++ b/documentation/extensions/mod_remote.html @@ -125,57 +125,54 @@ <h1>Apache Tamaya - Extension: Remote Configuration</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="Remote">Tamaya Remote Configuration (Extension Module)</h2> -<div class="sectionbody"> -<div class="paragraph"> -<p>Tamaya <em>Remote</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>Remote</em> provides support for reading configuration from remote resources. It provides -out-of-the-box support for reading scoped configuration from a Tamaya configuration server as -provided with the Tamaya <em>server</em> module .</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 remote 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="Remote">Tamaya Remote Configuration (Extension Module)</h2> + <div class="sectionbody"> + <div class="paragraph"> + <p>Tamaya <em>Remote</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>Remote</em> provides support for reading configuration from remote resources. It provides out-of-the-box support for reading scoped configuration from a Tamaya configuration server as provided with the Tamaya <em>server</em> module .</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 remote 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-remote</artifactId> <version>{tamaya_version}</version> -</dependency></code></pre> -</div> -</div> -</div> -<div class="sect2"> -<h3 id="_reading_remote_configuration_from_a_tamaya_configuration_server">Reading Remote configuration from a Tamaya Configuration Server</h3> -<div class="paragraph"> -<p>The remote module allows reading JSON formatted configuration as provided by the Tamaya <em>server</em> extension . The JSON -format used looks as follows:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-json" data-lang="json">{ +</dependency></code></pre> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_reading_remote_configuration_from_a_tamaya_configuration_server">Reading Remote configuration from a Tamaya Configuration Server</h3> + <div class="paragraph"> + <p>The remote module allows reading JSON formatted configuration as provided by the Tamaya <em>server</em> extension . The JSON format used looks as follows:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-json" data-lang="json">{ "java.vendor.url": "http://java.oracle.com/";, "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/";, "java.vm.info": "mixed mode", @@ -203,23 +200,18 @@ format used looks as follows:</p> "_info.timestamp": "1441463200571", "_timestamp": "1441463200571", "_type": "Configuration" -}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>Basically there are no constraints about they keys provided. By default Tamaya uses keys prefixed with -'_' to identify meta-data entries, but this is not a required precondition.</p> -</div> -<div class="paragraph"> -<p>Finally such a remote configuration can be easily integrated by inheriting from the provided base -class. Hereby a default ordinal must be defined and the protected Collection<URL> getAccessURLs() -method must be implemented to define the URL from where the configuration should be accessible. Hereby -multiple URLs can be provided, which are accesed in order as provided by the collection’s iterator. The -first accessible URL determines the configuration read.</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public class RemotePropertySource extends BaseRemotePropertySource{ +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Basically there are no constraints about they keys provided. By default Tamaya uses keys prefixed with '_' to identify meta-data entries, but this is not a required precondition.</p> + </div> + <div class="paragraph"> + <p>Finally such a remote configuration can be easily integrated by inheriting from the provided base class. Hereby a default ordinal must be defined and the protected Collection<URL> getAccessURLs() method must be implemented to define the URL from where the configuration should be accessible. Hereby multiple URLs can be provided, which are accesed in order as provided by the collectionâs iterator. The first accessible URL determines the configuration read.</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public class RemotePropertySource extends BaseRemotePropertySource{ @Override protected Collection<URL> getAccessURLs() { @@ -239,11 +231,11 @@ first accessible URL determines the configuration read.</p> } } -}</code></pre> -</div> -</div> -</div> -</div> +}</code></pre> + </div> + </div> + </div> + </div> </div></p> <hr /> @@ -255,8 +247,8 @@ first accessible URL determines the configuration read.</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_resolver.html ---------------------------------------------------------------------- diff --git a/documentation/extensions/mod_resolver.html b/documentation/extensions/mod_resolver.html index 20a23d9..a24c994 100644 --- a/documentation/extensions/mod_resolver.html +++ b/documentation/extensions/mod_resolver.html @@ -125,102 +125,101 @@ <h1>Apache Tamaya - Extension: Resolver</h1> </div> - <p><em>2018-04-26</em></p> + <p><em>2018-05-17</em></p> - <p><div class="sect1"> -<h2 id="Resolver">Tamaya Resolver (Extension Module)</h2> -<div class="sectionbody"> -<div class="paragraph"> -<p>Tamaya <em>Resolver</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>Resolver</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> -for further details about modules.</p> -</div> -<div class="paragraph"> -<p>Tamaya Resolver provides a dynamic resolution mechanism, which allows to use UNIX-styled (${...} placeholder -expressions in your configuration values. The resolver hereby supports transitive resolution and also prevents -cycles to loop endlessly.</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 dynamic value resolution 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 class="sect1"> + <h2 id="Resolver">Tamaya Resolver (Extension Module)</h2> + <div class="sectionbody"> + <div class="paragraph"> + <p>Tamaya <em>Resolver</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>Resolver</em> is an extension module. Refer to the <a href="../extensions.html">extensions documentation</a> for further details about modules.</p> + </div> + <div class="paragraph"> + <p>Tamaya Resolver provides a dynamic resolution mechanism, which allows to use UNIX-styled (${...} placeholder expressions in your configuration values. The resolver hereby supports transitive resolution and also prevents cycles to loop endlessly.</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 dynamic value resolution 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-resolver</artifactId> <version>0.4-incubating-SNAPSHOT</version> -</dependency></code></pre> -</div> -</div> -<div class="paragraph"> -<p>The module automatically registers an according PropertyFilter that is automatically called, whenever a value -is accessed.</p> -</div> -</div> -<div class="sect2"> -<h3 id="_available_resolvers">Available Resolvers</h3> -<div class="paragraph"> -<p>Currently the module defines the following resolvers:</p> -</div> -<table class="tableblock frame-all grid-all spread"> -<caption class="title">Table 1. Available Resolvers</caption> -<colgroup> -<col style="width: 25%;"> -<col style="width: 50%;"> -<col style="width: 25%;"> -</colgroup> -<tbody> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock"><em>Expression</em></p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><em>Description</em></p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock"><em>Example</em></p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">conf:<configKey></p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Reads another configKey and replaces the expression with the value found.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">conf-ref=${conf:anotherConf.entryKey}</p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">resource:<resourceRef></p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Reads a resource from the current classpath and replaces the expression with the given text content.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">cp-ref=${resource:Testresource.txt}</p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">file:<fileRef></p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Reads a resource from the current classpath and replaces the expression with the given text content.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">file-ref=${file:c:\myFile.txt}</p></td> -</tr> -<tr> -<td class="tableblock halign-left valign-top"><p class="tableblock">url:<url></p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">Reads an URL and replaces the expression with the given text content.</p></td> -<td class="tableblock halign-left valign-top"><p class="tableblock">url-ref=${url:http://www.google.com}</p></td> -</tr> -</tbody> -</table> -</div> -<div class="sect2"> -<h3 id="_spi_implementing_your_own_resolvers">SPI: Implementing your own Resolvers</h3> -<div class="paragraph"> -<p>The module also provides a small but powerful SPI for adding your own resolver implementations. Basically the -first and most important thing to do is implementing the ExpressionResolver interface:</p> -</div> -<div class="listingblock"> -<div class="title">Implementing a Custom Resolver</div> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public class PwdDecrypter implements ExpressionResolver { +</dependency></code></pre> + </div> + </div> + <div class="paragraph"> + <p>The module automatically registers an according PropertyFilter that is automatically called, whenever a value is accessed.</p> + </div> + </div> + <div class="sect2"> + <h3 id="_available_resolvers">Available Resolvers</h3> + <div class="paragraph"> + <p>Currently the module defines the following resolvers:</p> + </div> + <table class="tableblock frame-all grid-all spread"> + <caption class="title"> + Table 1. Available Resolvers + </caption> + <colgroup> + <col style="width: 25%;"> + <col style="width: 50%;"> + <col style="width: 25%;"> + </colgroup> + <tbody> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock"><em>Expression</em></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"><em>Description</em></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"><em>Example</em></p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">conf:<configKey></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Reads another configKey and replaces the expression with the value found.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">conf-ref=${conf:anotherConf.entryKey}</p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">resource:<resourceRef></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Reads a resource from the current classpath and replaces the expression with the given text content.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">cp-ref=${resource:Testresource.txt}</p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">file:<fileRef></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Reads a resource from the current classpath and replaces the expression with the given text content.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">file-ref=${file:c:\myFile.txt}</p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock">url:<url></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Reads an URL and replaces the expression with the given text content.</p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">url-ref=${url:http://www.google.com}</p></td> + </tr> + </tbody> + </table> + </div> + <div class="sect2"> + <h3 id="_spi_implementing_your_own_resolvers">SPI: Implementing your own Resolvers</h3> + <div class="paragraph"> + <p>The module also provides a small but powerful SPI for adding your own resolver implementations. Basically the first and most important thing to do is implementing the ExpressionResolver interface:</p> + </div> + <div class="listingblock"> + <div class="title"> + Implementing a Custom Resolver + </div> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public class PwdDecrypter implements ExpressionResolver { @Override public String getResolverPrefix() { @@ -235,31 +234,27 @@ first and most important thing to do is implementing the ExpressionResolver inte private String decrypt(String s) { ... } -}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>Basically that is all you must do, after having registered the class with the ServiceLoader it will be found -and loaded by the implementation. With that all expressions that start with the given prefix are passed to the -resolver, so all the following expressions will be sent to the implementation:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">blabla ${decrypt:myname} -blabla ${decrypt:myname} foo blabla ${decrypt:myname}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>Hereby evaluation is repeated until no further change of values could be detetced. In case of a endless loop -the evaluation is broken after a (configurable) number of cycles.</p> -</div> -<div class="paragraph"> -<p>Under the hood instances of ExpressionResolver are managed by an implementation of the ExpressionEvaluator -interface:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ExpressionEvaluator { +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Basically that is all you must do, after having registered the class with the ServiceLoader it will be found and loaded by the implementation. With that all expressions that start with the given prefix are passed to the resolver, so all the following expressions will be sent to the implementation:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">blabla ${decrypt:myname} +blabla ${decrypt:myname} foo blabla ${decrypt:myname}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Hereby evaluation is repeated until no further change of values could be detetced. In case of a endless loop the evaluation is broken after a (configurable) number of cycles.</p> + </div> + <div class="paragraph"> + <p>Under the hood instances of ExpressionResolver are managed by an implementation of the ExpressionEvaluator interface:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface ExpressionEvaluator { /** * Evaluates the current expression. * @param key the key, not null. @@ -267,15 +262,14 @@ interface:</p> * @return the filtered/evaluated value, including null. */ String evaluateExpression(String key, String value); -}</code></pre> -</div> -</div> -<div class="paragraph"> -<p>Implementing and registering this interface gives you full control, but in most cases you should be fine with -the default implementation in place.</p> -</div> -</div> -</div> +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>Implementing and registering this interface gives you full control, but in most cases you should be fine with the default implementation in place.</p> + </div> + </div> + </div> </div></p> <hr /> @@ -287,8 +281,8 @@ the default implementation in place.</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>
