| <!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="_apache_tamaya_quickstart">Apache Tamaya: Quickstart</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The fastest way to start with Tamaya is just using the <em>Core</em> implementation, implementing the <strong>Config JSR API</strong> in a minimalistic way. For that add the following Maven dependency to your project:</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_adding_the_tamaya_dependency">Adding the Tamaya Dependency</h3> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> |
| <groupId>org.apache.tamaya</groupId> |
| <artifactId>tamaya-core</artifactId> |
| <version>0.4-incubating-SNAPSHOT</version> |
| </dependency></code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_start_coding">Start Coding</h3> |
| <div class="paragraph"> |
| <p>In your Java code you can directly access configuration from the API. In most cases it is recommended to provide the default values when accessing the configuration:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code class="language-java" data-lang="java">Configuration config = ConfigProvider.getConfig(); |
| |
| String aTextValue = config.getOptionalValue("my.value.key", String.class).orElse("N/A"); |
| int aNumericValue = config.getOptionalValue("my.numValueKey", Integer.class).orElse(15 /* default */); |
| BigDecimal bdValue = config.getOptionalValue("my.BD.value", BigDecimal.class).orElse(BigDecimal.valueOf(120));</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_add_define_your_configuration_data">Add/define your configuration data</h3> |
| <div class="paragraph"> |
| <p>As seen you can immedeatly start working with your configuration backend, without adding any kind of default configuration. Nevertheless the <em>core</em> implementation also comes with a <em>default</em> mechanism, where you can store your configuration as .properties in your classpath:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code>META-INF/javaconfig.properties</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Additionally also system properties are taken into account, hereby overriding the <em>default</em> properties. Overall Tamaya by default defines the following configuration model per default (most significant first):</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> <p>Environment Properties</p> </li> |
| <li> <p>System Properties</p> </li> |
| <li> <p><code>META-INF/javaconfig.properties</code></p> </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_advanced_topics">Advanced Topics</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="_multiple_configuration_files">Multiple configuration files</h3> |
| <div class="paragraph"> |
| <p>By default you can provide multiple <code>javaconfig.properties</code> files, e.g. as part of multiple jars loaded into your system. The system creates one <code>ConfigSource</code> for each file found on the classpath. All <code>ConfigSource</code> instances created are ordered by their precedence.</p> |
| </div> |
| <div class="paragraph"> |
| <p>By default the precendence of a ConfigSource is evaluated based on an <em>ordinal</em> value calculated as follows:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> <p>the systems checks for a <code>config.ordinal</code> configuration value and tries to convert to an <code>int</code> ordinal value.</p> </li> |
| <li> <p>the systems checks if the config source has a method int getOrdinal(). If present the result is used as ordinal.</p> </li> |
| <li> <p>the systems checks if the config source has a <code>@Priority</code> annotation and uses the annotation’s value as ordinal.</p> </li> |
| <li> <p>if all of the above fails, 0 is assumed as ordinal.</p> </li> |
| </ol> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tbody> |
| <tr> |
| <td class="icon"> |
| <div class="title"> |
| Note |
| </div> </td> |
| <td class="content"> Since evaluation of the <code>config.ordinal</code> is always done first, it is possible to change the ordinal value by adding a corresponding configuration entry to a config source. </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Tamaya Core uses the following default ordinals (see also the ConfigJSR spec):</p> |
| </div> |
| <table class="tableblock frame-all grid-all" style="width: 70%;"> |
| <colgroup> |
| <col style="width: 75%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Source</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Ordinal</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">400</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">300</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Properties from <code>META-INF/javaconfig.properties</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">100</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>That means that the value of a configuration variable <code>x</code> passed as <code>-Dx=yes</code> has a higher precedence then the entry for configuration variable <code>x</code> specified in <code>META-INF/javaconfig.properties</code> as <code>x=no</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These ordinal values can be either hardcoded, or be dynamically configurable as key within each configuration resource. The ladder can be done by defining a special Tamaya ordinal value as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code># override default ordinal for property files |
| config.ordinal=123</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This assigns an ordinal of 123 to each entry in that config source providing this configuration properties.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_using_additional_features_of_tamaya">Using additional features of Tamaya</h3> |
| <div class="paragraph"> |
| <p>There many modules that extend the capabilities of Tamaya and the ConfigJSR. These modules doe not depend on core, so alternative implementations of the Tamaya API should work similarly. Following a small extract of most important modules available. Refer to <a href="extensions/extensions.html">this list</a> for a complete overview.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_dynamic_resolution_and_value_placeholders">Dynamic Resolution and Value Placeholders</h4> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> |
| <artifactId>org.apache.tamaya.ext</id> |
| <artifactId>tamaya-resolver</artifactId> |
| <version>0.4-incubating-SNAPSHOT</version> |
| </dependency></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>With that it is possible to define values with Unix styled placeholders that are resolved on configuration access, e.g. <code>mykey=my${dynamicValue}´. For further details refer to the module documentation. This module also provides a `Resolver</code> singleton:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code class="language-java" data-lang="java">String myExpression = ...; |
| String resolved = Resolver.evaluateExpression(myExpression);</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_ant_styled_path_resolution_of_resources">Ant-styled Path Resolution of Resources</h4> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> |
| <artifactId>org.apache.tamaya.ext</id> |
| <artifactId>tamaya-resolution</artifactId> |
| <version>0.4-incubating-SNAPSHOT</version> |
| </dependency></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This module provides a <code>Resolver</code> singleton that allows to resolve configuration resources using a ant-styled resource description, e.g.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml">Collection<URL> urls = ResourceResolver.getResources("META-INF/cfg/**/*.properties");</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For further details refer to the module documentation.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configuration_injection">Configuration Injection</h4> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml"><dependency> |
| <artifactId>org.apache.tamaya.ext</id> |
| <artifactId>tamaya-inject</artifactId> |
| <version>{tamaya_version_development}</version> |
| </dependency></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>With this extension you can let Tamaya inject configuration into instances of annotated classes or let Tamaya implement a configuration template.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Corresponding configuration:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml">public class MyType { |
| @Config("my.key") |
| private String typeName; |
| |
| public String getName() { |
| return name; |
| } |
| } |
| |
| MyType type = new MyType(); |
| ConfigurationInjector.configure(type);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Or the same as template:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code class="language-xml" data-lang="xml">public interface MyTypeTemplate { |
| @Config("my.key") |
| public String getName(); |
| } |
| |
| MyTypeTemplate type = ConfigurationInjector.createTemplate(MyTypeTemplate.class);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Currently the following resolvers are available:</p> |
| </div> |
| <table class="tableblock frame-all grid-all" style="width: 60%;"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 80%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Conf</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Cross-reference to another configuration entry</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">URL</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Referencing a resource addressable by an URL.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">File</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Reference to a file, replacing the expression with the file’s text value.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Resource</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Reference to classpath resource, replacing the expression with the resource’s text value.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </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.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> |
