| <!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…​</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’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’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">© 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> |