http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/4f4912e5/documentation/api.html ---------------------------------------------------------------------- diff --cc documentation/api.html index 52cbd8e,3e52494..0000000 deleted file mode 100644,100644 --- a/documentation/api.html +++ /dev/null @@@ -1,1141 -1,1141 +1,0 @@@ --<!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> - <a class="navbar-brand" href="../">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><a href="../index.html">Home</a></li> - <li><a href="../about.html">About</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/index.html">Javadoc {tamaya_version} (external)</a></li> - <li><a href="../apidocs/index.html">Javadoc ${tamaya_version} (external)</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>2016-12-19</em></p> -- -- <p><div class="sect1"> --<h2 id="CoreDesign">Apache Tamaya: API</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 are the base of all the other mechanisms. As a starting point we recommend you read the corresponding - l<a href="highleveldesign.html">High Level Design Documentation</a></p> -l<a href="HighLevelDesign.html">High Level Design Documentation</a></p> --</div> --</div> --</div> --<div class="sect1"> --<h2 id="API">The Tamaya API</h2> --<div class="sectionbody"> --<div class="paragraph"> - <p>The API provides the artifacts as described in the <a href="highleveldesign.html">High Level Design Documentation</a>, which are:</p> -<p>The API provides the artifacts as described in the <a href="HighLevelDesign.html">High Level Design Documentation</a>, which are:</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. Configuration provides</p> --<div class="ulist"> --<ul> --<li> --<p>access to literal key/value pairs.</p> --</li> --<li> --<p>functional extension points (with, query) using a unary ConfigOperator or --a function ConfigurationQuery<T>.</p> --</li> --</ul> --</div> --</li> --<li> --<p>ConfigurationProvider provides with getConfiguration() the static entry point for accessing configuration.</p> --</li> --<li> --<p>ConfigException defines a runtime exception for usage by the configuration system.</p> --</li> --<li> --<p>TypeLiteral provides a possibility to type safely define the target type to be returned by a registered --PropertyProvider.</p> --</li> --<li> --<p>PropertyConverter, which defines conversion of configuration values (String) into any required target type.</p> --</li> --</ul> --</div> --</li> --<li> --<p>Additionally the <strong>SPI</strong> provides:</p> --<div class="ulist"> --<ul> --<li> --<p><em>PropertySource:</em> is the the SPI for adding configuration data. A PropertySource hereby</p> --<div class="ulist"> --<ul> --<li> --<p>is designed as a minimalistic interface that be implemented by any kind of data provider (local or remote)</p> --</li> --<li> --<p>provides single access for key/value pairs in raw format as String key/values only (getPropertyValue).</p> --</li> --<li> --<p>can optionally support scanning of its provided values, implementing getProperties().</p> --</li> --</ul> --</div> --</li> --<li> --<p><em>PropertySourceProvider:</em> allows to register multiple property sources dynamically, e.g. all config files found in --file system folder..</p> --</li> --<li> --<p>ConfigurationProviderSpi defines the SPI that is used as a backing bean for the ConfigurationProvider --singleton.</p> --</li> --<li> --<p>PropertyFilter, which allows filtering of property values prior getting returned to the caller.</p> --</li> --<li> --<p>PropertyValueCombinationPolicy optionally can be registered to change the way how different key/value --pairs are combined to build up the final Configuration passed over to the filters registered.</p> --</li> --<li> --<p>ConfigurationContext, which provides a container for all the artifacts needed to build up a Configuration. --For example a context contains the property sources, property filters, converters and combination policy used. --Also the ordering of the property sources is defined by the context. A context instance given a --Configuration can be created by calling ConfigurationProvider.createConfiguration(context);.</p> --</li> --<li> --<p>Similarly a ConfigurationContext can be created using a ConfigurationContextBuilder. This builder can be --obtained calling ConfigurationProvider.getConfigurationContextBuilder();.</p> --</li> --<li> --<p>ServiceContext, which provides access to the components loaded, depending on the current runtime stack.</p> --</li> --<li> --<p>ServiceContextManager provides static access to the ServiceContext loaded.</p> --</li> --</ul> --</div> --</li> --</ul> --</div> --<div class="paragraph"> --<p>This is also reflected in the main packages of the API:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>org.apache.tamaya contains the main API abstractions used by users.</p> --</li> --<li> --<p>org.apache.tamaya.spi contains the SPI interfaces to be implemented by implementations and the ServiceContext --mechanism.</p> --</li> --</ul> --</div> --<div class="sect2"> --<h3 id="APIKeyValues">Key/Value Pairs</h3> --<div class="paragraph"> --<p>Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple --and most commonly used approach are simple literal key/value pairs. So the core building block of {name} are key/value pairs. --You can think of a common .properties file, e.g.</p> --</div> --<div class="listingblock"> --<div class="title">A simple properties file</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-properties" data-lang="properties">a.b.c=cVal --a.b.c.1=cVal1 --a.b.c.2=cVal2 --a=aVal --a.b=abVal --a.b2=abVal</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Now you can use java.util.Properties to read this file and access the corresponding properties, e.g.</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-properties" data-lang="properties">Properties props = new Properties(); --props.readProperties(...); --String val = props.getProperty("a.b.c"); --val = props.getProperty("a.b.c.1"); --...</code></pre> --</div> --</div> --<div class="sect3"> --<h4 id="_why_using_strings_only">Why Using Strings Only</h4> --<div class="paragraph"> --<p>There are good reason to keep of non String-values as core storage representation of configuration. Mostly --there are several huge advantages:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>Strings are simple to understand</p> --</li> --<li> --<p>Strings are human readable and therefore easy to prove for correctness</p> --</li> --<li> --<p>Strings can easily be used within different language, different VMs, files or network communications.</p> --</li> --<li> --<p>Strings can easily be compared and manipulated</p> --</li> --<li> --<p>Strings can easily be searched, indexed and cached</p> --</li> --<li> --<p>It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in --production as well in testing.</p> --</li> --<li> --<p>and more…​</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>On the other side there are also disadvantages:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>Strings are inherently not type safe, they do not provide validation out of the box for special types, such as --numbers, dates etc.</p> --</li> --<li> --<p>In many cases you want to access configuration in a typesafe way avoiding conversion to the target types explicitly --throughout your code.</p> --</li> --<li> --<p>Strings are neither hierarchical nor multi-valued, so mapping hierarchical and collection structures requires some --extra efforts.</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>Nevertheless most of these advantages can be mitigated easily, hereby still keeping all the benefits from above:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>Adding type safe adapters on top of String allow to add any type easily, that can be directly mapped out of Strings. --This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more.</p> --</li> --<li> --<p>Also multi-valued, complex and collection types can be defined as a corresponding PropertyAdapter knows how to --parse and create the target instance required.</p> --</li> --<li> --<p>String s also can be used as references pointing to other locations and formats, where configuration is --accessible.</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>[[API Configuration]] --=== Configuration</p> --</div> --<div class="paragraph"> --<p>Configuration is the main API provided by Tamaya. It allows reading of single property values or the whole --property map, but also supports type safe access:</p> --</div> --<div class="listingblock"> --<div class="title">Interface Configuration</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface Configuration{ -- String get(String key); -- String getOrDefault(String key, String value); -- <T> T get(String key, Class<T> type); -- <T> T getOrDefault(String key, Class<T> type, T defaultValue); -- <T> T get(String key, TypeLiteral<T> type); -- <T> T getOrDefault(String key, TypeLiteral<T> type, T defaultValue); -- Map<String,String> getProperties(); -- -- // extension points -- Configuration with(ConfigOperator operator); -- <T> T query(ConfigQuery<T> query); -- -- ConfigurationContext getContext(); --}</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Hereby</p> --</div> --<div class="ulist"> --<ul> --<li> --<p><T> T get(String, Class<T>) provides type safe accessors for all basic wrapper types of the JDK.</p> --</li> --<li> --<p>with, query provide the extension points for adding additional functionality.</p> --</li> --<li> --<p>getProperties() provides access to all key/values, whereas entries from non scannable property sources may not --be included.</p> --</li> --<li> --<p>getOrDefault allows to pass default values as needed, returned if the requested value evaluated to null.</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>The class TypeLiteral is basically similar to the same class provided with CDI:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public class TypeLiteral<T> implements Serializable { -- -- [...] -- -- protected TypeLiteral(Type type) { -- this.type = type; -- } -- -- protected TypeLiteral() { } -- -- public static <L> TypeLiteral<L> of(Type type){...} -- public static <L> TypeLiteral<L> of(Class<L> type){...} -- -- public final Type getType() {...} -- public final Class<T> getRawType() {...} -- -- public static Type getGenericInterfaceTypeParameter(Class<?> clazz, Class<?> interfaceType){...} -- public static Type getTypeParameter(Class<?> clazz, Class<?> interfaceType){...} -- -- [...] --}</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Instances of Configuration can be accessed from the ConfigurationProvider singleton:</p> --</div> --<div class="listingblock"> --<div class="title">Accessing Configuration</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">Configuration config = ConfigurationProvider.getConfiguration();</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Hereby the singleton is backed up by an instance of ConfigurationProviderSpi.</p> --</div> --</div> --<div class="sect3"> --<h4 id="PropertyConverter">Property Type Conversion</h4> --<div class="paragraph"> --<p>As illustrated in the previous section, Configuration also to access non String types. Nevertheless internally --all properties are strictly modelled as pure Strings only, so non String types must be derived by converting the --configured String values into the required target type. This is achieved with the help of PropertyConverters:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface PropertyConverter<T>{ -- T convert(String value, ConversionContext context); -- //X TODO Collection<String> getSupportedFormats(); --}</code></pre> --</div> --</div> --<div class="paragraph"> --<p>The ConversionContext contains additional meta-information for the accessed key, inclusing the key’a name and --additional metadata.</p> --</div> --<div class="paragraph"> --<p>PropertyConverter instances can be implemented and registered by default using the ServiceLoader. Hereby --a configuration String value is passed to all registered converters for a type in order of their annotated @Priority --value. The first non-null result of a converter is then returned as the current configuration value.</p> --</div> --<div class="paragraph"> --<p>Access to converters is provided by the current ConfigurationContext, which is accessible from --the ConfigurationProvider singleton.</p> --</div> --</div> --</div> --<div class="sect2"> --<h3 id="ExtensionPoints">Extension Points</h3> --<div class="paragraph"> --<p>We are well aware of the fact that this library will not be able to cover all kinds of use cases. Therefore --we have added functional extension mechanisms to Configuration that were used in other areas of the Java eco-system --as well:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>with(ConfigOperator operator) allows to pass arbitrary unary functions that take and return instances of --Configuration. Operators can be used to cover use cases such as filtering, configuration views, security --interception and more.</p> --</li> --<li> --<p>query(ConfigQuery query) allows to apply a function returning any kind of result based on a --Configuration instance. Queries are used for accessing/deriving any kind of data based on of a Configuration --instance, e.g. accessing a Set<String> of root keys present.</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>Both interfaces hereby are functional interfaces. Because of backward compatibility with Java 7 we did not use --UnaryOperator and Function from the java.util.function package. Nevertheless usage is similar, so you can --use Lambdas and method references in Java 8:</p> --</div> --<div class="listingblock"> --<div class="title">Applying a ConfigurationQuery using a method reference</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ConfigSecurity securityContext = ConfigurationProvider.getConfiguration().query(ConfigSecurity::targetSecurityContext);</code></pre> --</div> --</div> --<div class="admonitionblock note"> --<table> --<tr> --<td class="icon"> --<div class="title">Note</div> --</td> --<td class="content"> --ConfigSecurity is an arbitrary class only for demonstration purposes. --</td> --</tr> --</table> --</div> --<div class="paragraph"> --<p>Operator calls basically look similar:</p> --</div> --<div class="listingblock"> --<div class="title">Applying a ConfigurationOperator using a lambda expression:</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">Configuration secured = ConfigurationProvider.getConfiguration() -- .with((config) -> -- config.get("foo")!=null?; -- FooFilter.apply(config): -- config);</code></pre> --</div> --</div> --</div> --<div class="sect2"> --<h3 id="ConfigException">ConfigException</h3> --<div class="paragraph"> --<p>The class ConfigException models the base <strong>runtime</strong> exception used by the configuration system.</p> --</div> --</div> --</div> --</div> --<div class="sect1"> --<h2 id="SPI">SPI</h2> --<div class="sectionbody"> --<div class="sect2"> --<h3 id="PropertySource">Interface PropertySource</h3> --<div class="paragraph"> --<p>We have seen that constraining configuration aspects to simple literal key/value pairs provides us with an easy to --understand, generic, flexible, yet expendable mechanism. Looking at the Java language features a java.util.Map<String, --String> and java.util.Properties basically model these aspects out of the box.</p> --</div> --<div class="paragraph"> --<p>Though there are advantages in using these types as a model, there are some severe drawbacks, notably implementation --of these types is far not trivial and the collection API offers additional functionality not useful when aiming --for modelling simple property sources.</p> --</div> --<div class="paragraph"> --<p>To render an implementation of a custom PropertySource as convenient as possible only the following methods were --identified to be necessary:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public interface PropertySource{ -- int getOrdinal(); -- String getName(); -- String get(String key); -- boolean isScannable(); -- Map<String, String> getProperties(); --}</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Hereby</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>get looks similar to the methods on Map. It may return null in case no such entry is available.</p> --</li> --<li> --<p>getProperties allows to extract all property data to a Map<String,String>. Other methods like containsKey, --keySet as well as streaming operations then can be applied on the returned Map instance.</p> --</li> --<li> --<p>But not in all scenarios a property source may be scannable, e.g. when looking up keys is very inefficient, it --may not make sense to iterator over all keys to collect the corresponding properties. --This can be evaluated by calling isScannable(). If a PropertySource is defined as non scannable accesses to --getProperties() may not return all key/value pairs that would be available when accessed directly using the --String get(String) method.</p> --</li> --<li> --<p>getOrdinal() defines the ordinal of the PropertySource. Property sources are managed in an ordered chain, where --property sources with higher ordinals override the ones with lower ordinals. If ordinal are the same, the natural --ordering of the fulloy qualified class names of the property source implementations are used. The reason for --not using @Priority annotations is that property sources can define dynamically their ordinals, e.g. based on --a property contained with the configuration itself.</p> --</li> --<li> --<p>Finally getName() returns a (unique) name that identifies the PropertySource within the current --ConfigurationContext.</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>This interface can be implemented by any kind of logic. It could be a simple in memory map, a distributed configuration --provided by a data grid, a database, the JNDI tree or other resources. Or it can be a combination of multiple --property sources with additional combination/aggregation rules in place.</p> --</div> --<div class="paragraph"> --<p>PropertySources are by default registered using the Java ServiceLoader or the mechanism provided by the current -- active ServiceContext.</p> --</div> --</div> --<div class="sect2"> --<h3 id="PropertySourceProvider">Interface PropertySourceProvider</h3> --<div class="paragraph"> --<p>Instances of this type can be used to register multiple instances of PropertySource.</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">// @FunctionalInterface in Java 8 --public interface PropertySourceProvider{ -- Collection<PropertySource> getPropertySources(); --}</code></pre> --</div> --</div> --<div class="paragraph"> --<p>This allows to evaluate the property sources to be read/that are available dynamically. All property sources --are read out and added to the current chain of PropertySource instances within the current ConfigurationContext, --refer also to <a id="ConfigurationContext"></a>.</p> --</div> --<div class="paragraph"> --<p>PropertySourceProviders are by default registered using the Java ServiceLoader or the mechanism provided by the --current active ServiceContext.</p> --</div> --</div> --<div class="sect2"> --<h3 id="PropertyFilter">Interface PropertyFilter</h3> --<div class="paragraph"> --<p>Also PropertyFilters can be added to a Configuration. They are evaluated before a Configuration instance is --passed to the user. Filters can hereby used for multiple purposes, such as</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>resolving placeholders</p> --</li> --<li> --<p>masking sensitive entries, such as passwords</p> --</li> --<li> --<p>constraining visibility based on the current active user</p> --</li> --<li> --<p>…​</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>PropertyFilters are by default registered using the Java ServiceLoader or the mechanism provided by the current --active ServiceContext. Similar to property sources they are managed in an ordered filter chain, based on the --applied @Priority annotations.</p> --</div> --<div class="paragraph"> --<p>A PropertyFilter is defined as follows:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">// Functional Interface --public interface PropertyFilter{ -- String filterProperty(String value, FilterContext context); --}</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Hereby:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>returning null will remove the key from the final result</p> --</li> --<li> --<p>non null values are used as the current value of the key. Nevertheless for resolving multi-step dependencies --filter evaluation has to be continued as long as filters are still changing some of the values to be returned. --To prevent possible endless loops after a defined number of loops evaluation is stopped.</p> --</li> --<li> --<p>FilterContext provides additional metdata, inclusing the key accessed, which is useful in many use cases.</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>This method is called each time a single entry is accessed, and for each property in a full properties result.</p> --</div> --<div class="sect3"> --<h4 id="PropertyValueCombinationPolicy">Interface PropertyValueCombinationPolicy</h4> --<div class="paragraph"> --<p>This interface can be implemented optional. It can be used to adapt the way how property key/value pairs are combined to --build up the final Configuration to be passed over to the PropertyFilters. The default implementation is just --overriding all values read before with the new value read. Nevertheless for collections and other use cases it is --often useful to have alternate combination policies in place, e.g. for combining values from previous sources with the --new value. Finally looking at the method’s signature it may be surprising to find a Map for the value. The basic --value hereby is defined by currentValue.get(key). Nevertheless the Map may also contain additional meta entries, --which may be considered by the policy implementation.</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">// FunctionalInterface --public interface PropertyValueCombinationPolicy{ -- -- PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR = -- new PropertyValueCombinationPolicy(){ -- @Override -- public Map<String,String> collect(Map<String,String> currentValue, String key, -- PropertySource propertySource) { -- PropertyValue value = propertySource.get(key); -- return value!=null?value.getConfigEntries():currentValue; -- } -- }; -- -- String collect(Map<String,String> currentValue currentValue, String key, -- PropertySource propertySource); -- --}</code></pre> --</div> --</div> --</div> --<div class="sect3"> --<h4 id="ConfigurationContext">The Configuration Context</h4> --<div class="paragraph"> --<p>A Configuration is created from a ConfigurationContext, which is --accessible from Configuration.getContext():</p> --</div> --<div class="listingblock"> --<div class="title">Accessing the current ConfigurationContext</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext();</code></pre> --</div> --</div> --<div class="paragraph"> --<p>The ConfigurationContext provides access to the internal artifacts that determine the final Configuration and --also defines the ordering of the property sources, filters and converters contained:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>PropertySources registered (including the PropertySources provided from PropertySourceProvider instances).</p> --</li> --<li> --<p>PropertyFilters registered, which filter values before they are returned to the client</p> --</li> --<li> --<p>PropertyConverter instances that provide conversion functionality for converting String values to any other types.</p> --</li> --<li> --<p>the current PropertyValueCombinationPolicy that determines how property values from different PropertySources are --combined to the final property value returned to the client.</p> --</li> --</ul> --</div> --</div> --<div class="sect3"> --<h4 id="Mutability">Changing the current Configuration Context</h4> --<div class="paragraph"> --<p>A ConfigurationContext is not mutable once it is created. In many cases mutability is also not needed. Nevertheless --there are use cases where the current ConfigurationContext (and --consequently Configuration) must be adapted:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>New configuration files where detected in a folder observed by Tamaya.</p> --</li> --<li> --<p>Remote configuration, e.g. stored in a database or alternate ways has been updated and the current system must --be adapted to these changes.</p> --</li> --<li> --<p>The overall configuration context is manually setup by the application logic.</p> --</li> --<li> --<p>Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the --tests executed.</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>In such cases the ConfigurationContext must be changed, meaning it must be possible:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>to add or remove PropertySource instances</p> --</li> --<li> --<p>to add or remove PropertyFilter instances</p> --</li> --<li> --<p>to add or remove PropertyConverter instances</p> --</li> --<li> --<p>to redefine the current PropertyValueCombinationPolicy instances.</p> --</li> --</ul> --</div> --<div class="paragraph"> --<p>This can be achieved by obtaining an instance of ConfigurationContextBuilder. Instances of this builder can be --accessed either</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>calling ConfigurationContext.toBuilder(), hereby returning a builder instance preinitialized with the values from the --current ConfigurationContext.</p> --</li> --<li> --<p>calling ConfigurationProvider.getConfigurationContextBuilder().</p> --</li> --</ul> --</div> --<div class="listingblock"> --<div class="title">Accessing a ConfigurationContextBuilder</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext().toBuilder(); --ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder();</code></pre> --</div> --</div> --<div class="paragraph"> --<p>With such a builder a new ConfigurationContext can be created and then applied:</p> --</div> --<div class="listingblock"> --<div class="title">Creating and applying a new ConfigurationContext</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext() -- .toBuilder(); -- .addPropertySources(new MyPropertySource()) -- .addPropertyFilter(new MyFilter()) -- .build();</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Hereby the builder provides several methods for adding, removing of property sources and also operations --for programmatically change the property sourcepriorities, e.g.</p> --</div> --<div class="listingblock"> --<div class="title">Chain manipulation using ConfigurationContextBuilder</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">PropertySource propertySource = builder.getPropertySource("sourceId"); -- --// changing the priority of a property source. The ordinal value hereby is not considered. --// Instead the position of the property source within the chain is changed. --builder.decreasePriority(propertySource); -- --// Alternately a comparator expression can be passed to establish the defined ordering... --builder.sortPropertyFilters(MyFilterComparator::compare);</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Finally if the new context is ready a new configuration can be created, or the context is applied to the --current configuration.</p> --</div> --<div class="listingblock"> --<div class="title">Creating and applying a new ConfigurationContext</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ConfigurationContext context = builder.build(); -- --// Creates a new matching Configuration instance --Configuration newConfig = ConfigurationProvider.createConfiguration(context); -- --// Apply the new context to replace the current configuration: --ConfigurationProvider.setConfigurationContext(context);</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Hereby ConfigurationProvider.setConfigurationContext(context) can throw an UnsupportedOperationException. --This can be checked by calling the method boolean ConfigurationProvider.isConfigurationContextSettable().</p> --</div> --</div> --<div class="sect3"> --<h4 id="ConfigurationProviderSpi">Implementing and Managing Configuration</h4> --<div class="paragraph"> --<p>One of the most important SPI in Tamaya if the ConfigurationProviderSpi interface, which is backing up the --ConfigurationProvider singleton. Implementing this class allows</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>to fully determine the implementation class for Configuration</p> --</li> --<li> --<p>to manage the current ConfigurationContext in the scope and granularity required.</p> --</li> --<li> --<p>to provide access to the right Configuration/ConfigurationContext based on the current runtime context.</p> --</li> --<li> --<p>Performing changes as set with the current ConfigurationContextBuilder.</p> --</li> --</ul> --</div> --</div> --</div> --</div> --</div> --<h1 id="_interface_configurationcontextbuilder" class="sect0">Interface ConfigurationContextBuilder</h1> -<div class="paragraph"> -<p>Unresolved directive in <stdin> - include::temp-properties-files-for-site/attributes.adoc[]</p> -</div> --<div class="sect1"> --<h2 id="BuilderCore">Interface ConfigurationContextBuilder</h2> --<div class="sectionbody"> --<div class="sect2"> --<h3 id="_overview">Overview</h3> --<div class="paragraph"> --<p>The Tamaya builder module provides a generic (one time) builder for creating Configuration instances, --e.g. as follows:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ConfigurationBuilder builder = new ConfigurationBuilder(); --// do something --Configuration config = builder.build();</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Basically the builder allows to create configuration instances completely independent of the current configuration --setup. This gives you full control on the Configuration setup.</p> --</div> --</div> --<div class="sect2"> --<h3 id="_supported_functionality">Supported Functionality</h3> --<div class="paragraph"> --<p>The builder allows you to add PropertySource instances:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ConfigurationContextBuilder builder = ConfigurationProvider.getConfigurationContextBuilder(); --builder.addPropertySources(sourceOne, sourceTwo, sourceThree --Configuration config = ConfigurationProvider.createConfiguration(builder.build());</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Hereby the ordering of the propertysources is not changed, regardless of the ordinals provided --by the property sources. This allows alternate ordering policies easily being implemented because --creating a configuration based on a configuration context is already implemented and provided by the core --API.</p> --</div> --<div class="paragraph"> --<p>Similarly you can add filters:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">builder.addPropertyFilters(new MyConfigFilter());</code></pre> --</div> --</div> --<div class="paragraph"> --<p>…​or PropertySourceProvider instances:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">builder.addPropertySourceProvider(new MyPropertySourceProvider());</code></pre> --</div> --</div> --<div class="sect3"> --<h4 id="ServiceContext">The ServiceContext</h4> --<div class="paragraph"> --<p>The ServiceContext is also a very important SPI, which allows to define how components are loaded in Tamaya. --The ServiceContext hereby defines access methods to obtain components, whereas itself it is available from the --ServiceContextManager singleton:</p> --</div> --<div class="listingblock"> --<div class="title">Accessing the ServiceContext</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ServiceContext serviceContext = ServiceContextManager.getServiceContext(); -- --public interface ServiceContext{ -- int ordinal(); -- <T> T getService(Class<T> serviceType); -- <T> List<T> getServices(Class<T> serviceType); --}</code></pre> --</div> --</div> --<div class="paragraph"> --<p>With the ServiceContext a component can be accessed in two different ways:</p> --</div> --<div class="olist arabic"> --<ol class="arabic"> --<li> --<p>access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally --the most significant instance is returned only.</p> --</li> --<li> --<p>access all items given its type. This will return (by default) all instances loadedable from the current --runtime context, ordered by priority, hereby the most significant components added first.</p> --</li> --</ol> --</div> --</div> --</div> --</div> --</div> --<div class="sect1"> --<h2 id="_examples">Examples</h2> --<div class="sectionbody"> --<div class="sect2"> --<h3 id="_accessing_configuration">Accessing Configuration</h3> --<div class="paragraph"> --<p><em>Configuration</em> is obtained from the ConfigurationProvider singleton:</p> --</div> --<div class="listingblock"> --<div class="title">Accessing Configuration</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">Configuration config = ConfigurationProvider.getConfiguration();</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Many users in a SE context will probably only work with <em>Configuration</em>, since it offers all functionality --needed for basic configuration with a very lean memory and runtime footprint. In Java 7 access to the keys is --very similar to <strong>Map<String,String></strong>, whereas in Java 8 additionally usage of <em>Optional</em> is supported:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">Configuration config = ConfigurationProvider.getConfiguration(); --String myKey = config.get("myKey"); // may return null --int myLimit = config.get("all.size.limit", int.class);</code></pre> --</div> --</div> --</div> --<div class="sect2"> --<h3 id="_environment_and_system_properties">Environment and System Properties</h3> --<div class="paragraph"> --<p>By default environment and system properties are included into the <em>Configuration</em>. So we can access the current --<em>PROMPT</em> environment variable as follows:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">String prompt = ConfigurationProvider.getConfiguration().get("PROMPT");</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Similary the system properties are directly applied to the <em>Configuration</em>. So if we pass the following system --property to our JVM:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">java ... -Duse.my.system.answer=yes</code></pre> --</div> --</div> --<div class="paragraph"> --<p>we can access it as follows:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">boolean useMySystem = ConfigurationProvider.getConfiguration().get("use.my.system.answer", boolean.class);</code></pre> --</div> --</div> --</div> --<div class="sect2"> --<h3 id="_adding_a_custom_configuration">Adding a Custom Configuration</h3> --<div class="paragraph"> --<p>Adding a classpath based configuration is simply as well: just implement an according <em>PropertySource</em>. With the --<em>tamaya-spi-support</em> module you just have to perform a few steps:</p> --</div> --<div class="olist arabic"> --<ol class="arabic"> --<li> --<p>Define a PropertySource as follows:</p> --</li> --</ol> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java"> public class MyPropertySource extends PropertiesResourcePropertySource{ -- -- public MyPropertySource(){ -- super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"), DEFAULT_ORDINAL); -- } -- }</code></pre> --</div> --</div> --<div class="paragraph"> --<p>Then register MyPropertySource using the ServiceLoader by adding the following file:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">META-INF/services/org.apache.tamaya.spi.PropertySource</code></pre> --</div> --</div> --<div class="paragraph"> --<p>…​containing the following line:</p> --</div> --<div class="listingblock"> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-listing" data-lang="listing">com.mypackage.MyPropertySource</code></pre> --</div> --</div> --</div> --</div> --</div> --<div class="sect1"> --<h2 id="APIImpl">API Implementation</h2> --<div class="sectionbody"> --<div class="paragraph"> - <p>The API is implemented by the Tamaya-Core-module. Refer to the <a href="core.html">Core documentation</a> for -<p>The API is implemented by the Tamaya _Core_module. Refer to the <a href="Core.html">Core documentation</a> for --further details.</p> --</div> --</div> --</div></p> -- -- <hr /> -- </div> -- </div> -- <div> -- <div id="push"></div> -- -- <div id="footer"> -- <div class="container"> -- <p class="muted credit">© 2014-2016 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.0</span></a> -- at <span>2016-12-19</span> -- </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 /> -- <a href="http://incubator.apache.org/guides/website.html"; style="border:0px;" target="_target"><img class="incubator-logo" src="../logos/egg-logo2.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/4f4912e5/documentation/core.html ---------------------------------------------------------------------- diff --cc documentation/core.html index 4d77673,c59af7b..0000000 deleted file mode 100644,100644 --- a/documentation/core.html +++ /dev/null @@@ -1,600 -1,597 +1,0 @@@ --<!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> - <a class="navbar-brand" href="../">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><a href="../index.html">Home</a></li> - <li><a href="../about.html">About</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/index.html">Javadoc {tamaya_version} (external)</a></li> - <li><a href="../apidocs/index.html">Javadoc ${tamaya_version} (external)</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>2016-12-19</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">Tamaya Configuration API</a> and adds additional functionality -<p>Tamaya Core provides an implementation of the <a href="API.html">Tamaya Configuration API</a> and adds additional functionality --and building blocks for supporting SPI implementations.</p> --</div> --<div class="paragraph"> --<p>Tamaya Core contains the following artifacts:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>Implementations of Configuration, ConfigurationContext, ConfigurationContextBuilder ConfigurationProviderSpi+</p> --</li> --<li> --<p>A java.util.ServiceLoader based ServiceContext implementation. Hereby it implements component priorization based --on the @Priority annotations.</p> --</li> --<li> --<p>A PropertyConverterManager+ that loads and stores references to all the preconfigured PropertyConverter instances --hereby providing type conversion for all important types.</p> --</li> --<li> --<p>A simple default configuration setup using the current classpath and an optional staging variable.</p> --</li> --<li> --<p>It collects all PropertySource and PropertySourceProvider instances registered with the ServiceLoader and --registers them in the global ConfigurationContext</p> --</li> --<li> --<p>It provides a ConfigurationContextBuilder implementation (class DefaultConfigurationContextBuilder) and allows --changing the current ConfigurationContext.</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</p> --</li> --<li> --<p>dynamic resource path lookup, e.g. with ant styled patterns</p> --</li> --<li> --<p>configuration injection and configuration templates</p> --</li> --<li> --<p>abstraction for reusable formats</p> --</li> --<li> --<p>integration with other existing solutions</p> --</li> --<li> --<p>configuration and configuration isolation targeting Java EE</p> --</li> --<li> --<p>dynamic configuration and configuration updates</p> --</li> --<li> --<p>Configuration management extensions</p> --</li> --<li> --<p>remote configuration</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> -<p>For details about the extension modules available and their functionality refer to the <a href="modules.html">extension user guide</a>.</p> --</div> --</div> --<div class="sect2"> --<h3 id="CorePropertyConverters">Default PropertyConverters in Core</h3> --<div class="paragraph"> --<p>As mentioned the Core module delivers several default PropertyConverter instances out of the box. 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_propertyconverters">Registering PropertyConverters</h3> --<div class="paragraph"> --<p>Additional PropertyConverters can be implemented easily. It is recommended to register then using the java.util.ServiceLoader, --meaning you add a file under META-INF/service/org.apache.tamaya.spi.PropertyConverter containing the fully qualified --class names of the converters to be registered (one line per each).</p> --</div> --<div class="paragraph"> --<p>Alternatively you can also use a ConfigurationContextBuilder to add additional converters programmatically.</p> --</div> --<div class="admonitionblock note"> --<table> --<tr> --<td class="icon"> --<div class="title">Note</div> --</td> --<td class="content"> --API Implementations can be read-only thus not allowing adding additional converters programmatically. --</td> --</tr> --</table> --</div> --</div> --<div class="sect2"> --<h3 id="ComponentLoadingAndPriorization">Component Loading and Priorization</h3> --<div class="paragraph"> --<p>Tamaya Core in general loads all components 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 --core adds this functionality by the possibility to add @Priority annotations to the components registered. --By default, and if no annotation is added 0 is used as priority. Hereby higher values preceed lower values, meaning</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>if a singleton 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 collection of components is obtained from the ServiceContext the components are ordered in order, where the --ones with higher priority are before components with lower priority.</p> --</li> --<li> --<p>if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is --still defined and predictable in almost 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="RegisteringPropertySources">Registering Property Sources</h3> --<div class="paragraph"> --<p>PropertySources that provide configuration properties are registered as ordinary components as described in the previous --section. Nevertheless the priority is not managed based on @Priority annotations, but based on an explicit --int getOrdinal() method. This allows to define the ordinal/priority of a PropertySource explicitly. This is useful --due to several reasons:</p> --</div> --<div class="ulist"> --<ul> --<li> --<p>it allows to define the ordinal as part of the configuration, thus allowing new overriding property sources being --added easily.</p> --</li> --<li> --<p>it allows to define the ordinal dynamically, e.g. based on the configuration location, the time of loading or --whatever may be appropriate.</p> --</li> --</ul> --</div> --</div> --</div> --</div> --<div class="sect1"> --<h2 id="CorePropertySources">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/javaconfiguration.properties --and META-INF/javaconfiguration.xml</p> --</li> --</ol> --</div> --<div class="sect2"> --<h3 id="_overview_of_registered_default_property_sources_and_providers">Overview of Registered Default Property Sources and Providers</h3> --<div class="paragraph"> --<p>The Tamaya Core implementation provides a couple of default PropertySource implementations, which are automatically --registered. They are all in the package org.apache.tamaya.core.propertysource and --org.apache.tamaya.core.provider:</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/javaconfiguration.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">0</p></td> --</tr> --<tr> --<td class="tableblock halign-left valign-top"><p class="tableblock">META-INF/javaconfiguration.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">0</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">EnvironmentPropertySource</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">SystemPropertySource</p></td> --<td class="tableblock halign-left valign-top"><p class="tableblock">400</p></td> --</tr> --</tbody> --</table> --</div> --<div class="sect2"> --<h3 id="_abstract_class_propertiesfilepropertysource">Abstract Class PropertiesFilePropertySource</h3> --<div class="paragraph"> --<p>The abstract class PropertiesFilePropertySource can be used for implementing a PropertySource 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">PropertiesFilePropertySource(URL url);</code></pre> --</div> --</div> --<div class="sect3"> --<h4 id="_abstract_class_propertiespropertysource">Abstract Class PropertiesPropertySource</h4> --<div class="paragraph"> --<p>The abstract class PropertiesPropertySource can be used for implementing a PropertySource based on a Properties --instance. It requires a PropertySource 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">PropertiesPropertySource(Properties properties);</code></pre> --</div> --</div> --</div> --<div class="sect3"> --<h4 id="_abstract_class_basepropertysource">Abstract Class BasePropertySource</h4> --<div class="paragraph"> --<p>The abstract class BasePropertySource can be used for implementing custom PropertySource classes. It requires only --one method to implemented:</p> --</div> --<div class="listingblock"> --<div class="title">Implementing a PropertySource using BasePropertySource</div> --<div class="content"> --<pre class="prettyprint highlight"><code class="language-java" data-lang="java">public class MyPropertySource extends BasePropertySource{ -- -- public String getName(){ -- // return a unique name for the property 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 property source -- // If the property source is not scannable, the map returned may be empty. -- // In the ladder case the +boolean isScannale()+ must be overridden, since -- // by default property sources are assumed to be scannable. -- } -- --}</code></pre> --</div> --</div> --<div class="paragraph"> --<p>By default the ordinal of the property sources will be 1000, unless the key tamaya.ordinal asdefined in --PropertySource.TAMAYA_ORDINAL is present in the current PropertySource. 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="CorePropertySourceProviders">Default PropertySourceProvider in Core</h3> --<div class="paragraph"> --<p>With org.apache.tamaya.core.provider.JavaConfigurationProvider there is also a default PropertySourceProvider --present that loads all .properties files found at META-INF/javaconfiguration.properties --and META-INF/javaconfiguration.xml.</p> --</div> --</div> --</div> --</div> --<div class="sect1"> --<h2 id="Extensions">Adding Extensions</h2> --<div class="sectionbody"> --<div class="paragraph"> - <p>The Core module only implements the <a href="api.html">API</a>. Many users require/wish additional functionality from a -<p>The Core module 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-2016 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.0</span></a> -- at <span>2016-12-19</span> -- </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 /> -- <a href="http://incubator.apache.org/guides/website.html"; style="border:0px;" target="_target"><img class="incubator-logo" src="../logos/egg-logo2.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>
