http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8e3904a8/documentation-new/core.html ---------------------------------------------------------------------- diff --git a/documentation-new/core.html b/documentation-new/core.html new file mode 100644 index 0000000..877f3e2 --- /dev/null +++ b/documentation-new/core.html @@ -0,0 +1,713 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";> + +<html xmlns="http://www.w3.org/1999/xhtml";> + <head> + <meta charset="utf-8"/> + <title>Tamaya Incubator</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0"/> + <meta name="description" content=""/> + <meta name="author" content=""/> + <meta name="keywords" content=""/> + <meta name="generator" content="'JBake '+'${version}"/> + + <!-- Le styles --> + <link href="../css/bootstrap.min.css" rel="stylesheet"/> + <link href="../css/asciidoctor.css" rel="stylesheet"/> + <link href="../css/base.css" rel="stylesheet"/> + <link href="../css/prettify.css" rel="stylesheet"/> + + <!-- HTML5 shim, for IE6-8 support of HTML5 elements --> + <!--[if lt IE 9]> + <script src="../js/html5shiv.min.js"></script> + <![endif]--> + + <!-- Fav and touch icons from ASF --> + <link rel="shortcut icon" href="../favicon.ico"/> + <link rel="apple-touch-icon" sizes="57x57" href="../favicons/apple-touch-icon-57x57.png"/> + <link rel="apple-touch-icon" sizes="60x60" href="../favicons/apple-touch-icon-60x60.png"/> + <link rel="apple-touch-icon" sizes="72x72" href="../favicons/apple-touch-icon-72x72.png"/> + <link rel="apple-touch-icon" sizes="76x76" href="../favicons/apple-touch-icon-76x76.png"/> + <link rel="apple-touch-icon" sizes="114x114" href="../favicons/apple-touch-icon-114x114.png"/> + <link rel="apple-touch-icon" sizes="120x120" href="../favicons/apple-touch-icon-120x120.png"/> + <link rel="apple-touch-icon" sizes="144x144" href="../favicons/apple-touch-icon-144x144.png"/> + <link rel="apple-touch-icon" sizes="152x152" href="../favicons/apple-touch-icon-152x152.png"/> + <link rel="apple-touch-icon" sizes="180x180" href="../favicons/apple-touch-icon-180x180.png"/> + <link rel="icon" type="image/png" href="../favicons/favicon-32x32.png" sizes="32x32"/> + <link rel="icon" type="image/png" href="../favicons/favicon-194x194.png" sizes="194x194"/> + <link rel="icon" type="image/png" href="../favicons/favicon-96x96.png" sizes="96x96"/> + <link rel="icon" type="image/png" href="../favicons/android-chrome-192x192.png" sizes="192x192"/> + <link rel="icon" type="image/png" href="../favicons/favicon-16x16.png" sizes="16x16"/> + <link rel="manifest" href="../favicons/manifest.json"/> + <link rel="shortcut icon" href="../favicons/favicon.ico"/> + <meta name="msapplication-TileColor" content="#603cba"/> + <meta name="msapplication-TileImage" content="../favicons/mstile-144x144.png"/> + <meta name="msapplication-config" content="../favicons/browserconfig.xml"/> + <meta name="theme-color" content="#303284"/> + </head> + <body onload="prettyPrint()"> + <div id="wrap"> + <div> + + <!-- Fixed navbar --> + <div class="navbar navbar-default navbar-fixed-top" role="navigation"> + <div class="container"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="../index.html">Apache Tamaya (incubating)</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + <li><a href="../start.html">Tamaya in 5 minutes</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="../documentation/usecases.html">Use Cases and Requirements</a></li> + <li><a href="../documentation/quickstart.html">Quickstart</a></li> + <li><a href="../documentation/api.html">API</a></li> + <li><a href="../documentation/core.html">Core</a></li> + <li><a href="../documentation/extensions.html">Extension Guide</a></li> + <li class="divider"></li> + <li><a href="../apidocs/stable/index.html">Javadoc 0.3-incubating (release/stable)</a></li> + <li><a href="../apidocs/development/index.html">Javadoc 0.4-incubating-SNAPSHOT (development)</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Development <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="../development/source.html">Sources</a></li> + <li><a href="../development/community.html">Community</a></li> + <li><a href="../development/team.html">Project Team</a></li> + <li><a target="_blank" href="https://builds.apache.org/view/S-Z/view/Tamaya/";>CI / ASF Jenkins</a></li> + <li><a target="_blank" href="https://issues.apache.org/jira/browse/TAMAYA";>Issues / ASF Jira</a></li> + <li><a href="../devguide.html">Development Guide</a></li> + <li><a href="../release-guide.html">Release Guide</a></li> + <li class="divider"></li> + <li><a href="../development/possible-contributions.html">Possible Contributions</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Releases <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="../download.html">Download</a></li> + <li><a href="../history.html">Release History</a></li> + </ul> + </li> +<!-- Example: + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Dropdown <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="#">Action</a></li> + <li><a href="#">Another action</a></li> + <li><a href="#">Something else here</a></li> + <li class="divider"></li> + <li class="dropdown-header">Nav header</li> + <li><a href="#">Separated link</a></li> + <li><a href="#">One more separated link</a></li> + </ul> + </li> +--> + <li><a href="../sitemap.xml">Sitemap</a></li> + <li><a href="../feed.xml">Subscribe</a></li> + </ul> + </div><!--/.nav-collapse --> + </div> + </div> + + </div> + <div class="container"> + + <div class="page-header"> + <h1></h1> + </div> + + <p><em>2018-02-26</em></p> + + <p><div class="sect1"> +<h2 id="Core">Tamaya Core Implementation</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_overview">Overview</h3> +<div class="paragraph"> +<p>Tamaya Core provides an implementation of the <a href="api.html">Configuration API</a> and adds additional functionality +and building blocks for supporting SPI implementations.</p> +</div> +<div class="paragraph"> +<p>Tamaya contains the following core artifacts:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><strong>tamaya-base</strong> provides implementations and base classes for different API artifacts such as Config, +ConfigContext, ConfigBuilder, BaseConfigSource and more. It is +built as an independent module, which also can be used with other implementations.</p> +</li> +<li> +<p>The <strong>tamaya-core</strong> +implementation</p> +<div class="ulist"> +<ul> +<li> +<p>leverages these base classes to build up a full API implementation, adding converter +implementations for most common Java types.</p> +</li> +<li> +<p>A java.util.ServiceLoader based ServiceContext implementation. This allows component priorization based +on the @Priority annotations.</p> +</li> +<li> +<p>A PropertyConverterManager that loads and stores references to all the preconfigured PropertyConverter instances, +thus providing type conversion for all important types.</p> +</li> +</ul> +</div> +</li> +<li> +<p>A simple default configuration setup using the current classpath and an optional staging variable.</p> +</li> +<li> +<p>It collects all ConfigSource and ConfigSourceProvider instances registered with the ServiceLoader and +registers them in the global ConfigurationContext</p> +</li> +<li> +<p>It provides a ConfigBuilder implementation (DefaultConfigBuilder), including an extended TamayaConfigBuilder +variant.</p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>The overall size of the library is very small. All required components are implemented and registered, so basically the +Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible +enough to be extended/accommodated with additional features as needed, such as</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>placeholder and resolution mechanisms (org.apache.tamaya.ext:tamaya-resolver)</p> +</li> +<li> +<p>dynamic resource path lookup, e.g. with ant styled patterns (org.apache.tamaya.ext:tamaya-resources)</p> +</li> +<li> +<p>configuration injection and configuration templates (org.apache.tamaya.ext:tamaya-injcetion-api)</p> +</li> +<li> +<p>abstraction for reusable formats (org.apache.tamaya.ext:tamaya-formats)</p> +</li> +<li> +<p>integration with other existing solutions (e.g. org.apache.tamaya.ext:tamaya-spring)</p> +</li> +<li> +<p>configuration and configuration isolation targeting Java EE (org.apache.tamaya.ext:tamaya-injection-ee)</p> +</li> +<li> +<p>dynamic configuration and configuration updates (org.apache.tamaya.ext:tamaya-events)</p> +</li> +<li> +<p>remote configuration (org.apache.tamaya.ext:tamaya-etcd, org.apache.tamaya.ext:tamaya-consul, +org.apache.tamaya.ext:tamaya-hazelcast)</p> +</li> +<li> +<p>and more</p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>For details about the extension modules available and their functionality refer to the <a href="extensions.html">extension user guide</a>.</p> +</div> +</div> +<div class="sect2"> +<h3 id="CoreConverters">Default Converters</h3> +<div class="paragraph"> +<p>The <em>SPI</em> base module provides several Converter implementations, which are automatically registered by the +<em>Core</em> module. Find below the listing of converters automatically registered with the Core module:</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>Target Type</em></th> +<th class="tableblock halign-left valign-top"><em>Class Name</em></th> +<th class="tableblock halign-left valign-top"><em>Supported Formats</em></th> +</tr> +</thead> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.math.BigDecimal</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">BigDecimalConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">1.2345, 0xFF</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.math.BigInteger</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">BigIntegerConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">0xFF, 1234</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Boolean</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">BooleanConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">true, false, T, F, 1 ,0</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Byte</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">ByteConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">0xFF, MIN_VALUE, MAX_VALUE, 123</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Character</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">CharConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">0xFF, 'a', 'H', 123</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Class</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">ClassConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><fully qualified class name></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.util.Currency</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">CurrencyConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">CHF, 123</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Double</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">DoubleConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><em>Enums</em></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">EnumConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><Enum item name></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Float</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">FloatConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Integer</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">IntegerConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">1, 0xD3, MIN_VALUE, MAX_VALUE</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">LocalDate</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">LocalDateConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><Date as defined by LocalDate.parse(String)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">LocalTime</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">LocalTimeConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><Time as defined by LocalTime.parse(String)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">LocalDateTime</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">LocalDateTimeConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><LocalDateTime as defined by LocalDateTime.parse(String)></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Long</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">LongConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">1, 0xD3, MIN_VALUE, MAX_VALUE</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Number</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">NumberConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.ui.lang.Short</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">ShortConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">1, 0xD3, MIN_VALUE, MAX_VALUE</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.net.URI</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">URIConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://localhost:2020/testresource?api=true"; class="bare">http://localhost:2020/testresource?api=true</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">java.net.URL</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">URLConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://localhost:2020/testresource?api=true"; class="bare">http://localhost:2020/testresource?api=true</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">ZoneId</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">ZoneIdConverter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Europe/Zurich</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_registering_converters">Registering Converters</h3> +<div class="paragraph"> +<p>Additional Converters can be implemented easily. It is recommended to register them using +the java.util.ServiceLoader, meaning you add a file under META-INF/service/javax.config.spi.Converter +containing the fully qualified class names of the converters to be registered (one line each) to enable +auto-discovery.</p> +</div> +<div class="paragraph"> +<p>Alternatively you can also use a TamayaConfigBuilder to add additional converters programmatically.</p> +</div> +</div> +<div class="sect2"> +<h3 id="ComponentLoadingAndPriorization">Component Loading and Priorization</h3> +<div class="paragraph"> +<p>Tamaya <em>Core</em> in general loads all components by default using the java.util.ServiceLoader mechanism. This means that +new components must be registered by adding a file under META-INF/service/<myInterfaceName> containing the fully +qualified implementation class names of the components to be registered (one line per each). +The ServiceLoader itself does not provide any functionality for overriding or ordering of +components. Tamaya <em>Core</em> adds such a functionality with the possibility to add @Priority +annotations to the components registered. By default, and if no annotation is added 0 is assumed +as priority. Hereby higher values preceed lower values, meaning</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>if a <em>singleton</em> component is accessed from the current ServiceContext the component with the +higher value effectively <em>overrides/replaces</em> any component with lower values.</p> +</li> +<li> +<p>if a <em>collection</em> of components is obtained from the ServiceContext the components are <em>ordered</em> +based on their priorities, where the ones with higher priority are before components with lower +priority.</p> +</li> +<li> +<p>if priorities <em>match</em> Tamaya <em>Core</em> additionally sorts them using the <em>simple class name</em>. +This ensures that ordering is still defined and predictable in all scenarios.</p> +</li> +</ul> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +Sorting the property sources based on their ordinal value is only the default ordering + principle applied. By implementing your own implementation of ConfigurationProviderSpi + you can apply a different logic: +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="RegisteringConfigSources">Registering ConfigSources</h3> +<div class="paragraph"> +<p>ConfigSource implementations that provide configuration properties are registered as components as described in the +previous section. Hereby the precedence (ordering) of property sources is not hard-coded. Instead a Comparator<ConfigSource> +can be passed to a ConfigurationContextBuilder to perform automatic ordering of the property sources +registered. The default implementation hereby uses the following logic:</p> +</div> +<div class="olist arabic"> +<ol class="arabic"> +<li> +<p>It checks for an property entry config.ordinal if present the value is parsed into an int value and used as +the ordinal val value.</p> +</li> +<li> +<p>It checks for an explicit method int getOrdinal(), if found its value is taken as an ordinal.</p> +</li> +<li> +<p>It checks for a @Priority annotation, if present the priority value is used as an ordinal.</p> +</li> +<li> +<p>If none of the above works, 0 is assumed as ordinal value.</p> +</li> +<li> +<p>If multiple ConfigSource instances share the same ordinal value, they are ordered based on their fully qualified +class names.</p> +</li> +</ol> +</div> +<div class="paragraph"> +<p>Custom implementations of the config source comparator can be applied by calling +TamayaConfigBuilder.sortSources(Comparator<ConfigSource>). The default comparator can be replaced +by passing the fully qualified comparator class name as system property:</p> +</div> +<div class="paragraph"> +<p>-Dconfig-source-comparator=a.b.c.MyComparatorClass</p> +</div> +<div class="paragraph"> +<p>The ladder allows to adapt the ordering of auto-discovered config sources, even if the value returned by +int getOrdinal() cannot be changed.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="CoreConfigSources">Configuration Setup in Core</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Tamaya Core provides a minimal configuration setting, that allows you to configure SE +applications already easily. Basically configuration is built up by default as follows:</p> +</div> +<div class="olist arabic"> +<ol class="arabic"> +<li> +<p>Read environment properties and add them prefixed with env.</p> +</li> +<li> +<p>Read all files found at META-INF/javaconfig.properties +and META-INF/javaconfig.xml</p> +</li> +</ol> +</div> +<div class="sect2"> +<h3 id="_overview_of_registered_default_config_sources_and_providers">Overview of Registered Default Config Sources and Providers</h3> +<div class="paragraph"> +<p>The Tamaya Core implementation provides a couple of default ConfigSource implementations, which are automatically +registered. They are all in the package org.apache.tamaya.base.configsource:</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>Type</em></th> +<th class="tableblock halign-left valign-top"><em>Class Name</em></th> +<th class="tableblock halign-left valign-top"><em>Ordinal Used</em></th> +</tr> +</thead> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">META-INF/javaconfig.properties</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">JavaConfigurationProvider</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">100</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">META-INF/javaconfig.xml</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">JavaConfigurationProvider</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">100</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">JNDI Entries</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">JNDIConfigSource</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">200</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">Environment Properties</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">EnvironmentConfigSource</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">300</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">System Properties</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">SystemConfigSource</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">1000</p></td> +</tr> +</tbody> +</table> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +Similarly to converters the config sources shown here are defined within the "tamaya-base* module + and automatically registered with the <strong>tamaya-core</strong> implementation using Tamaya’s auto-discovery mechanisms. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +JNDIConfigSource is provided by the <code>tamaya-jndi</code> extension module. +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_abstract_class_propertiesfileconfigsource">Abstract Class PropertiesFileConfigSource</h3> +<div class="paragraph"> +<p>The abstract class PropertiesFileConfigSource can be used for implementing a ConfigSource based on a URL +instance that points to a .properites file. It requires a URL to be passed on the constructor:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="prettyprint highlight"><code class="language-java" data-lang="java">PropertiesFileConfigSource(URL url);</code></pre> +</div> +</div> +<div class="sect3"> +<h4 id="_abstract_class_propertiesconfigsource">Abstract Class PropertiesConfigSource</h4> +<div class="paragraph"> +<p>The abstract class PropertiesConfigSource can be used for implementing a ConfigSource based on a Properties +instance. It requires a Properties to be passed on the constructor:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="prettyprint highlight"><code class="language-java" data-lang="java">PropertiesConfigSource(Properties properties);</code></pre> +</div> +</div> +</div> +<div class="sect3"> +<h4 id="_abstract_class_baseconfigsource">Abstract Class BaseConfigSource</h4> +<div class="paragraph"> +<p>The abstract class BaseConfigSource can be used for implementing custom ConfigSource classes. It requires only +one method to implemented:</p> +</div> +<div class="listingblock"> +<div class="title">Implementing a ConfigSource using BaseConfigSource</div> +<div class="content"> +<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public class MyConfigSource extends BaseConfigSource{ + + public String getName(){ + // return a unique name for the config source, e.g. based on the underlying resource. This name also + // allows to access the property source later + } + + public Map<String, String> getProperties(){ + // Get a map with all properties provided by this config source + } + +}</code></pre> +</div> +</div> +<div class="paragraph"> +<p>By default the ordinal of the config sources will be 1000, unless the key config.ordinal +as defined in ConfigSource.CONFIG_ORDINAL is present in the current ConfigSource. Of course +it is also possible to override the inherited protected void initializeOrdinal(final int defaultOrdinal), +or directly int getOrdinal().</p> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="CoreConfigSourceProviders">Default ConfigSourceProvider in Core</h3> +<div class="paragraph"> +<p>With org.apache.tamaya.core.provider.JavaConfigurationProvider there is also a default ConfigSourceProvider +present that loads all .properties files found at META-INF/javaconfig.properties +and META-INF/javaconfig.xml.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_replacing_the_property_value_evaluation_policy">Replacing the property value evaluation policy</h3> +<div class="paragraph"> +<p>Tamaya’s core implementation allows to replace the complete logic how a configuration value or the current configuration +properties are calculated from a given ConfigContext by implementing the ConfigValueEvaluator +interface:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="prettyprint highlight"><code class="language-java" data-lang="java">/** + * Component SPI which encapsulates the evaluation of a single or full <b>raw</b>value + * for a {@link ConfigurationContext}. + */ +public interface ConfigValueEvaluator { + + /** + * Evaluates single value using a {@link ConfigContext}. + * @param key the config key, not null. + * @param context the context, not null. + * @return the value, or null. + */ + ConfigValue evaluteRawValue(String key, ConfigContext context); + + /** + * Evaluates all property values from a {@link ConfigurationContext}. + * @param context the context, not null. + * @return the value, or null. + */ + Iterable<ConfigValue> evaluateRawValues(ConfigContext context); + +}</code></pre> +</div> +</div> +<div class="paragraph"> +<p>The default implementation DefaultConfigValueEvaluator implements the following logic:</p> +</div> +<div class="olist arabic"> +<ol class="arabic"> +<li> +<p>Collect all ConfigSources from the context.</p> +</li> +<li> +<p>Access String get(String) (single key access)/ Map<String,String> getProperties() +(config map access) from each property source and combine the previous with the next value using +the ConfigValueCombinationPolicy in place.</p> +</li> +</ol> +</div> +<div class="paragraph"> +<p>The resulting <em>raw</em> value(s) are then finally handed over to the registered filters and finally +converted to String/Map<String,String> as required by the user API.</p> +</div> +<div class="paragraph"> +<p>To replace this default behaviour you must register your implementation with the current +ServiceContext.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="Extensions">Adding Extensions</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Tamaya <em>Core</em> only implements the <a href="api.html">API</a>. Many users require/wish additional functionality from a +configuration system. Fortunately there are numerous extensions available that add further functionality. +Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath.</p> +</div> +<div class="paragraph"> +<p>For detailed information on the extensions available refer to the <a href="extensions.html">extensions documentation</a>.</p> +</div> +</div> +</div></p> + + <hr /> + </div> + </div> + <div> + <div id="push"></div> + + <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-04-26</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> + <b>Disclaimer</b> + Apache Tamaya (incubating) is an effort undergoing + incubation at + The Apache Software Foundation (ASF), sponsored by + the name of Apache Incubator. Incubation is required of + all newly accepted projects until a further review indicates + that the infrastructure, communications, and decision making + process have stabilized in a manner consistent with other + successful ASF projects. While incubation status is not + necessarily a reflection of the completeness or stability of + the code, it does indicate that the project has yet to + be fully endorsed by the ASF. + Apache, Apache Tamaya, and the Apache Tamaya logo are registered trademarks or trademarks of The Apache Software Foundation in the U.S. and/or other countries.<br /> + <a href="https://incubator.apache.org/guides/website.html"; style="border:0px;" target="_target"> + <img class="incubator-logo" src="../logos/apache-incubator.png"/> + </a> + </p> + </div> + </div> + + <!-- Le javascript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="../js/jquery-1.11.1.min.js"></script> + <script src="../js/bootstrap.min.js"></script> + <script src="../js/prettify.js"></script> + </div> + </body> +</html>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8e3904a8/documentation-new/extensions.html ---------------------------------------------------------------------- diff --git a/documentation-new/extensions.html b/documentation-new/extensions.html new file mode 100644 index 0000000..f9a60ae --- /dev/null +++ b/documentation-new/extensions.html @@ -0,0 +1,422 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";> + +<html xmlns="http://www.w3.org/1999/xhtml";> + <head> + <meta charset="utf-8"/> + <title>Tamaya Incubator</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0"/> + <meta name="description" content=""/> + <meta name="author" content=""/> + <meta name="keywords" content=""/> + <meta name="generator" content="'JBake '+'${version}"/> + + <!-- Le styles --> + <link href="../css/bootstrap.min.css" rel="stylesheet"/> + <link href="../css/asciidoctor.css" rel="stylesheet"/> + <link href="../css/base.css" rel="stylesheet"/> + <link href="../css/prettify.css" rel="stylesheet"/> + + <!-- HTML5 shim, for IE6-8 support of HTML5 elements --> + <!--[if lt IE 9]> + <script src="../js/html5shiv.min.js"></script> + <![endif]--> + + <!-- Fav and touch icons from ASF --> + <link rel="shortcut icon" href="../favicon.ico"/> + <link rel="apple-touch-icon" sizes="57x57" href="../favicons/apple-touch-icon-57x57.png"/> + <link rel="apple-touch-icon" sizes="60x60" href="../favicons/apple-touch-icon-60x60.png"/> + <link rel="apple-touch-icon" sizes="72x72" href="../favicons/apple-touch-icon-72x72.png"/> + <link rel="apple-touch-icon" sizes="76x76" href="../favicons/apple-touch-icon-76x76.png"/> + <link rel="apple-touch-icon" sizes="114x114" href="../favicons/apple-touch-icon-114x114.png"/> + <link rel="apple-touch-icon" sizes="120x120" href="../favicons/apple-touch-icon-120x120.png"/> + <link rel="apple-touch-icon" sizes="144x144" href="../favicons/apple-touch-icon-144x144.png"/> + <link rel="apple-touch-icon" sizes="152x152" href="../favicons/apple-touch-icon-152x152.png"/> + <link rel="apple-touch-icon" sizes="180x180" href="../favicons/apple-touch-icon-180x180.png"/> + <link rel="icon" type="image/png" href="../favicons/favicon-32x32.png" sizes="32x32"/> + <link rel="icon" type="image/png" href="../favicons/favicon-194x194.png" sizes="194x194"/> + <link rel="icon" type="image/png" href="../favicons/favicon-96x96.png" sizes="96x96"/> + <link rel="icon" type="image/png" href="../favicons/android-chrome-192x192.png" sizes="192x192"/> + <link rel="icon" type="image/png" href="../favicons/favicon-16x16.png" sizes="16x16"/> + <link rel="manifest" href="../favicons/manifest.json"/> + <link rel="shortcut icon" href="../favicons/favicon.ico"/> + <meta name="msapplication-TileColor" content="#603cba"/> + <meta name="msapplication-TileImage" content="../favicons/mstile-144x144.png"/> + <meta name="msapplication-config" content="../favicons/browserconfig.xml"/> + <meta name="theme-color" content="#303284"/> + </head> + <body onload="prettyPrint()"> + <div id="wrap"> + <div> + + <!-- Fixed navbar --> + <div class="navbar navbar-default navbar-fixed-top" role="navigation"> + <div class="container"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="../index.html">Apache Tamaya (incubating)</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + <li><a href="../start.html">Tamaya in 5 minutes</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="../documentation/usecases.html">Use Cases and Requirements</a></li> + <li><a href="../documentation/quickstart.html">Quickstart</a></li> + <li><a href="../documentation/api.html">API</a></li> + <li><a href="../documentation/core.html">Core</a></li> + <li><a href="../documentation/extensions.html">Extension Guide</a></li> + <li class="divider"></li> + <li><a href="../apidocs/stable/index.html">Javadoc 0.3-incubating (release/stable)</a></li> + <li><a href="../apidocs/development/index.html">Javadoc 0.4-incubating-SNAPSHOT (development)</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Development <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="../development/source.html">Sources</a></li> + <li><a href="../development/community.html">Community</a></li> + <li><a href="../development/team.html">Project Team</a></li> + <li><a target="_blank" href="https://builds.apache.org/view/S-Z/view/Tamaya/";>CI / ASF Jenkins</a></li> + <li><a target="_blank" href="https://issues.apache.org/jira/browse/TAMAYA";>Issues / ASF Jira</a></li> + <li><a href="../devguide.html">Development Guide</a></li> + <li><a href="../release-guide.html">Release Guide</a></li> + <li class="divider"></li> + <li><a href="../development/possible-contributions.html">Possible Contributions</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Releases <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="../download.html">Download</a></li> + <li><a href="../history.html">Release History</a></li> + </ul> + </li> +<!-- Example: + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Dropdown <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="#">Action</a></li> + <li><a href="#">Another action</a></li> + <li><a href="#">Something else here</a></li> + <li class="divider"></li> + <li class="dropdown-header">Nav header</li> + <li><a href="#">Separated link</a></li> + <li><a href="#">One more separated link</a></li> + </ul> + </li> +--> + <li><a href="../sitemap.xml">Sitemap</a></li> + <li><a href="../feed.xml">Subscribe</a></li> + </ul> + </div><!--/.nav-collapse --> + </div> + </div> + + </div> + <div class="container"> + + <div class="page-header"> + <h1></h1> + </div> + + <p><em>2018-04-26</em></p> + + <p><div class="sect1"> +<h2 id="_apache_tamaya_extension_modules">Apache Tamaya: Extension Modules</h2> +<div class="sectionbody"> +<!-- toc disabled --> +<div class="sect2"> +<h3 id="_mature_extensions">Mature Extensions</h3> +<div class="paragraph"> +<p>Mature extensions have a stable API and SPI, similar to the API and Implementations provided.</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>Links</em></th> +</tr> +</thead> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">N/A: currently no extensions have reached that maturity level.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-collections</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Collections support.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_collections.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-events</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides support for publishing configuration changes</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_events.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-filter</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides a programmatic filter for config entries.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_filter.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-features</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides a simple feature check for loaded extensions.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_features.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-formats</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides an abstract model for configuration formats</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_formats.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-functions</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides several functional extension points.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_functions.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-injection-api</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides Tamaya’s injection annotations API.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_injection.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-injection</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides configuration injection services and configuration template support.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_injection.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-injection-cdi</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Java EE/standalone compliant CDI integration using CDI for injection.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_cdi.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-jndi</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides a JNDI based PropertySource.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_jndi.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-json</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides format support for JSON based configuration.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_json.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-microprofile</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Implemenation and Integration with the Microprofile API.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_microprofile.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-mutable-config</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides API/SPI for writing configuration</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_mutable_config.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-optional</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Lets a Tamaya configuration to be used as an optional project extension only.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_optional.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-osgi</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Integration with OSGI containers.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_osgi.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-resolver</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides placeholder and dynamic resolution functionality for configuration values.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_resolver.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-resources</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides ant-style resource path resolution</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_resources.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-spring</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Integration for Spring / Spring Boot.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_spring.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-yaml</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Support for using yaml as a configuration format.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_yaml.html">Documentation</a></p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_extensions_sandbox">Extensions Sandbox</h3> +<div class="paragraph"> +<p>Extensions in <em>draft state</em> rather experimental or not yet very mature. API changes may occurr at any time +and the may also have severe issues or even not work at all. So use at your own risk or join and help +us getting them stable and well tested!</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +All extensions currently require Java 8. +</td> +</tr> +</table> +</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>Links</em></th> +</tr> +</thead> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-camel_beta</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Integration with Apache Camel.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_camel.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-classloader-support</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Configuration services considering classloaderas.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_classloader_support.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-commons_beta</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Integration Support for Apache Commons.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-configured-sysprops_beta</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Tamaya configuration to be provided as System.getProperties().</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_sysprops.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-consul_beta</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Integration with consul clusters.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_consul.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-etcd_beta</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Integration with etcd clusters.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_etcd.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-hazelcast_beta</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Integration with Hazelcast datagrids.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_hazelcast.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-jodatime_beta</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides support for JodaTime.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_jodatime.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-management_alpha</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides JMX support for inspecting configuration.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_management.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-metamodel_alpha</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides an XML API for building configuration.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_metamodel-staged.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-remote_alpha</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Remote configuration support using the server API.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_remote.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-server_alpha</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Publishes configuration as a REST service.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_server.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-ui_alpha</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides a web UI for a VM running Tamaya.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_ui.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-uom_beta</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides additional converters based on the Units of Measurement JSR.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_uom.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-usagetracker_beta</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Allows tracking of configuration usage.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_usagetracker.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-validation-alpha</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides an XML API for validating configuration.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_validation.html">Documentation</a></p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock">org.apache.tamaya.ext:tamaya-vertx-alpha</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Provides Vertx integration.</p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="extensions/mod_vertx.html">Documentation</a></p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div></p> + + <hr /> + </div> + </div> + <div> + <div id="push"></div> + + <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-04-26</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> + <b>Disclaimer</b> + Apache Tamaya (incubating) is an effort undergoing + incubation at + The Apache Software Foundation (ASF), sponsored by + the name of Apache Incubator. Incubation is required of + all newly accepted projects until a further review indicates + that the infrastructure, communications, and decision making + process have stabilized in a manner consistent with other + successful ASF projects. While incubation status is not + necessarily a reflection of the completeness or stability of + the code, it does indicate that the project has yet to + be fully endorsed by the ASF. + Apache, Apache Tamaya, and the Apache Tamaya logo are registered trademarks or trademarks of The Apache Software Foundation in the U.S. and/or other countries.<br /> + <a href="https://incubator.apache.org/guides/website.html"; style="border:0px;" target="_target"> + <img class="incubator-logo" src="../logos/apache-incubator.png"/> + </a> + </p> + </div> + </div> + + <!-- Le javascript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="../js/jquery-1.11.1.min.js"></script> + <script src="../js/bootstrap.min.js"></script> + <script src="../js/prettify.js"></script> + </div> + </body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8e3904a8/documentation-new/extensions/mod_camel.html ---------------------------------------------------------------------- diff --git a/documentation-new/extensions/mod_camel.html b/documentation-new/extensions/mod_camel.html new file mode 100644 index 0000000..aa364a5 --- /dev/null +++ b/documentation-new/extensions/mod_camel.html @@ -0,0 +1,321 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";> + +<html xmlns="http://www.w3.org/1999/xhtml";> + <head> + <meta charset="utf-8"/> + <title>Apache Tamaya - Extension: Integration with Apache Camel</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0"/> + <meta name="description" content=""/> + <meta name="author" content=""/> + <meta name="keywords" content=""/> + <meta name="generator" content="'JBake '+'${version}"/> + + <!-- Le styles --> + <link href="../../css/bootstrap.min.css" rel="stylesheet"/> + <link href="../../css/asciidoctor.css" rel="stylesheet"/> + <link href="../../css/base.css" rel="stylesheet"/> + <link href="../../css/prettify.css" rel="stylesheet"/> + + <!-- HTML5 shim, for IE6-8 support of HTML5 elements --> + <!--[if lt IE 9]> + <script src="../../js/html5shiv.min.js"></script> + <![endif]--> + + <!-- Fav and touch icons from ASF --> + <link rel="shortcut icon" href="../../favicon.ico"/> + <link rel="apple-touch-icon" sizes="57x57" href="../../favicons/apple-touch-icon-57x57.png"/> + <link rel="apple-touch-icon" sizes="60x60" href="../../favicons/apple-touch-icon-60x60.png"/> + <link rel="apple-touch-icon" sizes="72x72" href="../../favicons/apple-touch-icon-72x72.png"/> + <link rel="apple-touch-icon" sizes="76x76" href="../../favicons/apple-touch-icon-76x76.png"/> + <link rel="apple-touch-icon" sizes="114x114" href="../../favicons/apple-touch-icon-114x114.png"/> + <link rel="apple-touch-icon" sizes="120x120" href="../../favicons/apple-touch-icon-120x120.png"/> + <link rel="apple-touch-icon" sizes="144x144" href="../../favicons/apple-touch-icon-144x144.png"/> + <link rel="apple-touch-icon" sizes="152x152" href="../../favicons/apple-touch-icon-152x152.png"/> + <link rel="apple-touch-icon" sizes="180x180" href="../../favicons/apple-touch-icon-180x180.png"/> + <link rel="icon" type="image/png" href="../../favicons/favicon-32x32.png" sizes="32x32"/> + <link rel="icon" type="image/png" href="../../favicons/favicon-194x194.png" sizes="194x194"/> + <link rel="icon" type="image/png" href="../../favicons/favicon-96x96.png" sizes="96x96"/> + <link rel="icon" type="image/png" href="../../favicons/android-chrome-192x192.png" sizes="192x192"/> + <link rel="icon" type="image/png" href="../../favicons/favicon-16x16.png" sizes="16x16"/> + <link rel="manifest" href="../../favicons/manifest.json"/> + <link rel="shortcut icon" href="../../favicons/favicon.ico"/> + <meta name="msapplication-TileColor" content="#603cba"/> + <meta name="msapplication-TileImage" content="../../favicons/mstile-144x144.png"/> + <meta name="msapplication-config" content="../../favicons/browserconfig.xml"/> + <meta name="theme-color" content="#303284"/> + </head> + <body onload="prettyPrint()"> + <div id="wrap"> + <div> + + <!-- Fixed navbar --> + <div class="navbar navbar-default navbar-fixed-top" role="navigation"> + <div class="container"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="../../index.html">Apache Tamaya (incubating)</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + <li><a href="../../start.html">Tamaya in 5 minutes</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="../../documentation/usecases.html">Use Cases and Requirements</a></li> + <li><a href="../../documentation/quickstart.html">Quickstart</a></li> + <li><a href="../../documentation/api.html">API</a></li> + <li><a href="../../documentation/core.html">Core</a></li> + <li><a href="../../documentation/extensions.html">Extension Guide</a></li> + <li class="divider"></li> + <li><a href="../../apidocs/stable/index.html">Javadoc 0.3-incubating (release/stable)</a></li> + <li><a href="../../apidocs/development/index.html">Javadoc 0.4-incubating-SNAPSHOT (development)</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Development <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="../../development/source.html">Sources</a></li> + <li><a href="../../development/community.html">Community</a></li> + <li><a href="../../development/team.html">Project Team</a></li> + <li><a target="_blank" href="https://builds.apache.org/view/S-Z/view/Tamaya/";>CI / ASF Jenkins</a></li> + <li><a target="_blank" href="https://issues.apache.org/jira/browse/TAMAYA";>Issues / ASF Jira</a></li> + <li><a href="../../devguide.html">Development Guide</a></li> + <li><a href="../../release-guide.html">Release Guide</a></li> + <li class="divider"></li> + <li><a href="../../development/possible-contributions.html">Possible Contributions</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Releases <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="../../download.html">Download</a></li> + <li><a href="../../history.html">Release History</a></li> + </ul> + </li> +<!-- Example: + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Dropdown <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="#">Action</a></li> + <li><a href="#">Another action</a></li> + <li><a href="#">Something else here</a></li> + <li class="divider"></li> + <li class="dropdown-header">Nav header</li> + <li><a href="#">Separated link</a></li> + <li><a href="#">One more separated link</a></li> + </ul> + </li> +--> + <li><a href="../../sitemap.xml">Sitemap</a></li> + <li><a href="../../feed.xml">Subscribe</a></li> + </ul> + </div><!--/.nav-collapse --> + </div> + </div> + + </div> + <div class="container"> + + <div class="page-header"> + <h1>Apache Tamaya - Extension: Integration with Apache Camel</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="Camel">Integration with Apache Camel (Extension Module)</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Tamaya <em>Camel</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>The Tamaya <em>Camel</em> module provides different artifacts which allows integration of Apachae Tamaya +configuration with Apache Camel.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_compatibility">Compatibility</h3> +<div class="paragraph"> +<p>The module is based on Java 8, so it will not run on Java 8 and beyond.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_installation">Installation</h3> +<div class="paragraph"> +<p>To benefit from configuration builder 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-camel</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>Tamaya Camel comes basically with three artifacts:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>A Camel ResolverFunction implementation adding explicit property resolution +(org.apache.tamaya.camel.TamayaPropertyResolver).</p> +</li> +<li> +<p>A Camel PropertiesComponent implementation, which allows implicitly preconfigures the resolvers from above and +additionally allows using Tamaya configuration as Camel <em>overrides</em> +(org.apache.tamaya.camel.TamayaPropertiesComponent).</p> +</li> +</ul> +</div> +</div> +<div class="sect2"> +<h3 id="_configuring_using_camel_java_dsl">Configuring using Camel Java DSL</h3> +<div class="paragraph"> +<p>Camel integration using Java DSL is basically simple:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="prettyprint highlight"><code class="language-java" data-lang="java">import org.apache.tamaya.camel.TamayaPropertiesComponent; + +camelContext.addComponent("properties", new TamayaPropertiesComponent());</code></pre> +</div> +</div> +<div class="paragraph"> +<p>Given so you can then use cfg or tamaya as prefix for resolving entries with Tamaya as follows:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="prettyprint highlight"><code class="language-java" data-lang="java">RouteBuilder builder = new RouteBuilder() { + public void configure() { + from("direct:hello1").transform().simple("{{cfg:message}}"); + } +}; +camelContext.addRoutes(builder); +builder = new RouteBuilder() { + public void configure() { + from("direct:hello2").transform().simple("{{tamaya:message}}"); + } +}; +camelContext.addRoutes(builder);</code></pre> +</div> +</div> +<div class="paragraph"> +<p>Optionally you can also configure TamayaPropertiesComponent that all currently known Tamaya properties are used +as Camel overrides, meaning they are evaluated prior to all other available resolver functions in the Camel +PropertiesComponent:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="prettyprint highlight"><code class="language-java" data-lang="java">TamayaPropertiesComponent props = new TamayaPropertiesComponent(); +props.setTamayaOverrides(true);</code></pre> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_configuring_using_camel_xml_dsl">Configuring using Camel XML DSL</h3> +<div class="paragraph"> +<p>Camel integration using XML DSL is basically very similar. You just have to add the properties component as bean +as well. All other configuration parameters (e.g. file URIs are similar supported). In the example code below we +again use Tamaya as the main configuration solutions only using Camel’s default behaviour as a fallback:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><beans xmlns="http://www.springframework.org/schema/beans"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd + "> + + <routeContext id="myCoolRoutes" xmlns="http://camel.apache.org/schema/spring"> + <route id="r1"> + <from uri="direct:hello1"/> + <transform> + <simple>{{message}}</simple> + </transform> + </route> + <route id="r2"> + <from uri="direct:hello2"/> + <transform> + <simple>{{cfg:message}}</simple> + </transform> + </route> + <route id="r3"> + <from uri="direct:hello3"/> + <transform> + <simple>{{tamaya:message}}</simple> + </transform> + </route> + </routeContext> + + <bean id="properties" class="org.apache.tamaya.camel.TamayaPropertiesComponent"> + <property name="tamayaOverrides" value="true"/> + </bean> + +</beans></code></pre> +</div> +</div> +</div> +</div> +</div></p> + + <hr /> + </div> + </div> + <div> + <div id="push"></div> + + <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-04-26</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> + <b>Disclaimer</b> + Apache Tamaya (incubating) is an effort undergoing + incubation at + The Apache Software Foundation (ASF), sponsored by + the name of Apache Incubator. Incubation is required of + all newly accepted projects until a further review indicates + that the infrastructure, communications, and decision making + process have stabilized in a manner consistent with other + successful ASF projects. While incubation status is not + necessarily a reflection of the completeness or stability of + the code, it does indicate that the project has yet to + be fully endorsed by the ASF. + Apache, Apache Tamaya, and the Apache Tamaya logo are registered trademarks or trademarks of The Apache Software Foundation in the U.S. and/or other countries.<br /> + <a href="https://incubator.apache.org/guides/website.html"; style="border:0px;" target="_target"> + <img class="incubator-logo" src="../../logos/apache-incubator.png"/> + </a> + </p> + </div> + </div> + + <!-- Le javascript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="../../js/jquery-1.11.1.min.js"></script> + <script src="../../js/bootstrap.min.js"></script> + <script src="../../js/prettify.js"></script> + </div> + </body> +</html>
