Google Git
Sign in
apache / incubator-retired-tamaya-site / refs/heads/asf-site / . / documentation-new / core.html
blob: b7667ebbc2be54a6a057c06e1c97e914ba6dcb21 [file] [log] [blame]
<!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-09-06</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">&lt;fully qualified class name&gt;</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">&lt;Enum item name&gt;</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">&lt;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">&lt;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">&lt;LocalDateTime as defined by LocalDateTime.parse(String)&gt;</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/&lt;myInterfaceName&gt; 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>
<tbody>
<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>
</tbody>
</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&lt;ConfigSource&gt; 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&lt;ConfigSource&gt;). 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>
<tbody>
<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>
</tbody>
</table>
</div>
<div class="admonitionblock note">
<table>
<tbody>
<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>
</tbody>
</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&lt;String, String&gt; 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 &lt;b&gt;raw&lt;/b&gt;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&lt;ConfigValue&gt; 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&lt;String,String&gt; 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&lt;String,String&gt; 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">&copy; 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.6.1</span></a>
at <span>2018-11-02</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.<br />
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" style="height: 50px;"/>
</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>