blob: 0dc35e7fa91ed7679b42196665189a57b931d858 [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="Homepage of Apache Tamaya (incubating)"/>
<meta name="author" content="Apache Tamaya Project Team"/>
<meta name="keywords" content="Apache Tamaya Incubating, configuration, Java, ASF, Apache Software Foundation"/>
<meta name="generator" content="JBake ${content.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">Tamaya Home</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.4-incubating (release/stable)</a></li>
<li><a href="apidocs/development/index.html">Javadoc 0.5-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>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://www.apache.org/">Apache Software Foundation (ASF)</a></li>
<li><a href="https://www.apache.org/foundation/how-it-works.html">How the ASF works</a></li>
<li><a href="https://www.apache.org/foundation/getinvolved.html">Get Involved</a></li>
<li><a href="https://www.apache.org/dev/">Developer Resources</a></li>
<li><a href="https://www.apache.org/foundation/policies/conduct.html">Code of Conduct</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="https://www.apache.org/licenses/">License</a></li>
<li><a href="https://www.apache.org/security">Security</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
<hr/>
<li><a href="https://www.apache.org/events/current-event.html"><img src="https://www.apache.org/events/current-event-125x125.png" alt="Current Apache event"/></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>
<li><a href="https://incubator.apache.org/guides/website.html" style="border:0px;" target="_target">
<img class="incubator-logo" src="logos/apache-incubator.png"/></a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<div class="container">
<div class="page-header">
<h1></h1>
</div>
<p><em>2019-11-17</em></p>
<p><div class="sect1">
<h2 id="_the_tamaya_high_level_design">The Tamaya High Level Design</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required
that build the base of all the other mechanisms:</p>
</div>
<div class="paragraph">
<p>The <strong>API</strong> (package org.apache.tamaya) provides</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A simple but complete SE <strong>API</strong> for accessing key/value based <em>Configuration</em>:</p>
<div class="ulist">
<ul>
<li>
<p>Configuration hereby models configuration, the main interface of Tamaya, providing key/value pairs as raw
(String-based) key/value pairs, allowing also access to typed values.</p>
</li>
<li>
<p>ConfigurationProvider provides the static entry point for accessing configuration.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>The <strong>SPI</strong> (package org.apache.tamaya.spi) provides:
<strong> A simple minimalistic model for configuration data, called <em>PropertySource</em>.
</strong> Several extension points for adding additional configuration property sources or adapting the internal workings
of the overall system.
** A ServiceContext / ServiceContextManager that controls the loading of the components in Tamaya. This allows to
adapt the behaviour depending on the runtime environment in use, e.g. a Java standalone application, an OSGi
container or a Java EE application server.</p>
</div>
<div class="paragraph">
<p>Tamaya <strong>Modules</strong> finally allow to add additional functionality to customize your configuration solution with the
functionality you want. E.g. modules are providing features such as</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Configuration <em>injection</em></p>
</li>
<li>
<p><em>Dynamic placeholders</em> and resolution mechanism for configuration values</p>
</li>
<li>
<p>Abstractions for reusable <em>configuration formats</em></p>
</li>
<li>
<p>Dynamic configuration updates and change events</p>
</li>
<li>
<p>Support for OSGi/Java EE Classloading</p>
</li>
<li>
<p>A configuration server/client</p>
</li>
<li>
<p>and more&#8230;&#8203;</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_how_tamaya_organizes_configuration">How Tamaya organizes Configuration</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_overview">Overview</h3>
<div class="paragraph">
<p>All the mentioned artifacts are used to organize configuration in a higly flexible and extendable way. Hereby the
PropertySource is the key artifact. In general Tamaya organizes Configuration as follows:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../images/CoreDesign.png" alt="CoreDesign">
</div>
</div>
<div class="paragraph">
<p>Key abstraction hereby is the ConfigurationContext, which basically</p>
</div>
<div class="ulist">
<ul>
<li>
<p>an ordered chain of PropertySource instances. This chain is used to evaluate raw configuration values.</p>
</li>
<li>
<p>a set of PropertyFilter instances that filter the raw values evaluated from the property source chain.</p>
</li>
<li>
<p>a set of PropertyConverter that convert String values into typed values when needed.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In most standalone use cases only one ConfigurationContext will be active at a time. But in more complex scenarios,
such as Java EE also multiple contexts could be active that are active depending on the current runtime context
(e.g. attached to the corresponding classloader(s)). These aspects are basically handled by the
ConfigurationProvider and its corresponding SPIs.</p>
</div>
</div>
<div class="sect2">
<h3 id="_loading_the_current_configurationcontext">Loading the current <em>ConfigurationContext</em></h3>
<div class="paragraph">
<p>The ConfigurationContext is the core of Tamaya. It manages all configuration sources and additional components
required to evaluate a concrete configuration value:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Tamaya loads all available PropertySource instances. Hereby PropertySource instances can be</p>
<div class="ulist">
<ul>
<li>
<p>Directly registered (using the mechanism defined by the current ServiceContext implementation, by default
the Java ServiceLoader.</p>
</li>
<li>
<p>Provided by a registered instance of PropertySourceProvider.</p>
</li>
</ul>
</div>
</li>
<li>
<p>All loaded property sources are <em>ordered based on each ordinal</em>, returned from PropertySource.getOrdinal() as
an ordered chain of PropertySources, building up the ordered chain of PropertySource instances used for raw
configuration value evaluation.</p>
</li>
<li>
<p>Tamaya loads all available PropertyFilter instances. Hereby PropertyFilter instances can be registered
by default using the Java ServiceLoader API. The PropertyFilter instances loaded are ordered based on the
@Priority annotations found on each filter. If no priority annotation is present, 0 is assumed.</p>
</li>
<li>
<p>Tamaya loads all available PropertyConverter instances. Hereby PropertyConverter instances can be registered
by default using the Java ServiceLoader API. The PropertyConverter instances loaded are ordered based on the
@Priority annotations found on each filter. If no priority annotation is present, 0 is assumed. It is
possible to register multiple converters for the same target type.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_evaluating_raw_property_values">Evaluating raw property values</h3>
<div class="paragraph">
<p>When evaluating a concrete configuration value for a given key, Tamaya iterates through this chain of registered
PropertySources. Hereby the final value, by default, is determined by the last non-null value returned from a
PropertySource.</p>
</div>
<div class="paragraph">
<p>Since the ladder may not always be appropriate, e.g. when values should be combined instead of overridden, a
instance of PropertyConverter actually has access to all values returned. This enables more complex value
evaluation algorithms, when needed.</p>
</div>
<div class="paragraph">
<p>Access to the complete configuration Map is performing the same resolution algorithm, but for all
key/value pairs available.</p>
</div>
</div>
<div class="sect2">
<h3 id="_filtering_the_raw_properties">Filtering the raw properties:</h3>
<div class="paragraph">
<p>Each raw configuration value evaluated is filtered by the ordered filter chain, as long as there are any changes
applied by any of the filters called. This ensures that also transitive replacements by filters are possible.
If, after a configurable number of evaluation loops still values are changes during each loop, the filtering
process is aborted, since a non-resolvable circular filter issue is assumed.</p>
</div>
<div class="paragraph">
<p>The output is the final configuration value as type String.</p>
</div>
</div>
<div class="sect2">
<h3 id="_applying_type_conversion">Applying type conversion:</h3>
<div class="paragraph">
<p>Finally, if the required target type, does not match Java.ui.lang.String, all registered PropertyConverter
instances targeting the corresponding target type are asked to convert the given (String-based) configuration
entry to the required (non String) target type.</p>
</div>
<div class="paragraph">
<p>Hereby the first <em>non-null</em> value returned by a PropertyConverter is used as the final typed configuration value and
returned to the caller.</p>
</div>
</div>
<div class="sect2">
<h3 id="_advanced_features">Advanced Features</h3>
<div class="paragraph">
<p>Basically the bahaviour of Tamaya can be customized using the following mechanisms. Basically configuration can be
provided using the following mechanism:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Registering additional PropertySource instances. Depending on their <em>ordinal value</em> they
will override or extend existing configuration.</p>
</li>
<li>
<p>Registering additional PropertySourceProvider instances, to provide multiple PropertySource
instances.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Additionally Tamaya provides hooks for further adapting the internal workings:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Adding additional support for new target types configurable by registering additional PropertyConverter
instances. This can be used for adding support for new types as well as for adding support for additional
formats.</p>
</li>
<li>
<p>Complex extensions may adapt the complete ConfigurationContext.</p>
</li>
<li>
<p>Registering additional PropertyFilter instances, that filter the configuration values extracted.</p>
</li>
<li>
<p>Registering an alternate ServiceContext to support alternate runtime containers, e.g. a CDI container.</p>
</li>
<li>
<p>A combination of all above.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Additionally instances of ConfigOperator, ConfigQuery can be implemented that provide additional functionality.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_component_loading">Component Loading</h2>
<div class="sectionbody">
<div class="paragraph">
<p>As mentioned the component loading of Tamaya can be adapted. By default the JDK ServiceLoader API is used to determine
a ServiceContext implementation that should control
Tamaya&#8217;s overall component loading. If not found, a default implementation is registered, which relies on the
Java hava.util.ServiceLoader mechanism. This behaviour can be changed by implementing your own version
of the ServiceContext interface, annotating it with a @Priority annotation and registering it using the
java.util.ServiceLoader mechanism.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_compatibility">Compatibility</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The Tamaya API is compatible with Java 8 and beyond.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_further_documentation">Further Documentation</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Being here we recommend to have a look at the more detailed documentation of Tamaya&#8217;s <a href="documentation/api.html">API and SPI</a>,
and of its current available <a href="documentation/extensions.html">modules</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>2019</span> Apache Software Foundation | Mixed with <a href="https://getbootstrap.com/">Bootstrap v3.1.1</a>
| Baked with <a href="https://jbake.org">JBake <span>v2.6.4</span></a>
at <span>2019-11-17</span> |
<a class="twitter-follow-button" data-show-count="false" href="https://twitter.com/tamayaconf">Follow @tamayaconf</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
</p>
<p>
<b>Disclaimer</b>
Apache Tamaya (incubating) is an effort undergoing
incubation at
The Apache Software Foundation (ASF), sponsored by
the 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>