You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by an...@apache.org on 2018/11/18 21:20:47 UTC
[1/8] incubator-tamaya-site git commit: TAMAYA-359 Improve hompage,
also adding a windows start script to bake and view the paeg locally.
Repository: incubator-tamaya-site
Updated Branches:
refs/heads/master 43f983e92 -> 8dd2accde
TAMAYA-359 Improve hompage, also adding a windows start script to bake and view the paeg locally.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/15c355a8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/15c355a8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/15c355a8
Branch: refs/heads/master
Commit: 15c355a8100a5b91fbe65cf34502d493acb2c7c6
Parents: 31718f6
Author: Anatole Tresch <at...@gmail.com>
Authored: Tue Oct 23 18:44:33 2018 +0200
Committer: Anatole Tresch <at...@gmail.com>
Committed: Tue Oct 23 18:44:33 2018 +0200
----------------------------------------------------------------------
assets/css/base.css | 20 +++-
assets/logos/tamaya.png | Bin 0 -> 2015 bytes
bake.cmd | 9 ++
content/about.adoc | 45 ++++++++
.../extensions/mod_microprofile.adoc | 2 +-
content/documentation/quickstart.adoc | 6 +-
content/documentation/usecases.adoc | 26 ++++-
content/features.adoc | 105 +++++++++++++++++++
content/start.adoc | 2 +-
templates/blog.thyme | 27 +++++
templates/footer.thyme | 5 +-
templates/index.thyme | 60 +++++++++--
templates/menu.thyme | 9 +-
13 files changed, 293 insertions(+), 23 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/assets/css/base.css
----------------------------------------------------------------------
diff --git a/assets/css/base.css b/assets/css/base.css
index 68fe241..96a8004 100644
--- a/assets/css/base.css
+++ b/assets/css/base.css
@@ -36,16 +36,34 @@ body {
}
}
+.incubator-logo {
+ width; 300px;
+ height: 30px;
+}
+
/* Custom page CSS
-------------------------------------------------- */
/* Not required for template or sticky footer method. */
#wrap > .container {
- padding-top: 60px;
+ padding-top: 20px;
}
.container .credit {
margin: 20px 0;
}
+.front-logo {
+ padding-top: 6px;
+ padding-right: 20px;
+ padding-bottom: 10px;
+ padding-left: 0px;
+}
+.front-cell {
+ padding-top: 5px;
+ padding-right: 5px;
+ padding-bottom: 5px;
+ padding-left: 0px;
+ width: 33%;
+}
/*code {
font-size: 80%;
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/assets/logos/tamaya.png
----------------------------------------------------------------------
diff --git a/assets/logos/tamaya.png b/assets/logos/tamaya.png
new file mode 100644
index 0000000..16df5d7
Binary files /dev/null and b/assets/logos/tamaya.png differ
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/bake.cmd
----------------------------------------------------------------------
diff --git a/bake.cmd b/bake.cmd
new file mode 100644
index 0000000..c8c630b
--- /dev/null
+++ b/bake.cmd
@@ -0,0 +1,9 @@
+@ECHO OFF
+cls
+echo Cleaning up cache ...
+rmdir /Q /S cache/
+echo Starting to bake our project homepage ....
+set JBAKE_HOME="%~dp0\bin\jbake-2.6.1-bin"
+echo %JBAKE_HOME%
+%JBAKE_HOME%/bin/jbake -b -s
+@ECHO ON
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/content/about.adoc
----------------------------------------------------------------------
diff --git a/content/about.adoc b/content/about.adoc
new file mode 100644
index 0000000..cfdc6c3
--- /dev/null
+++ b/content/about.adoc
@@ -0,0 +1,45 @@
+:jbake-type: page
+:jbake-status: published
+
+= About Tamaya
+
+Apache Tamaya (incubating) provides a *unopinionated and powerful
+configuration solution* for developers on the JVM.
+
+
+== Rationale
+
+Configuration is one of the most prominent cross-cutting concerns similar to logging. Most of us already have been
+writing similar code again and again in each of our projects. Sometimes in a similar way but mostly always slightly
+different, but certainly with high coupling to your configuration backends. Given your code is reused or integrated
+some how, or deployed by some customers, struggling starts: not supported backends, different policies, missing
+combination and validation mechanisms and so on. Tamaya solves all this by defining a common API and backend SPI.
+Your code is decoupled from the configuration backend. There is no difference if your code is deployed on your dev box
+or in a clustered Docker environment in production, it stays the same!
+
+
+For further information we recommend to have a look at our documentation resources:
+
+* link:features.html[Feature Overview]
+* link:documentation/usecases.html[Use Cases and Requirements]
+* link:highleveldesign.html[High Level Design]
+* link:documentation/api.html[API]
+* link:documentation/core.html[Core]
+* link:documentation/extensions.html[Extensions]
+
+
+== You just wanna start right away
+
+So here is five liner to start...
+
+1. Add `{tamaya_mvn_group_id}:tamaya-core:{tamaya_version}` to your dependencies.
+2. Add some config to `META-INF/javaconfiguration.properties`
+3. Access your configuration by `Configuration.current()` and use it.
+4. Look at the link:features.html[extensions modules] to customize your setup!
+5. Enjoy!
+
+And, yes, give feedback, so we can improve ;-)
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/content/documentation/extensions/mod_microprofile.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_microprofile.adoc b/content/documentation/extensions/mod_microprofile.adoc
index 9d5951d..b6d8bb0 100644
--- a/content/documentation/extensions/mod_microprofile.adoc
+++ b/content/documentation/extensions/mod_microprofile.adoc
@@ -55,7 +55,7 @@ be supported by Tamaya as well.
--------------------------------------------------------
// SE API
-Config config = ConfigProvider.getConfig();
+Config config = Configuration.current();
String serverUrl = config.getValue("acme.myprj.some.url", String.class);
callToServer(serverUrl);
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/content/documentation/quickstart.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/quickstart.adoc b/content/documentation/quickstart.adoc
index 8648e74..e396bcc 100644
--- a/content/documentation/quickstart.adoc
+++ b/content/documentation/quickstart.adoc
@@ -26,7 +26,7 @@ to provide the default values when accessing the configuration:
[source,java]
----
-Configuration config = ConfigurationProvider.getConfiguration();
+Configuration config = Configuration.current();
String aTextValue = config.getOrDefault("my.value.key", "N/A");
int aNumericValue = config.getOrDefault("my.numValueKey", Integer.class, 15 /* default */);
@@ -37,9 +37,9 @@ With Java 8 you can, of course, also use +Optional+, e.g.
[source,java]
----
-Configuration config = ConfigurationProvider.getConfiguration();
+Configuration config = Configuration.current();
-String aTextValue = Optional.ofNullable(config.getOrDefault("my.value.key").orElse("N/A");
+String aTextValue = config.getOptional("my.value.key", String.class).orElse("N/A");
----
=== Add/define your configuration data
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/content/documentation/usecases.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/usecases.adoc b/content/documentation/usecases.adoc
index 0d0d4e0..8d83ced 100644
--- a/content/documentation/usecases.adoc
+++ b/content/documentation/usecases.adoc
@@ -1,7 +1,31 @@
:jbake-type: page
:jbake-status: published
-== Apache Tamaya: Use Cases and Requirements
+
+= Why you should rely on Tamaya?
+
+There are several reasons, why you should choose Tamaya, some of them:
+
+* *Tamaya is useful*: Tamaya ships with a type safe, easy to use API and SPI, which can help you to decouple your
+ code from configuration concerns.
+* *Tamaya is flexible*: Regardless of working
+with Vanilla Java SE or with OSGI or Jakarta EE, Tamaya can be the tool
+of choice for your configuration concerns.
+* *Tamaya is extendible*: Tamaya comes with a lean core API. Additional features can
+ be added easily by simply adding them to the project classpath as needed.
+Tamaya does not fill up your memory with things you wont ever need.
+* *Tamaya is easy*: Tamaya comes with a flexible auto-discovery mechanism to lookup
+ the property sources and define their individual significance.
+* *Tamaya is runtime-independent*: Tamaya runs on every JVM platform, since it's core is written in pure
+ Java.
+* *Tamaya is well documented*: Both the API as well as the extension are all well documented.
+* *Tamaya is Apache*: Tamaya is community as it's best, no vendor lock-in, no payed members, just
+ the Apache Way!
+
+A good way to continue is probably looking at the use cases we had in mind, when implementing Tamaya...
+
+
+= Use Cases and Requirements
toc::[]
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/content/features.adoc
----------------------------------------------------------------------
diff --git a/content/features.adoc b/content/features.adoc
new file mode 100644
index 0000000..eb43a57
--- /dev/null
+++ b/content/features.adoc
@@ -0,0 +1,105 @@
+:jbake-type: page
+:jbake-status: published
+
+[toc]
+
+= Tamaya\'s Features
+
+Apache Tamaya comes with numerous useful features. This page lists the most important
+ones. Also also have a look at the full feature list. If you don't find your features,
+please get in contact with us to discuss your ideas!
+
+== Core Features
+
+The Core Features are built-in riht away and available by default. Just add Tamaya to your project
+dependencies and there you go!
+
+
+=== Accessing Configuration
+
+Tamaya provides a super simple API to access configuration:
+
+[source: java]
+----
+Configuration config = Configuration.current();
+----
+
+Yes it's as easy as that. Optionally you can also pass your classloader of choice:
+
+[source: java]
+----
+ClassLoader myApplicationClassLoader = ...;
+Configuration config = Configuration.current(myApplicationClassLoader);
+----
+
+From there you can access your configuration properties:
+
+[source: java]
+----
+String host = config.getOrDefault("server.host", "localhost");
+Optional<Integer> port = config.getOptional("server.port", Integer.class);
+----
+
+
+=== Providing Configuration
+
+Providing configuration is as simple:
+
+* Implement the `PropertySource` interface.
+* Register your implementation with the Java `ServiceLoader`.
+
+
+== Configuration Auto-Discovery and Builders
+
+Tamaya can care about everything. You dont have to bother with
+configuration sources, classloaders, overriding etc. Tamaya will collect and load
+all registered property sources.
+
+On the other hand if you prefer having full control, Tamaya provides
+powerful factories and builders, with allow to built your customized
+configuration and manage your own configuration lifecycle.
+
+[source: java]
+----
+Configuration config = Configuration.builder()
+ .withDefaultPropertySources()
+ .addPropertySources(new MyCustomPropertySource())
+ .withDefaultConverters()
+ .build();
+----
+
+
+== Pluggable Extensions
+
+Tamaya comes with numerous features, that can be easily added. Just add
+the corresponding dependency to your build. Yes, it's as easy as that.
+So let's have a quick look at some of the most commonly used features...
+
+
+== Functional Extensions
+
+
+== Dynamic Placeholders
+
+
+== Different Configuration Formats: JSON, YAML, XML, properties, ini...
+
+
+== Support for Configuration Injection
+
+
+== Support for Configuration Templates
+
+
+== Ant styled File Resource Wildcards
+
+
+== Support for Spring/Spring Boot
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/content/start.adoc
----------------------------------------------------------------------
diff --git a/content/start.adoc b/content/start.adoc
index 58eb6f1..35cb043 100644
--- a/content/start.adoc
+++ b/content/start.adoc
@@ -33,7 +33,7 @@ Using Apache Tamaya is simple:
1. Add `{tamaya_mvn_group_id}:tamaya-core:{tamaya_version}` to your dependencies.
2. Add your config to `META-INF/javaconfiguration.properties`
-3. Access your configuration by `ConfigurationProvider.getConfiguration()` and use it.
+3. Access your configuration by `Configuration.current()` and use it.
4. Look at the link:documentation/extensions.html[extensions modules] to customize your setup!
5. Enjoy!
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/templates/blog.thyme
----------------------------------------------------------------------
diff --git a/templates/blog.thyme b/templates/blog.thyme
new file mode 100644
index 0000000..95deaf6
--- /dev/null
+++ b/templates/blog.thyme
@@ -0,0 +1,27 @@
+<!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-strict-thymeleaf-4.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:th="http://www.thymeleaf.org">
+ <head th:replace="header.thyme::head"/>
+ <body onload="prettyPrint()">
+ <div id="wrap">
+ <div th:replace="menu.thyme::menu"/>
+ <div class="container">
+ <div class="page-header">
+ <h1>Blog</h1>
+ </div>
+
+ <div th:each="post : ${published_posts}">
+ <a th:href='${post.uri}' href='href'><h1 th:text='${post.title}'>title</h1></a>
+ <p th:text='${#dates.format(post.date,"yyyy-MM-dd")}'>date</p>
+ <p th:utext='${post.body}'>body</p>
+ </div>
+
+ <hr />
+
+ <p>Older posts are available via the <a th:href='${content.rootpath+config.archive_file}' href='href'>archive</a>.</p>
+ </div>
+ </div>
+
+ <div th:replace="footer.thyme::footer"></div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/templates/footer.thyme
----------------------------------------------------------------------
diff --git a/templates/footer.thyme b/templates/footer.thyme
index 0a91f5f..1113845 100644
--- a/templates/footer.thyme
+++ b/templates/footer.thyme
@@ -26,10 +26,7 @@
the code, it does indicate that the project has yet to
be fully endorsed by the ASF.
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 th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" class="incubator-logo" th:src="${rootpath} + 'logos/apache-incubator.png'"/>
- </a>
- </p>
+ </p>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/templates/index.thyme
----------------------------------------------------------------------
diff --git a/templates/index.thyme b/templates/index.thyme
index 95deaf6..ed228ac 100644
--- a/templates/index.thyme
+++ b/templates/index.thyme
@@ -7,18 +7,60 @@
<div th:replace="menu.thyme::menu"/>
<div class="container">
<div class="page-header">
- <h1>Blog</h1>
- </div>
-
- <div th:each="post : ${published_posts}">
- <a th:href='${post.uri}' href='href'><h1 th:text='${post.title}'>title</h1></a>
- <p th:text='${#dates.format(post.date,"yyyy-MM-dd")}'>date</p>
- <p th:utext='${post.body}'>body</p>
+ <h1><img class="front-logo" src="/logos/tamaya.png"/>Apache Tamaya (Incubating)</h1>
</div>
+ <div>
+ <table class="table table-striped">
+ <tbody>
+ <tr>
+ <td class="front-cell">
+ <h3>What is Tamaya?</h3>
+ <p>Tamaya is a powerful, flexible but simple configuration API that decouples your application
+ from your configuration backend sources.</p>
+ <p><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'about.html'">Learn more about Tamaya</a></p>
+ </td>
+ <td class="front-cell">
+ <h3>Challenge it: Why you should use Tamaya?</h3>
+ <p>Configuration is one of the most important cross-cutting concerns. Nevertheless
+ most people rewrite similar logic again and again. It's time to rely on a standard
+ compliant solution that allows to plug-in any configuration resources?</p>
+ <p><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/usecases.html'">Look at Tamaya's Use Cases</a></p>
+ </td>
+ <td class="front-cell">
+ <h3>Try it: Get started!</h3>
+ <p>Get started is easy. Look at our examples, add Tamaya's runtime dependency and
+ there you go. Tamaya is plain Java SE in it's core. Lean and effective. And if you have
+ a question, let us know. We are happy to help!</p>
+ <p><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/quickstart.html'">"Getting started" right away!</a></p>
+ </td>
+ </tr>
+ <tr>
+ <td class="front-cell">
+ <h3>Use it: Add more Features!</h3>
+ <p>Did we already have mentioned features? There are a lot of them. Read this
+ overview about current and upcoming features to see what matches your
+ requirements. Tamaya is modular, you only depend on what you like.</p>
+ <p><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'features.html'">Checkout our outstanding features</a></p>
+ </td>
+ <td class="front-cell">
+ <h3>Rely on it: Tamaya as a standard</h3>
+ <p>Tamaya is not only a flexible configuration solution, it is also future proof.
+ With Tamaya you get an indepepdent implementation of the current Microprofile
+ Config and JSR 310 API.</p>
+ <p><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/tamayaasastandard.html'">Learn more</a></p>
+ </td>
+ <td class="front-cell">
+ <h3>Improve it: Get involved...</h3>
+ <p>Tell us your story and help us making Tamaya even better.
+ We are happy to support you and discuss further features or improvements.</p>
+ <p><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'development/community.html'">Get involved!</a></p>
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
<hr />
-
- <p>Older posts are available via the <a th:href='${content.rootpath+config.archive_file}' href='href'>archive</a>.</p>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/15c355a8/templates/menu.thyme
----------------------------------------------------------------------
diff --git a/templates/menu.thyme b/templates/menu.thyme
index d3bcfa8..1aaba7b 100644
--- a/templates/menu.thyme
+++ b/templates/menu.thyme
@@ -14,7 +14,7 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
- <a class="navbar-brand" th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Apache Tamaya (incubating)</a>
+ <a class="navbar-brand" th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Tamaya Home</a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
@@ -67,9 +67,12 @@
</ul>
</li>
-->
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'sitemap.xml'">Sitemap</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+${config.feed_file}">Subscribe</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'sitemap.xml'">Sitemap</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+${config.feed_file}">Subscribe</a></li>
+ <li><a href="https://incubator.apache.org/guides/website.html" style="border:0px;" target="_target">
+ <img th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" class="incubator-logo" th:src="${rootpath} + 'logos/apache-incubator.png'"/></a></li>
</ul>
+
</div><!--/.nav-collapse -->
</div>
</div>
[3/8] incubator-tamaya-site git commit: TAMAYA-274 Updated
documentation. TAMAYA-355 Updated documentation. TAMAYA-353 Updated
documentation.
Posted by an...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_jodatime.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_jodatime.adoc
index 67a88a1,67a88a1..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_jodatime.adoc
+++ /dev/null
@@@ -1,80 -1,80 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: JodaTime
--
--toc::[]
--
--[[JodaTime]]
--== Tamaya JodaTime (Extension Module)
--Tamaya _JodaTime_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _JodaTime_ is an extension module to support the usage of http://www.joda.org/joda-time/[Joda-Time]
--in conjunction with Tamaya. Tamaya JodaTime defines some additional property
--converters to use Joda-Time types when accessing configuration.
--
--
--=== Installation
--
--To support Joda-Time types as configuration values, you only have to add the following
--maven dependency to your project:
--
--[source, listing]
-------------------------------------------------
--<dependency>
-- <grooupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-jodatime</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Usage
--
--After adding this module to your project you can retrieve
--Joda-Time based values directly from a given configuration.
--
--[source,java]
-------------------------------------------------
--Config configuration = ConfigProvider.getConfig();
--
--DateTime pit = configuration.get("pointInTime", DateTime.class)
-------------------------------------------------
--
--Currently the following types are supported:
--
--
--[width="80%",options=header]
--|================================================================
--| Joda-Time target type | Supported Input Formats
--.12+^.<| +org.joda.time.DateTime+ +org.joda.time.Instant+ | `yyyy-MM-dd'T'HH:mm:ss.SSSZ`
-- | `yyyy-MM-dd'T'HH:mm:ss.SSSz`
-- | `yyyy-MM-dd'T'HH:mm:ss.SSS z`
-- | `yyyy-MM-dd'T'HH:mm:ssZ`
-- | `yyyy-MM-dd'T'HH:mm:ssz`
-- | `yyyy-MM-dd'T'HH:mm:ss z`
-- | `yyyy-MM-dd'T'HH:mmZ`
-- | `yyyy-MM-dd'T'HH:mmz`
-- | `yyyy-MM-dd'T'HH:mm z`
-- | `yyyy-MM-dd'T'HHZ`
-- | `yyyy-MM-dd'T'HHz`
-- | `yyyy-MM-dd'T'HH z`
--.2+^.<| +org.joda.time.DateTimeZone+ | `[+-]hh:mm` (reg.ex.)
-- | all _timezone ids_ known by Joda-Time.
--.3+^.<| +org.joda.time.Duration+ | `PTa.bS`
-- | `PdDThHmMsS`
-- | `ddThh:mm:ss`
--.2+^.<| +org.joda.time.Period+ | `PyYmMwWdDThHmMsS`
-- | `Pyyyy-mm-ddThh:mm:ss`
--.4+^.<| +org.joda.time.LocalDate+ | `yyyy ['-' MM ['-' dd]]`
-- | `yyyy ['-' DDD]`
-- | `LocalDateConverter`
-- | `yyyy ['-' dd ['-' MM]]`
--.4+^.<| +org.joda.time.LocalTime+ | `['T']` _time-element_
-- | _time-element_ = HH [_minute-element_] _or_ [_fraction_]
-- | _minute-element_ = ':' mm [_second-element_] _or_ [_fraction_]
-- | _second-element_ = ':' ss [_fraction_]
-- | _fraction_ = ('.' _or_ ',') digit+`
--|================================================================
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_json.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_json.adoc
index a6e0572,a6e0572..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_json.adoc
+++ /dev/null
@@@ -1,80 -1,80 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Builder
--
--toc::[]
--
--
--[[JSON]]
--== Tamaya JSON (Extension Module)
--Tamaya _JSON_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _JSON_ provides support for reading configuration using JSON
--format:
--
--[source, json]
-------------------------------------------------
--{
-- "a.b"{
-- "key1": "blabla",
-- "key2": true,
-- }
--}
-------------------------------------------------
--
--Hereby the hierarchical structure of the JSON document will be mapped to a
--flat key-value pairs of type `String`, e.g. the bove will be mapped to
--
--[source, properties]
-------------------------------------------------
--a.b.key1=blabla
--a.b.key2=true
-------------------------------------------------
--
--This extension uses SPI defined by the +tamaya.formats+ extension module.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will run on Java 8 and beyond.
--
--
--=== Installation
--
--To use the JSON extension module you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-json</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--This extension also transitively requires the +tamaya.formats+ module.
--
--
--=== Reading configuration in JSON
--
--For reading JSON based onfiguration most easily a +JSONFormat+ can be
--used:
--
--[source, java]
-------------------------------------------------
--ConfigurationData dataRead = ConfigurationFormats.readConfig(
-- getClassLoader().getResource("myFileConfig.json"), new JSONFormat()));
-------------------------------------------------
--
--Or, if you are fine with the _default_ mapping you can directly create a
--+PropertySource+ using the _formats_ API (this works since this module
--registers the _json_ format automatically using the `ServiceContext`):
--
--[source, java]
-------------------------------------------------
--ConfigSource ps = ConfigurationFormats.createConfigSource(
-- getClassLoader().getResource("myFileConfig.json"));
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_management.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_management.adoc
index df45aeb,df45aeb..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_management.adoc
+++ /dev/null
@@@ -1,97 -1,97 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: JMX Management Access
--
--toc::[]
--
--
--[[ExtModel]]
--== Tamaya Management (JMX Support) (Extension Module)
--Tamaya _Management_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--The Tamaya _Management_ module provides support for registering a JMX management bean for
--accessing configuration.
--
--=== Compatibility
--
--The module is based on Java 8, so it will run on Java 8 and beyond.
--
--
--=== Installation
--
--To use the _management_ extension you only must add the corresponding dependency
--to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-management</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The ManagedConfigMBean bean
--
--The management model defines the MBean of type +ManagedConfigMBean+ as follows:
--
--
--[source,java]
-------------------------------------------------------------------------------
--public interface ManagedConfigMBean {
-- String getJsonConfigurationInfo();
-- String getXmlConfigurationInfo();
-- Map<String, String> getConfiguration();
-- Map<String, String> getSection(String area, boolean recursive);
-- Set<String> getSections();
-- Set<String> getTransitiveSections();
-- boolean isSectionExisting(String area);
-- default boolean isSectionEmpty(String area);
--}
-------------------------------------------------------------------------------
--
--* +getJsonConfigurationInfo,getXmlConfigurationInfo+ return a JSON or XML representation of the
--current configuration.
--* +getConfiguration+ access the current configuration properties.
--* +getSection+ allows to extract all entries below a certain subkey. With _recursive_ the query
-- will not only return direct children, but also recursively walk down all subsection of the
-- given section key.
--* +getSections+ returns all current known section names.
--* +getTransitiveSections+ return all sections, but also adds all transitive subsection as single
-- entries to the set as well.
--* +isSectionExisting+ and +isSectionEmpty+ allow for quering if entries are present under the given
-- section keys.
--
--
--=== Registering the ManagedConfigMBean
--
--For registering the current +ManagedConfigMBean+ instance to the current MBean platform server, the
--following static methods are available:
--
--[source,java]
-------------------------------------------------------------------------------
--public final class ConfigManagementSupport{
--
-- private JMXSupport(){}
--
-- public static ObjectName registerMBean();
-- public static ObjectName registerMBean(String context);
-- public static ObjectName unregisterMBean();
-- public static ObjectName unregisterMBean(String context);
--}
-------------------------------------------------------------------------------
--
--* +registerMBean+ creates a new +ManagedConfigMBean+ instance using the +ServiceContextManager+
-- and registers it. Optionally an additional _context_ parameter can be passed, which allows
-- to register the management bean for different classloaders, e.g. for different
-- ears.
--* +unregisterMBean+ does the oppsite than registering obviously.
--
--NOTE: The instance of +ManagedConfigMBean+ to be created and registered is evaluated by use og the
-- +ServiceContextManager+. So you can replace the bean implementation by registering your
-- overriding implementation using the current +ServiceContext+ (by default using
-- +java.util.ServiceLoader+ and +@Priority+ annotation.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_metamodel.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_metamodel.adoc
index ed03b25,ed03b25..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_metamodel.adoc
+++ /dev/null
@@@ -1,632 -1,632 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Metamodel (Configuration of Tamaya)
--
--toc::[]
--
--
--[[Model]]
--== Tamaya Metamodel (Configuration of Tamaya) (Extension Module)
--
--Tamaya _metamodel_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--The Tamaya _metamodel_ module provides support for configuring the Tamaya system itself. It
--allows, like a logging configuration, to configure how your configuration framework should
--work, where to find configuration and how it is combined using overrides, filters etc.
--
--By default it uses an XML based configuration format as illustrated below:
--
--[source, xml]
--.Extract from `tamaya-config.xml`
-------------------------------------------------
--<configuration>
-- <!-- Context is evaluated first. -->
-- <context>
-- <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry>
-- <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry>
-- <context-entry name="app">${properties:system.APP?default=NONE}</context-entry>
-- <context-entry name="context">${java:org.apache.tamaya.context.Context#id()}</context-entry>
-- <context-entry name="company">Trivadis</context-entry>
-- <context-entry name="default-formats">yaml,json</context-entry>
-- <context-entry name="default-refresh-period">5 SECOND</context-entry>
-- </context>
--
-- <!-- combinationPolicy type="" / -->
--
-- <!-- Configuration definition. -->
--
-- <sources>
-- <source enabled="${stage=TEST || stage=PTA || stage=PROD}"
-- type="env-properties">
-- <filter type="PropertyMapping">
-- <param name="mapTarget">ENV.</param>
-- </filter>
-- <filter type="AccessMask">
-- <param name="roles">admin,power-user</param>
-- <param name="policy">mask</param>
-- <param name="mask">*****</param>
-- <param name="matchExpression">SEC_</param>
-- </filter>
-- </source>
-- <source type="sys-properties" >
-- <filter type="ImmutablePropertySource" />
-- </source>
-- <source type="file" refreshable="true">
-- <name>config.json</name>
-- <param name="location">config.json</param>
-- </source>
-- ...
-- </sources>
--</configuration>
-------------------------------------------------
--
--The module basically provides an XML representation to the +ConfigBuilder+ API.
--It creates and registers the corresponding +Config+
--as the system's _default_ configuration (accessible from `ConfigProvider.getConfig(ClassLoader cl)`.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _metamodel_ features you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-model</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Creating a Configuration using Meta-Configuration
--
--The basic feature of this module is the capability of creating a +Config+ completely
--based on a meta-configuration file. For this the +MetaConfig+ main singleton
--provides different methods:
--
--[source, java)
-------------------------------------------------
--public final class MetaConfig {
-- public static void configure();
-- public static void configure(URL metaConfig);
-- public static ConfigBuilder createBuilder(URL metaConfig);
-- public static Config createConfiguration(URL metaConfig);
-------------------------------------------------
--
--* If you have supplied your meta-configuration at `META-INF/tamaya-config.xml` you simply
-- call +MetaConfig.configure();+. This will read the meta-configuration and
-- configure Tamaya's _default_ configuration. Alternatively you can choose your own
-- metaconfiguration location by passing an alternate `URL` ro read from.
--* With +MetaConfiguration.createContextBuilder()+ you can stop a step earlier: a new
-- instance of +ConfigBuilder+ is created and configured with all the
-- entries found in your meta-configuration. Also here you can optionally pass your
-- custom location for the meta-configuration resouce.
--* Finally +MetaConfig.createConfig(URL)+ allows you to create an
-- arbitrary +Config+ instance using a meta-configuration file. The `Config`
-- instance is completely independent and not registered as _default_ configuration, so
-- it's lifecycle and usage is completely under your control.
--
--
--=== MetaContext
--
--When thinking what are the various input parameters for determining a correct configuration, there
--might be different things relevant in different scenarios, especially for developers in different
--companies. A good example of such an input parameter is the current `STAGE`. All these kinf od inputs
--can be summarized in some sort of meta-configuration, commonly known as a _context_. So
--the metamodel extension ships with a +MetaContext+ class that allows to define a common meta-context,
--that can be accessed by components as needed to determine the correct settings to be applied:
--
--[source, java)
-------------------------------------------------
--public final class MetaContext {
--
-- ...
--
-- public static MetaContext getInstance(String contextName);
--
-- /**
-- * Access the default context. Contexts are managed as weak references in this class. If no
-- * such context exists, a new instance is created.
-- * @return the context instance, never null.
-- */
-- public static MetaContext getDefaultInstance();
--
-- /**
-- * Access a context by name. Contexts are managed as weak references in this class. If no
-- * such valid context exists, a new instance is created, using the given {@code validSupplier}.
-- * @param contextName the context name, not null.
-- * @return the context instance, never null.
-- */
-- public static MetaContext getInstance(String contextName, Supplier<Boolean> validSupplier);
--
-- /**
-- * Access the thread-based context. If no such context
-- * exists a new one will be created.
-- * @param reinit if true, clear's the thread's context.
-- * @return the corresponding context, never null.
-- */
-- public static MetaContext getThreadInstance(boolean reinit);
--
-- /**
-- * Access the current context, which actually is the current context, combined with the thread based
-- * context (overriding).
-- * @return the corresponding context, never null.
-- */
-- public MetaContext getCurrentInstance();
--
-- /**
-- * Access the current context, which actually is the current context, combined with the thread based
-- * context (overriding).
-- * @param reinit if true, clear's the thread's context.
-- * @return the corresponding context, never null.
-- */
-- public MetaContext getCurrentInstance(boolean reinit);
--
--
-- /**
-- * Method to evaluate if a context is valid. This basically depends on the
-- * {@code validSupplier}, if any is set. If no supplier is present the context is valid.
-- *
-- * @return true, if this context is valid.
-- */
-- public boolean isValid();
--
-- /**
-- * Combine this context with the other contexts given, hereby only contexts are included
-- * which are {@code valid}, see {@link #isValid()}.
-- * @param contexts the context to merge with this context.
-- * @return the newly created Context.
-- */
-- public MetaContext combineWith(MetaContext... contexts);
--
-- /**
-- * Access the given context property.
-- * @param key the key, not null
-- * @return the value, or null.
-- */
-- public String getProperty(String key);
--
-- /**
-- * Access the given context property.
-- * @param key the key, not the default value.
-- * @param defaultValue the default value to be returned, if no value is defined, or the
-- * stored value's TTL has been reached.
-- * @return the value, default value or null.
-- */
-- public String getProperty(String key, String defaultValue);
--
-- /**
-- * Sets the given context property.
-- * @param key the key, not null.
-- * @param value the value, not null.
-- * @return the porevious value, or null.
-- */
-- public String setProperty(String key, String value);
--
-- /**
-- * Sets the given context property.
-- * @param key the key, not null.
-- * @param value the value, not null.
-- * @param ttl the time to live. Zero or less than zero means, no timeout.
-- * @param unit the target time unit.
-- * @return the porevious value, or null.
-- */
-- public String setProperty(String key, String value, int ttl, TimeUnit unit);
--
-- /**
-- * Sets the given property unless there is already a value defined.
-- * @param key the key, not null.
-- * @param value the value, not null.
-- */
-- public void setPropertyIfAbsent(String key, String value);
--
-- /**
-- * Sets the given property unless there is already a value defined.
-- * @param key the key, not null.
-- * @param value the value, not null.
-- * @param ttl the time to live. Zero or less than zero means, no timeout.
-- * @param unit the target time unit.
-- */
-- public void setPropertyIfAbsent(String key, String value, long ttl, TimeUnit unit);
--
-- /**
-- * Adds all properties given, overriding any existing properties.
-- * @param properties the properties, not null.
-- */
-- public void setProperties(Map<String,String> properties);
--
-- /**
-- * Adds all properties given, overriding any existing properties.
-- * @param properties the properties, not null.
-- * @param ttl the time to live. Zero or less than zero means, no timeout.
-- * @param unit the target time unit.
-- */
-- public void setProperties(Map<String,String> properties, long ttl, TimeUnit unit);
--
-- /**
-- * Checks if all the given properties are present.
-- * @param keys the keys to check, not null.
-- * @return true, if all the given keys are existing.
-- */
-- public boolean checkProperties(String... keys);
--
-- /**
-- * Access all the current context properties.
-- * @return the properties, never null.
-- */
-- public Map<String,String> getProperties();
--}
-------------------------------------------------
--
--As you see, a +MetaContext+ has the following aspects:
--
--* there are multiple context's possible, identified by their name.
--* Accessing an instance that does not yet exist, will create a new one.
--* there is one shared _default_ instance.
--* they store ordinary `String,String` key, value pairs.
--* they can be _combined_ into a overriging hierarchy
--* accessing the _default_ MetaContext returns the global instance combined with
-- a threaded override instance. Passing `reinit` will clear the thread instance's
-- data.
--
--
--==== Configuring MetaContexts
--
--`MetaContext` instances can be configured in the _meta-configuration_ in the first
--`meta-context` section as illustrated below:
--
--[source, xml]
-------------------------------------------------
--<!-- Configuring the default context -->
--<context>
-- <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry>
-- <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry>
-- <context-entry name="app">${properties:system.APP?default=NONE}</context-entry>
-- <context-entry name="context">${java:org.apache.tamaya.context.Context#id()}</context-entry>
-- <context-entry name="company">Trivadis</context-entry>
-- <context-entry name="default-formats">yaml,json</context-entry>
-- <context-entry name="default-refresh-period">5 SECOND</context-entry>
--</context>
--<!-- Configuring a context named 'APP' -->
--<context name="APP">
-- <context-entry name="application">someAppName</context-entry>
--</context>
-------------------------------------------------
--
--As shown above multiple contexts can be configured. Keys and values are of type `String`.
--
--
--===== Using Expressions
--
--As shown before, it is possible to add simple expressions, enclosed in `${}`. Hereby the
--contents must be formatted as `evaluator:expression`, which then internally must be interpreted by
--the +org.apache.tamaya.metamodel.internal.SimpleResolver+, which effectively reads and
--applied context entries.
--
--Currently the following placeholders for context entries are provided:
--
--* properties - mapping to system properties (`properties:sys:KEY`) or
-- environment properties (`properties:env:KEY`) or other MetaContext
-- entries initialized already (`properties:ctx[:CTXNAME]:KEY`)
--* java - mapping to a static method or field, returning a `String` value.
--
--
--=== General Extensions
--
--Working with meta-models requires additional aspects to be generalized to separate
--concerns and reuse some of the common functionality. These concepts are shown in the following
--subsections.
--
--=== Enabled
--
--Things can be dynamically enabled or disabled, e.g. based on context. This can be
--modelled by the +Enabled+ interface:
--
--[source, java]
-------------------------------------------------
--public interface Enabled {
--
-- /**
-- * Returns the enabled property.
-- * @return the enabled value.
-- */
-- boolean isEnabled();
--
-- /**
-- * Enables/disables this property source.
-- * @param enabled the enabled value.
-- */
-- void setEnabled(boolean enabled);
--}
-------------------------------------------------
--
--+Enabled+ can be used as a mixin-logic, e.g. for decorating property sources,
--property source providers, filters and converters. The decorator can also, if not
--set explicitly, evaluate the _enabled_ property based on the current runtime
--context.
--
--
--=== Refreshable
--
--Similar to _Enabled_ things can also be refreshable.
--
--[source, java]
-------------------------------------------------
--public interface Refreshable {
--
-- /**
-- * Refreshes the given instance.
-- */
-- void refresh();
--}
-------------------------------------------------
--
--This can be used to define a common API for refreshing artifctas. Similar to
--_Enabled_ this can be applied as a decorator/mix-in interface to property
--sources and property source providers. This property also is supported in the
--XML metaconfiguration, e.g.
--
--[source, xml]
-------------------------------------------------
--<sources>
-- <source type="file" refreshable="true">
-- <name>config.json</name>
-- <param name="location">config.json</param>
-- </source>
--</sources>
-------------------------------------------------
--
--
--=== The MetaConfiguration XML Structure
--
--In general the `tamaya-config.xml` file does never apply an XML schema or
--similar. Nevertheless there is a common DSL structure, which can be extended
--as well (see next chapter).
--
--[source, xml]
-------------------------------------------------
--<configuration>
-- <!-- PART ONE: Contexts initialization. -->
-- <context>
-- <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry>
-- <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry>
-- ...
-- </context>
-- <context name="APP">
-- <context-entry name="application">someAppName</context-entry>
-- </context>
--
-- <!-- PART TWO: Global settings of ConfigurationContext. -->
-- <!-- combinationPolicy type="" / -->
--
-- <!-- PART THREE: Configuration definition. -->
--
-- <sources>
-- <source enabled="${stage=TEST || stage=PTA || stage=PROD}"
-- type="env-properties">
-- <filter type="PropertyMapping">
-- <param name="mapTarget">ENV.</param>
-- </filter>
-- <filter type="AccessMask">
-- <param name="roles">admin,power-user</param>
-- <param name="policy">mask</param>
-- <param name="mask">*****</param>
-- <param name="matchExpression">SEC_</param>
-- </filter>
-- </source>
-- <source type="sys-properties" >
-- <filter type="ImmutablePropertySource" />
-- </source>
-- <source type="file" refreshable="true">
-- <name>config.json</name>
-- <param name="location">config.json</param>
-- </source>
-- <source type="file" refreshable="true">
-- <name>config.xml</name>
-- <param name="location">config.xml</param>
-- <param name="formats">xml-properties</param>
-- </source>
-- <source-provider type="resource">
-- <name>classpath:application-config.yml</name>
-- <param name="location">/META-INF/application-config.yml</param>
-- </source-provider>
-- <source type="ch.mypack.MyClassSource" />
-- <!--<include enabled="${stage==TEST}">TEST-config.xml</include>-->
-- <source-provider type="resource" enabled="${configdir != null}">
-- <name>config-dir</name>
-- <param name="location">/${configdir}/**/*.json</param>
-- </source-provider>
-- <source type="url" refreshable="true">
-- <name>remote</name>
-- <param name="location">https://www.confdrive.com/cfg/customerId=1234</param>
-- <param name="formats">json</param>
-- <filter type="CachedPropertySource">
-- <param name="ttl">30 SECOND</param>
-- </filter>
-- </source>
-- </sources>
-- <filters>
-- <filter type="UsageTrackerFilter"/>
-- <filter type="AccessControl">
-- <param name="roles">admin,power-user</param>
-- <param name="policy">hide</param>
-- <param name="expression">*.secret</param>
-- </filter>
-- <filter type="Cache">
-- <param name="ttl">30000</param>
-- <param name="expression">cached.*</param>
-- </filter>
-- </filters>
-- <converters>
-- <!--<converter type="AllInOneConverter"/>-->
-- <default-converters/>
-- </converters>
--</configuration>
-------------------------------------------------
--
--The different parts in fact are not hardcoded, but implemented
--as independent components, where each of them gets access to the
--XML DOM tree to read the configuration aspects of interest.
--Instances related must implement the ++ interface and register it to
--the `ServiceContext`. Reading order is mapped using `@Priority`
--annotations.
--For further details refer to the SPI section in this document.
--
--
--== Model SPI
--
--=== Extending the XML DSL
--
--The XML DSL can be extended in various ways:
--
--* Basically adding a new feature maps to adding a new section to the
-- meta-config XML. This can be easily done, by implementing +MetaConfigurationReader+
-- and do whatever is appropriate for your use case.
--* For adding new expression capabilities for `MetaContext`entries +SimpleResolver+ must
-- be implemented.
--* For allowing customized parameterization of artifacts, e.g. property sources,
-- property source providers, converters and filters etc. you may implement +ItemFactory+
-- instances.
--
--=== MetaConfigurationReader
--
--XML metaconfiguration is effectively processed by instances of
--type +org.apache.tamaya.metamodel.spi.MetaConfigurationReader+:
--
--[source,java]
-------------------------------------------------------------
--public interface MetaConfigReader {
--
-- /**
-- * Reads meta-configuration from the given document and configures the current
-- * context builder. The priority of readers is determined by the priorization policy
-- * implemented by the {@link org.apache.tamaya.spi.ServiceContext},
-- * @param document the meta-configuration document
-- * @param configBuilder the config builder to use.
-- */
-- void read(Document document, ConfigBuilder configBuilder);
--
-- }
-------------------------------------------------------------
--
--Hereby we also see that an instance of `ConfigBuilder` is passed.
--Remember, we mentioned earlier that meta-configuration basically is a XML
--API to the building a configuration using a +ConfigBuilder+. So
--all you can do with the meta-config XML can also be done programmatically using
--the Java API.
--
--This module provides instances of this class for reading of meta-context,
--property-sources, property source providers, converters, filters and more.
--Look into the +org.apache.tamaya.metamodel.internal+ package for further details.
--
--New instances implementing this interface must be registered into the current
--+ServiceContext+, by default the +ServiceLoader+ is used.
--
--
--=== ItemFactory
--
--Instances of +ItemFactory+ allow to configure artifacts using XML data:
--
--[source, java]
-------------------------------------------------------------
--public interface ItemFactory<T> {
--
-- /**
-- * Get the factory name.
-- * @return the factory name, not null.
-- */
-- String getName();
--
-- /**
-- * Create a new instance.
-- * @param parameters the parameters for configuring the instance.
-- * @return the new instance, not null.
-- */
-- T create(Map<String,String> parameters);
--
-- /**
-- * Get the target type created by this factory. This can be used to
-- * assign the factory to an acording item base type, e.g. a PropertySource,
-- * PropertySourceProvider, PropertyFilter etc.
-- * @return the target type, not null.
-- */
-- Class<? extends T> getArea();
--
--}
-------------------------------------------------------------
--
--The factory's name hereby is used as a short cut, e.g. have a look at the following
--XML snippet defining a `PropertySource` to be added:
--
--[source, xml]
-------------------------------------------------------------
--<source type="file" refreshable="true">
-- <name>config.json</name>
-- <param name="location">config.json</param>
--</source>
-------------------------------------------------------------
--
--In the above snippet _file_ equals to the factory name, which provides the user
--a simple to use short name, instead of adding the fully qualified classname
--(which is always possible).
--
--The _location_ paramter with its value is passed as `Map` to the `create` method.
--
--
--=== ItemFactoryManager
--
--This singleton class manages the _ItemFactory_ instances found, hereby allowing
--accessing and registering instances. This singleton is actually used by the
--component parsers (type `MetaConfigurationReader`).
--
--[source, java]
-------------------------------------------------------------
--public final class ItemFactoryManager {
--
-- ...
--
-- public static ItemFactoryManager getInstance();
--
-- public <T> List<ItemFactory<T>> getFactories(Class<T> type);
-- public <T> ItemFactory<T> getFactory(Class<T> type, String id);
--
-- public <T> void registerItemFactory(ItemFactory<T> factory);
--
--}
-------------------------------------------------------------
--
--
--=== Extended Implementations
--
--The package +org.apache.tamaya.metamodel.ext+ contains a few useful
--implementations that also can be used in your meta-configuration and
--show how mixin-functionality can be added without touching property source
--implementations.
--
--As of now the package contains
--
--* +EnabledPropertySource+: a decorator for a `PropertySource`
-- adding the capability to _enable/disable_ the property source.
--* +EnabledPropertySourceProvider+ a decorator for a `PropertySourceProvider`
-- adding the capability to _enable/disable_ the property source provider.
--* +RefreshablePropertySource+: a decorator for a `PropertySource`
-- adding the capability to _refresh_ the property source.
--* +EnabledPropertySourceProvider+ a decorator for a `PropertySourceProvider`
-- adding the capability to _refresh_ the property source provider.
--
--Not yet implemented but planned are implementations to add the following
--functionality:
--
--* _caching_ of entries for a given time.
--* _immutability_ of entries, so a configuration data (or parts of it) will
-- never change later.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_mutable_config.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_mutable_config.adoc
index 478acee,478acee..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_mutable_config.adoc
+++ /dev/null
@@@ -1,236 -1,236 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Mutable Configuration
--
--toc::[]
--
--
--[[MutableConfiguration]]
--== Tamaya Mutable Configuration (Extension Module)
--
--Tamaya _Mutable Configuration_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--+Config+ instances by default are read-only, which covers must of the use cases. But there are many legit scenarios
--where configuration should be written back to backend systems or the local file system. This module adds this
--functionality.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--
--=== Installation
--
--To benefit from configuration mutability support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-mutable-config</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Core Architecture
--
--==== Accessing MutableConfig
--
--The core of the module is the +MutableConfigProider+ singleton, which provides access to +MutableConfig+
--instance, which extends +Config+. This interface adds additional methods to add/update or remove property values.
--Hereby each +MutableConfig+ manages a transaction like context, which includes
--a UUID that identifes a change.
--Backends for writing changes applied umst implement +MutableConfigSource+, which extends +ConfigSource+.
--Registrations and ordering policies are exact the same as with ordinary config sources, but
--mutable property sources can be targeted by config write operations.
--
--The example below shows how a +MutableConfig+ can be obtained ,values added, removed and
--finally changes written back to the backend:
--
--[source,java]
--.Accessing and changing configuration
----------------------------------------------
--MutableConfig config = MutableConfigProvider
-- .createMutableConfig();
--config.put("newKey", "newValue")
-- .put("anotherKey", "updatedValue")
-- .remove("valueNotValid")
-- .store();
----------------------------------------------
--
--In the above scenario we use the system's _default_ configuration as the backend to be used.
--We can also pass any +Config+ to render it into a mutable instance, e.g.
--
--[source,java]
--.Explicitly passing the backing configuration
----------------------------------------------
--Config config = ...;
--MutableConfig config = MutableConfigProvider
-- .createMutableConfig(config);
----------------------------------------------
--
--NOTE: If a configuration does not contain any +MutableConfigSource+ instances,
-- a +IllegalArgumentException+ is thrown since it would not be able to accept
-- any changes.
--
--
--Following we show the possible methods you can use to create a +MutableConfig+.
--We will show in the following sections more details on the options provided...
--
--[source, java]
-----------------------------------------------
--public final class MutableConfigProvider {
--
-- private MutableConfigProvider(){}
--
-- public static MutableConfig createMutableConfig();
-- public static MutableConfig createMutableConfig(
-- ChangePropagationPolicy changePropgationPolicy);
-- public static MutableConfig createMutableConfig(Config configuration);
-- public static MutableConfig createMutableConfig(
-- Config configuration,
-- ChangePropagationPolicy changePropgationPolicy);
--
-- [...]
--}
-----------------------------------------------
--
--As we have not yet shown it, +MutableConfiguration+ is defined as follows:
--
--[source, java]
-----------------------------------------------
--public interface MutableConfig extends Config {
--
-- void store();
--
-- ConfigChangeRequest getConfigChangeRequest();
-- ChangePropagationPolicy getChangePropagationPolicy();
--
-- MutableConfig put(String key, String value);
-- MutableConfig putAll(Map<String, String> properties);
-- MutableConfig remove(Collection<String> keys);
-- MutableConfig remove(String... keys);
--
--}
-----------------------------------------------
--
--
--===== Targeting specific MutableConfigSources
--
--A +Config+ may have multiple +MutableConfigSource+ instances present. These are members of Tamaya's ordered list of
--+ConfigSources+ to evaluate the configuration. Nevertheless writing back changes requires additional aspects to
--be considered:
--* Should changes written target all mutable config sources? Or should a change only
-- target the most significant instance (hereby not writing the change to less significant config sources)?
--* Or should a change be applied only to specific mutable config source(s), regardless its position in the
-- processing chain?
--
--Therefore a _default_ +ChangePropagationPolicy+ can be applied on a +MutableConfig+ instance, which allows to
--control this aspect:
--
--[source,java]
--.Explicitly passing the backing configuration
----------------------------------------------
--public interface ChangePropagationPolicy {
-- /**
-- * Method being called when a multiple key/value pairs are added or updated.
-- * @param configSources all config sources, including read-only config sources, of the current configuration,
-- * never null.
-- * @param configChange the configuration change, not null.
-- */
-- void applyChange(ConfigChangeRequest configChange, Collection<ConfigSource> configSources);
--}
----------------------------------------------
--
--By default, changes are applied to all registered +MutableConfigSource+ instances
--similarly.
--
--The +MutableConfigProvider+ singleton also provides the most common
--change propagation policy implementations:
--
--[source, java]
-----------------------------------------------
--public final class MutableConfigProvider {
--
-- [...]
--
-- public static ChangePropagationPolicy getApplyAllChangePolicy();
-- public static ChangePropagationPolicy getApplyMostSignificantOnlyChangePolicy();
-- public static ChangePropagationPolicy getApplySelectiveChangePolicy(String... propertySourceNames);
-- public static ChangePropagationPolicy getApplyNonePolicy();
--}
-----------------------------------------------
--
--
--==== Some Aspects to consider
--
--Due to Tamaya's design the effective effect of your changes to the overall configuration, cannot
--be sometimes a bit tricky to be predicted, since it depends on several aspects:
--
--. is the corresponding configuration resource configured as part of the current system's configuration?
--. what is the +PropertySource's+ priority within the configuration context? Is it overriding or overridden
-- by other sources?
--. is the change directly visible to the configuration system? E.g. injected values are normally not updated,
-- whereas injecting a +DynamicValue<T>+ instance allows to detect and react single value changes. Also the
-- +PropertySources+ implementation must be able to detect any configuration changes and adapt its values returned
-- accordingly. Finally values also can be marked as immutable or being cached.
--. Is configuration cached, or written/collected directly on access?
--. can the changes applied be committed at all?
--
--So it is part of your application configuration design to clearly define, which property sources may be read-only, which
--may be mutable, how overriding should work and to which backends finally any changes should be written back.
--
--
--=== Configuration Changes
--
--This module does not handle detection of changes to the overall system's +Config+. This can be done in
--several ways, e.g. by:
--
--* using the _tamaya-events_ extension, which can be used to observe the system's configuration and
-- publishing events when things have been changed.
--* The SPI implementing the +MutableConfigBackendSpi+ may inform/update any affected +ConfigSource,
-- ConfigSourceProvider+ instances about the changes applied.
--
--
--=== Supported Backends
--
--Multiple backends are supported. E.g. _tamaya-etcd_ also registers
--corresponding SPI implementations/backends. This module comes with
--the following +MutableConfigSource+ implementations:
--
--* +MutablePropertiesConfigSource+ resources, targeting local +.properties+ files, using the +java.util.Properties+
-- format.
--* +MutableXmlPropertiesConfigSource+ resources, targeting local +.xml+ property files, using the +java.util.Properties+
-- XML format.
--
--
--=== SPIs
--
--The module defines +MutableConfigProviderSpi+, that is used as a delegate by the +MutableConfigProvider+
--singleton accessor:
--
--[source,java]
--.SPI: MutableConfigurationProviderSpi
----------------------------------------------------
--public interface MutableConfigProviderSpi {
-- /**
-- * Creates a new {@link MutableConfig} with {@code autoCommit = false} as default.
-- *
-- * @param configuration the configuration, not null.
-- * @param propagationPolicy policy that defines how changes are published to the property
-- * sources.
-- * @return a new mutable configuration instance.
-- */
-- MutableConfig createMutableConfig(Config configuration,
-- ChangePropagationPolicy propagationPolicy);
--}
----------------------------------------------------
--
--Implementations are registered with the current +ServiceContext+ (using by default the
-- +java.util.ServiceLoader+ service).
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_optional.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_optional.adoc
index 29ed2fc,29ed2fc..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_optional.adoc
+++ /dev/null
@@@ -1,61 -1,61 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Optional Tamaya Configuration
--
--toc::[]
--
--
--[[Optional]]
--== Tamaya Optional (Extension Module)
--
--Tamaya _Optional_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Optional_ is for projects that want to benefit from Tamaya configuration optionally only.
--E.g. doing an OSS project you can declare to support configuration with Tamaya as
--an optional extension. This module can be added as a hard dependency to your code, hereby adding only
--three artifacts. The _optional_ module automatically checks the availability of Tamaya on the
--classpath and only if available it tries to access it for configuration evaluation.
--Additionally an +EvaluationPolicy+ lets you define the precedence of configured values
--(yours, or Tamaya ones, if present).
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use Tamaya _optional_ you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-optional</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Reading configuration using the Tamaya Optional Module
--
--Tamaya _Optional_ allows reading configuration with a small subset of functionality only. For more
-- advanced use cases consider using the Apache Tamaya as your main configuration API. When
-- creating your +OptionalConfiguration+ instance you also pass the logic to access a value
-- with your own configuration logic. Tamaya Optional will delegate to your logic as needed
-- (depending on the `EvaluationPolicy`).
--
--[source, java]
-------------------------------------------------
--BigDecimal interestRate =
-- OptionalConfiguration.of(
-- EvaluationPolicy.TAMAYA_OVERRIDES_OTHER,
-- (k) -> MyConfigMechanism.get(k) // String get(String key);
-- )
-- .get("com.mycomp.ratecalculator.rate", BigDecimal.class))
-- .orElse(BigDecimal.of(0.05d));
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_osgi.adoc
index d075ac1,d075ac1..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_osgi.adoc
+++ /dev/null
@@@ -1,814 -1,814 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extensions: OSGI Integration
--
--toc::[]
--
--
--[[OSGI]]
--== Tamaya OSGI Support
--
--Tamaya _OSGI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _OSGI_ provides support for integration with OSGI. Hereby Tamaya does actively override or extend the OSGI
--+ConfigAdmin+ based configuration with entries stored and managed by Tamaya. Tamaya provides also shell extensions
--to enable/perform configuration loading and restoring actions.
--Optionally Tamaya also provides extension for automatically trigger configuration updates, when configuration has
--been changed and configuration injection using Tamaya's injection API.
--
--
--=== Compatibility
--
--All module described are based on Java 8, so it will run on Java 8 and beyond.
--The modules are built against *OSGI Compendium version 5.0*. Tamaya OSGI support
--is tested against the following OSGI runtimes:
--
--* Apache Karaf, version 4.0.7
--* Apache Felix, version 5.6.1
--* Eclipse Equinox, version x.x.x.
--
--
--=== Installation
--
--To benefit from Tamaya in an OSGI context you must deploy at least the following modules to
--your OSGI runtime environment:
--
--[source, listing]
-------------------------------------------------
--# Runtime with OSGI ConfigAdmin support, e.g.
--org.apache.felix:org.apache.felix.configadmin:{felix_version}
--# API and core
--org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0
--org.apache.tamaya:tamaya-api:{tamaya_version}
--org.apache.tamaya:tamaya-spisupport:{tamaya_version}
--org.apache.tamaya:tamaya-core:{tamaya_version}
--# Required extensions
--org.apache.tamaya.ext:tamaya-functions:{tamaya_version}
--org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}
-------------------------------------------------
--
--
--=== Tamaya Service Loading in OSGI
--
--Important to know is that within OSGI class- and resource loading is not compatible with standard Java SE. Also
--in OSGI, bundles can be loaded or unloaded at any time, so Tamaya's logic must cope with this as well.
--These constraints are handled by Tamaya (implemented in +tamaya-core+ and +tamaya-osgi+) as follows:
--
--* Tamaya registers a +OSGIServiceContext+ which reads all +java.util.ServiceLoader+ configurations and
-- registers them as OSGI services. Hereby integration is two-way: The core module contains an
-- OSGI +Activator+ that replaces Tamaya's default +ServiceContext+ with an OSGI based implementation that
-- will consume all services from the OSGI service API. Consequently you can also register Tamaya extensions
-- as OSGI services using standard OSGI tooling (e.g. your own +PropertySource+ instances). Tamaya hereby
-- also does not store any service references, so the dynamic nature of OSGI is fully honored.
--* Tamaya's +ServiceContext+ SPI does additionally provide functionality for loading of (classpath)
-- resources using the bundle's +getEntry(String)+ method.
--* Tamaya similarly checks the classpath of all bundles for Tamaya SPI services to be registered thus
-- implementing the +ServiceLoader+ logic in OSGI. Hereby Tamaya will only register services with the
-- +org.apache.tamaya+ as root package.
--
--NOTE: Tamaya actually does not replace any existing +ConfigAdmin+ component, Tamaya modifies any existing OSGI
-- configuration on changes detected and stores backups of any OSGI configuration before applying any
-- changes.
--
--=== Configuring Bundles
--==== Mapping of pids and factoryPids
--
--When accessing configuration from the OSGI +ConfigAdmin+ a pid and an optional location can be provided.
--Tamaya requires all configuration for a PID to be located in keys starting [PID]:
--
--[source, listing]
--.OSGI pid mapping
-------------------------------------------------
--# OSGI settings
--pid=myBundle
--key=common.net.port
--
--# Corresponding key in Tamaya configuration
--[myBundle]key=common.net.port
-------------------------------------------------
--
--==== Enabling/Disabling Tamaya
--
--By default, Tamaya doesn't do anything, unless it is told to so so. So having installed the Tamaya OSGI plugin,
--you will see the bundles are loaded, but your OSGI environment still works the same. This is not accidentally, since
--configuration is a crucial part. This means Tamaya, by default, is disabled for all bundles. You have now several
--options to enabled Tamaya:
--
--* you can enable Tamaya for *all* bundles by default by
-- ** setting the +-Dtamaya-enabled=true+ system property.
-- ** by setting +tamaya-enabled=true+ in the OSGI Configuration for the PID +TamayaConfigPlugin+.
--* you can enable Tamaya for a single bundle by
-- ** by setting +tamaya-enabled=true+ in the OSGI Configuration for the given bundle.
-- ** by adding +Tamaya-Enabled: true+ to the bundle's MANIFEST.
--
--Similarly you can also combine these options the other way round:
--
--* You can enable Tamaya by default as shown above.
--* You can disable Tamaya for bundles by
-- ** by setting +tamaya-enabled=false+ in the OSGI Configuration for the given bundle.
-- ** by adding +Tamaya-Enabled: false+ to the bundle's MANIFEST.
--
--
--==== Controlling How Tamaya changes your OSGI Configuration
--
--Tamaya supports different policies that define how Tamaya is changing the OSGI configuration:
--
--* *EXTEND*: Only add properties not existing in the OSGI configuration, but never override
-- or remove existing properties.
--* *OVERRIDE*: Override existing properties and also add new properties.
--* *UPDATE_ONLY*: Only override existing properties but do not add any properties.
--
--By default, Tamaya uses the _OVERRIDE_ policy. Also this policy can be configured in several
--ways and with different scopes:
--
--* You can define the _default_ policy applied, by
-- ** setting the +-Dtamaya-policy=POLICY+ system property.
-- ** by setting +tamaya-policy=POLICY+ in the OSGI Configuration for the PID +TamayaConfigPlugin+.
--
--Hereby, _POLICY_ must be one of +OVERRIDE, EXTEND, UPDATE_ONLY+.
--
--* You can also configure the policy individually for a bundle by
-- ** by setting +tamaya-policy=POLICY+ in the OSGI Configuration for the given bundle.
-- ** by adding +Tamaya-Policy: POLICY+ to the bundle's MANIFEST.
--
--==== Mapping OSGI PIDs to Tamaya Configuration
--
--Tamaya configuration is a single +Map<String,String> with String keys and String values. Whereas OSGI configuration are
--multiple +Dictionary<String,?>+ (for several PIDs). The Tamaya OSGI extension implements the following mapping:
--
--As an example refer to the followinf Tamaya configuration entries:
--
--[source, listing]
--.Tamaya configuration for PID 'MyPlugin'
-------------------------------------------------
--[MyPlugin]ch.base.pack.Main.customer=Native Inc
--[MyPlugin]ch.base.pack.Main.use=234
--[MyPlugin]ch.base.pack.Main.encoding=UTF-8
-------------------------------------------------
--
--The OSGI Configuration Plugin now provides the following configuration for PID:
--
--[source, listing]
--.OSGI configuration for PID 'MyPlugin'
-------------------------------------------------
--ch.base.pack.Main.use=100 (Integer)
--ch.base.pack.Main.switch=on (Boolean)
--ch.base.pack.Main.customer=NONE (String)
-------------------------------------------------
--
--Now using +Policy.OVERRIDE+ (as desribed in the previous section), Tamaya will change the OSGI configuration
--as follows:
--
--[source, listing]
--.OSGI configuration after Tamaya update for PID 'MyPlugin'
-------------------------------------------------
--ch.base.pack.Main.use=234 (Integer)
--ch.base.pack.Main.switch=on (Boolean)
--ch.base.pack.Main.customer=Native Inc (String)
--[MyPlugin]ch.base.pack.Main.encoding=UTF-8 (String)
-------------------------------------------------
--
--So Tamaya configuration mapping can be summarized as follows:
--
--* The OSGI PID is mapped to a Tamaya prefix +[PID]+.
--* The OSGI keys are the exact same keys as from Tamaya with the _[PID]_ prefix removed.
--* New entries are added (depending on the +Policy+) as +String+ values.
--* Types of existing entries are preserved on update (this requires the Tamaya entries to be convertable into
-- the required target types. Refer to Tamaya's core documentation for supported types and how
-- to add custom converters).
--
--Finally, the mapping of the OSGI _PID_ to the Tamaya _[PID]_ prefix also can be customized by
--
--* adding +tamaya-config-root+ as an OSGI configuration property to the OSGI configuration.
--* adding +Tamaya-Config-Root+ as a MANIFEST entry to the bundle.
--
--The root will replace the default _[PID]_ prefix with the value configured.
--
--==== OSGI Configuration Backup
--
--Before Tamaya changes any OSGI configuration it creates a _Backup_ of the existing OSGI
--configuration dictionary and stores it in serialized form in the plugin's OSGI configuration.
--This allows you to restore the original OSGI configuration in case of problems. Hereby Tamaya
--automatically sets the +tamaya-enabled=false+ property to disable Tamaya for the given
--configuration (bundle).
--
--The history can be accessed from the Tamaya Configuration Plugin Service
--(shown later).
--
--==== OSGI Configuration Change Log
--
--All changes applied by Tamaya are logged as well using
--+ConfigHistory+ entry items. The history can be accessed from the Tamaya Configuration Plugin Service
--(shown later):
--
--[source, Java]
--.OSGI ConfigHistory Entry
-------------------------------------------------
--public final class ConfigHistory implements Serializable{
--
-- [...]
--
-- public enum TaskType{
-- PROPERTY,
-- BEGIN,
-- END,
-- }
--
-- // ***
-- // Entry = attributes
-- // ***
--
-- public TaskType getArea(){...}
--
-- public String getPid() {... }
--
-- public Object getPreviousValue() {... }
--
-- public ConfigHistory setPreviousValue(Object previousValue) {... }
--
-- public Object getValue() {...}
--
-- public ConfigHistory setValue(Object value) {...}
--
-- public String getKey() {...}
--
-- public ConfigHistory setKey(String key) {...}
--
--}
-------------------------------------------------
--
--==== The Tamaya OSGI Configuration Service
--
--As mentioned Tamaya exposes it's OSGI functionality, allowing programmatic access to Tamaya configuration
--logic with the +TamayaConfigService+ OSGI service:
--
--[source, Java]
--.The exposed +TamayaConfigService+
-------------------------------------------------
--public interface TamayaConfigService{
-- /** The system/config property to set Tamaya's {@link Policy}. */
-- String TAMAYA_POLICY_PROP = "tamaya-policy";
-- /** The MANIFEST property to set Tamaya's {@link Policy}. */
-- String TAMAYA_POLICY_MANIFEST = "Tamaya-Policy";
-- /** The system/config property to define a customized Tamaya's configuration root, replacing the {@code [PID]} default
-- * prefix used. */
-- String TAMAYA_CUSTOM_ROOT_PROP = "tamaya-config-root";
-- /** The MANIFEST property to define a customized Tamaya's configuration root, replacing the {@code [PID]} default
-- * prefix used. */
-- String TAMAYA_CUSTOM_ROOT_MANIFEST = "Tamaya-Config-Root";
-- /** The system/config property to enable Tamaya. */
-- String TAMAYA_ENABLED_PROP = "tamaya-enabled";
-- /** The MANIFEST property to enable Tamaya. */
-- String TAMAYA_ENABLED_MANIFEST = "Tamaya-Enabled";
-- /** The system/config property to enable Tamaya automatic updates (requires Tamaya's Updater plugin to be loaded as well). */
-- String TAMAYA_AUTO_UPDATE_ENABLED_PROP = "tamaya-update-enabled";
-- /** The MANIFEST property to enable Tamaya automatic updates (requires Tamaya's Updater plugin to be loaded as well). */
-- String TAMAYA_AUTO_UPDATE_ENABLED_MANIFEST = "Tamaya-Update-Enabled";
--
-- /**
-- * Enables/disables automatic updates (requires Tamaya's Updater plugin to be loaded as well).
-- * @param enabled set to true to enable updates.
-- */
-- void setAutoUpdateEnabled(boolean enabled);
--
-- /**
-- * Enables/disables Tamaya config by default.
-- * @param enabled set to true to enable Tamaya for all bundles by default.
-- */
-- void setTamayaEnabledByDefault(boolean enabled);
--
-- /**
-- * Get the flag, if Tamaya is enabled by default for all bundles.
-- * @return true if Tamaya is enabled.
-- */
-- boolean isTamayaEnabledByDefault();
--
-- /**
-- * Get the default policy Tamaya is using for adapting OSGI configuration.
-- * @return the default policy, never null.
-- */
-- Policy getDefaultPolicy();
--
-- /**
-- * Set the default policy Tamaya is using for adapting OSGI configuration.
-- * @param policy the policy, not null.
-- */
-- void setDefaultPolicy(Policy policy);
--
-- /**
-- * Updates the given OSGI configuration with Tamaya configuration.
-- * @param pid the target PID, not null.
-- * @return the new configuration.
-- */
-- Dictionary<String,Object> updateConfig(String pid);
--
-- /**
-- * Updates the given OSGI configuration with Tamaya configuration.
-- * @param pid the target PID, not null.
-- * @param dryRun if true, the changes will not be applied to the OSGI configuration.
-- * @return the configuration that would be applied, has been applied.
-- */
-- Dictionary<String,Object> updateConfig(String pid, boolean dryRun);
--
-- /**
-- * Updates the given OSGI configuration with Tamaya configuration.
-- * @param pid the target PID, not null.
-- * @param policy the updating policy to be used, by default.
-- * @param forcePolicy if set to true, the given policy will be used, even if an alternate policy is configured
-- * for the given PID.
-- * @param dryRun if true, the changes will not be applied to the OSGI configuration.
-- * @return the configuration that would be applied, has been applied.
-- */
-- Dictionary<String,Object> updateConfig(String pid, Policy policy, boolean forcePolicy, boolean dryRun);
--
-- /**
-- * Checks if a bundle is enabled for Tamaya configuration.
-- * @param bundle the bundle, not null.
-- * @return true, if the bundle is enabled.
-- */
-- boolean isBundleEnabled(Bundle bundle);
--
-- /**
-- * Get the flag if automatic updates for config changes are enabled.
-- * @return true, if automatic updates for config changes are enabled.
-- */
-- boolean isAutoUpdateEnabled();
--
-- /**
-- * Get the backup written for a PID.
-- * @param pid the pid, not null.
-- * @return the backup, or null, if no backup is present.
-- */
-- Dictionary<String,?> getBackup(String pid);
--
-- /**
-- * Get all current known PIDs for which backups are registered.
-- * @return all known PIDs for which backups are registered.
-- */
-- Set<String> getBackupPids();
--
-- /**
-- * Restores a backup, replacing the current OSGI configuration with the backup and
-- * disabling Tamaya for this PID.
-- * @param pid the PID, not null.
-- * @return true, if a backup has been restored successfully.
-- */
-- boolean restoreBackup(String pid);
--
-- /**
-- * Stores the current OSGI configuration as a backup (only if no backup is existing).
-- * @param pid the target PID, not null.
-- * @return true, if a backup has been stored successfully.
-- */
-- boolean createBackup(String pid);
--
-- /**
-- * Deletes a backup, if existing.
-- * @param pid the target PID, not null.
-- * @return true, if a backup has been restored successfully.
-- */
-- boolean deleteBackup(String pid);
--
-- /**
-- * Sets the maximum getHistory size.
-- * @param maxHistory the max getHistory size. {@code 0} disables the getHistory function.
-- */
-- void setMaxHistorySize(int maxHistory);
--
-- /**
-- * Get the max getHistory size.
-- * @return the max getHistory size. {@code 0} means the getHistory function is disabled.
-- */
-- int getMaxHistorySize();
--
-- /**
-- * Access the current (full) change getHistory.
-- * @return the current getHistory, never null.
-- */
-- List<ConfigHistory> getHistory();
--
-- /**
-- * Clears the getHistory.
-- */
-- void clearHistory();
--
-- /**
-- * Clears the getHistory for a PID.
-- * @param pid the target PID, not null.
-- */
-- void clearHistory(String pid);
--
-- /**
-- * Get the getHistory for a PID.
-- * @param pid the target PID, not null.
-- * @return the PID's getHistory, never null.
-- */
-- List<ConfigHistory> getHistory(String pid);
--
-- /**
-- * Access the current OSGI configuration for a PID.
-- * @param pid the target PID, not null.
-- * @param section a subsection to be filter (using startsWith).
-- * @return the (optionally filtered) OSGI configuration.
-- */
-- Dictionary<String,Object> getOSGIConfiguration(String pid, String section);
--
-- /**
-- * Checks if a backup exists.
-- * @param pid the target PID, not null.
-- * @return true, if a backup exists.
-- */
-- boolean containsBackup(String pid);
--}
-------------------------------------------------
--
--
--==== The Tamaya OSGI Configuration Service
--
--Finally Tamaya also provides support for using Tamaya's injection API with your OSGI project. To enable injection
--you must install a few additional bundles:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-osgi-injection</artifactId>
-- <version>${tamaya.version}</version>
--</dependency>
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-injection</artifactId>
-- <version>${tamaya.version}</version>
--</dependency>
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>injection-api</artifactId>
-- <version>${tamaya.version}</version>
--</dependency>
-------------------------------------------------
--
--Given that you can inject configuration entries
--
--* on your services by
-- ** setting +tamaya-config-inject=true+ in your service properties.
-- ** setting +Tamaya-Config-Inject: true+ in your bundle's manifest.
--* or by using the registered +ConfigInjectionService+:
--
--[source, java]
-------------------------------------------------
--public interface ConfigInjectionService {
-- /** The manifest entry to enable Tamaya injection. */
-- String TAMAYA_INJECTION_ENABLED_MANIFEST = "Tamaya-Config-Inject";
-- /** The OSGI config entry to enable Tamaya injection. */
-- String TAMAYA_INJECTION_ENABLED_PROP = "tamaya-config-inject";
--
-- /**
-- * Checks if injection is enabled on the given service.
-- * @param reference the service reference, not null.
-- * @return true, if enjection is enabled.
-- */
-- boolean isInjectionEnabled(ServiceReference reference);
--
-- /**
-- * Checks if injection is enabled on the given service.
-- * @param bundle the bundle, not null.
-- * @return true, if enjection is enabled.
-- */
-- boolean isInjectionEnabled(Bundle bundle);
--
-- /**
-- * Configures the passed instance.
-- * @param instance the instance, not null.
-- * @param <T> the input and return type.
-- * @param pid the target PID, not null.
-- * @param location the optional location
-- * @return the configured instance.
-- */
-- <T> T configure(String pid, String location, T instance);
--
-- /**
-- * Creates a suzpplier, which supplies events as created by the basic supplier, which are
-- * automatically configured, when supplying.
-- * @param supplier the base supplier, not null.
-- * @param pid the target PID, not null.
-- * @param location the optional location
-- * @param <T> the type
-- * @return a configuring supplier.
-- */
-- <T> Supplier<T> getConfiguredSupplier(String pid, String location, java.util.function.Supplier<T> supplier);
--
-- /**
-- * Creates a template implementing the annotated methods based on current configuration data.
-- *
-- * @param <T> the type of the template.
-- * @param templateType the type of the template to be created.
-- * @param pid the target PID, not null.
-- * @param location the optional location
-- * @return the configured template.
-- */
-- <T> T createTemplate(String pid, String location, Class<T> templateType);
--
-- /**
-- * Configures the passed instance.
-- * @param instance the instance, not null.
-- * @param <T> the input and return type.
-- * @param bundle the target bundle, not null.
-- * @return the configured instance.
-- */
-- <T> T configure(Bundle bundle, T instance);
--
-- /**
-- * Creates a suzpplier, which supplies events as created by the basic supplier, which are
-- * automatically configured, when supplying.
-- * @param supplier the base supplier, not null.
-- * @param bundle the target bundle, not null.
-- * @param <T> the type
-- * @return a configuring supplier.
-- */
-- <T> Supplier<T> getConfiguredSupplier(Bundle bundle, java.util.function.Supplier<T> supplier);
--
-- /**
-- * Creates a template implementing the annotated methods based on current configuration data.
-- *
-- * @param <T> the type of the template.
-- * @param templateType the type of the template to be created.
-- * @param bundle the target bundle, not null.
-- * @return the configured template.
-- */
-- <T> T createTemplate(Bundle bundle, Class<T> templateType);
--}
-------------------------------------------------
--
--NOTE: Injection hereby is based on the OSGI ConfigAdmin values only. To use Tamaya configuration you have to additionally
--install the Tamaya common OSGI support as described in the previous sections.
--
--More details on Tamaya's injection API can be found in the corresponding link:mod_injection.html[API documentation].
--
--=== Special OSGI Platform support
--
--==== Apache Karaf Shell
--
--Apache Tamaya provides a Karaf Shell Extension providing commands for performing several actions related
--to Tamaya configuration. To use them, simply add the +org.apache.tamaya.ext:tamaya-osgi-karaf-shell+ bundle
--to your OSGI runtime. The extension will add the following commands to your Karaf conaole (with prefix +tamaya+):
--
--[width="100%",frame="1",options="header",grid="all"]
--|=======
--|_Artifact_ |_Description_ |_Options_
--
--| +tm_apply_config+
--| Show the current Tamaya configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_apply_config [options] pid
--<b>ARGUMENTS</b>
--<i>pid</i> The target OSGI component PID.
--<b>OPTIONS</b>
--<i>operationMode, -m, --opmode</i> Explicitly set (override) the operation mode to use.
--<i>dryRun, -d, --dryrun</i> If set to true no OSGI configuration gets changed.
--</pre>
--+++
--
--| +tm_backup_create+
--| Creates a backup of a current OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_backup_create [options] pid
--<b>ARGUMENTS</b>
--<i>pid</i> The target pid to backup.
--<b>OPTIONS</b>
--<i>--force, -f</i> Forces to (over)write a backup, even if one already exists.
--</pre>
--+++
--
--| +tm_backup_delete+
--| Deletes the OSGI configuration backup of Tamya.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_backup_delete pid
--<b>ARGUMENTS</b>
--<i>pid</i> Allows to filter on the given PID. '*' removes all backups.
--</pre>
--+++
--
--| +tm_backup_list+
--| List the backed-up OSGI configuration before Tamya applied changes.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_backup_list [pid]
--<b>ARGUMENTS</b>
--<i>pid</i> Allows to filter on the given PID.
--</pre>
--+++
--
--| +tm_backup_restore+
--| Restores the OSGI configuration backup of Tamya and disabled the PID for Tamaya configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_backup_restore pid
--<b>ARGUMENTS</b>
--<i>pid</i> The target PID. '*' restores all backups.
--</pre>
--+++
--
--| +tm_config+
--| Show the current Tamaya configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_config [options]
--<b>OPTIONS</b>
--<i>pi, -p, --pid</i> Apply filtering for the given OSGI component PID.
--<i>section, -s, --section</i> A starting expression selecting the section to be filtered.
--</pre>
--+++
--
--| +tm_enable+
--| Enables or disable Tamaya by default for all bundles/services (default: enabled=false). Disabling still allows to explicitly enable
-- bundles using 'tamaya-enable' manifest or OSGI config entries.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_enable enabled
--<b>ARGUMENTS</b>
--<i>enabled</i> The boolean value to enabled/disable Tamaya by default.
--</pre>
--+++
--
--| +tm_enabled+
--| Check if Tamaya is currently by default enabled for all bundles/services (default: enabled=false). If disabled still Tamaya allows to
-- explicitly enable bundles using 'tamaya-enable' manifest or OSGI config entries.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_enabled
--</pre>
--+++
--
--| +tm_history+
--| Gets the getHistory of changes Tamaya applied to the OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history [options] [pid]
--<b>ARGUMENTS</b>
--<i>pid</i> Allows to filter on the given PID.
--<i>--type, -t</i> Allows to filter the events types shown.
--</pre>
--+++
--
--| +tm_history_delete+
--| Deletes the getHistory of changes Tamaya applied to the OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history_delete pid
--<b>ARGUMENTS</b>
--<i>pid</i> Allows to filter on the given PID.
--</pre>
--+++
--
--| +tm_history_delete_all+
--| Deletes the full getHistory of changes Tamaya applied to the OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history_delete_all
--</pre>
--+++
--
--
--| +tm_history_maxsize+
--| Gets the maximal size of stored getHistory entries.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history_maxsize
--</pre>
--+++
--
--| +tm_history_maxsize_set+
--| Sets the maximal size of Tamaya getHistory entries.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history_maxsize_set size
--<b>ARGUMENTS</b>
--<i>size</i>: The maximum number of entries in the getHistory.
--+++
--
--| +tm_info+
--| Show he current Tamaya status.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_info
--</pre>
--+++
--
--| +tm_osgi_config+
--| Show the current OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_osgi_config [options] pid
--<b>ARGUMENTS</b>
--<i>pid</i> The target OSGI component PID.
--<b>OPTIONS</b>
--<i>section, -s, --section</i>: A starting expression selecting the keys to be filtered.
--</pre>
--+++
--
--| +tm_policy+
--| Get the current Tamaya overriding policy.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_policy
--</pre>
--+++
--
--| +tm_policy_set+
--| Sets the current Tamaya operation policy.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_policy_set tm_policy_set
--<b>ARGUMENTS</b>
--<i>tm_policy_set</i>: The operation policy how Tamaya intercepts OSGI configuration.
--+++
--
--| +tm_propagate_updates+
--| Flag if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.
--| +++
--<pre>
--<b>SYNTAX</b>
--tm_propagate_updates
--+++
--
--| +tm_propagate_updates_set+
--| Configure if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_propagate_updates_set enabled
--<b>ARGUMENTS</b>
--<i>enabled</i>: Set to true to enable Tamaya's updating trigger.
--</pre>
--+++
--
--| +tm_property+
--| Get a Tamaya property.
--| +++
--<pre><b>SYNTAX</b>
--tamaya:tm_property [options] [key]
--<b>ARGUMENTS</b>
--<i>key</i>: The target property source id.
--<b>OPTIONS</b>
--<i>extended,e</i>: Also print extended property value attributes.
--<i>propertysource, ps</i>: The target property source id.
--</pre>
--+++
--
--| +tm_propertysource+
--| Show the current Tamaya entries of a propertysource.
--| +++
--<pre><b>SYNTAX</b>
--tamaya:tm_propertysource [propertysource]
--<b>ARGUMENTS</b>
--<i>propertysource</i>: The target property source id.
--+++
--
--| +tm_propertysources+
--| Get a list of currently registered propertysources.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_propertysources
--</pre>
--+++
--
--|=======
--
--==== Apache Karaf Ferature
--
--Apache Tamaya provides a Karaf feature with all required dependencies
--as +org.apache.tamaya.ext:tamaya-karaf-features:{tamaya-version}:features:xml+.
--
--
--
--==== Apache Felix Gogo Console
--
--Apache Tamaya also provides the same commands as described for _Karaf_, but executable in
--plaing Gogo console as used by Apache Felix and Equinox as
--+org.apache.tamaya.ext:tamaya-gogo-shell:{tamaya-version}+. Refer to the previous sections for
--a detailed command description.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_remote.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_remote.adoc
index fb7ffa9,fb7ffa9..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_remote.adoc
+++ /dev/null
@@@ -1,111 -1,111 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Remote Configuration
--
--toc::[]
--
--
--[[Remote]]
--== Tamaya Remote Configuration (Extension Module)
--
--Tamaya _Remote_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Remote_ provides support for reading configuration from remote resources. It provides
--out-of-the-box support for reading scoped configuration from a Tamaya configuration server as
--provided with the Tamaya _server_ module .
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use remote support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-remote</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Reading Remote configuration from a Tamaya Configuration Server
--
--The remote module allows reading JSON formatted configuration as provided by the Tamaya _server_ extension . The JSON
--format used looks as follows:
--
--[source, json]
-------------------------------------------------
--{
-- "java.vendor.url": "http://java.oracle.com/",
-- "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/",
-- "java.vm.info": "mixed mode",
-- "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
-- "java.vm.specification.name": "Java Virtual Machine Specification",
-- "java.vm.specification.vendor": "Oracle Corporation",
-- "java.vm.specification.version": "1.8",
-- "java.vm.vendor": "Oracle Corporation",
-- "java.vm.version": "25.45-b02",
-- "sun.arch.data.model": "64",
-- "sun.boot.class.path": "C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes",
-- "sun.boot.library.path": "C:\apps\jdk18\jre\bin",
-- "sun.cpu.endian": "little",
-- "sun.cpu.isalist": "amd64",
-- "sun.desktop": "windows",
-- "sun.io.unicode.encoding": "UnicodeLittle",
-- "sun.java.command": "com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start",
-- "sun.java.launcher": "SUN_STANDARD",
-- "sun.jnu.encoding": "Cp1252",
-- "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers",
-- "sun.os.patch.level": "",
-- "_class": "org.apache.tamaya.functions.FilteredConfiguration",
-- "_info.filter": "java.v,sun",
-- "_info.format": "application/json",
-- "_info.timestamp": "1441463200571",
-- "_timestamp": "1441463200571",
-- "_type": "Configuration"
--}
-------------------------------------------------
--
--Basically there are no constraints about they keys provided. By default Tamaya uses keys prefixed with
--+'_'+ to identify meta-data entries, but this is not a required precondition.
--
--Finally such a remote configuration can be easily integrated by inheriting from the provided base
--class. Hereby a default ordinal must be defined and the +protected Collection<URL> getAccessURLs()+
--method must be implemented to define the URL from where the configuration should be accessible. Hereby
--multiple URLs can be provided, which are accesed in order as provided by the collection's iterator. The
--first accessible URL determines the configuration read.
--
--[source, java]
-------------------------------------------------
--public class RemoteConfigSource extends BaseRemoteConfigSource{
--
-- @Override
-- protected Collection<URL> getAccessURLs() {
-- try {
-- String configServerUrl = System.getenv("CONFIG_SERVER");
-- if(configServerUrl==null){
-- configServerUrl = System.getProperty("configServer");
-- }
-- if(configServerUrl==null){
-- configServerUrl = "http://localhost:8888/config?scope=CLIENT&scopeId={clientId}&format=application/json";
-- }
-- System.out.println("Reading config from " + configServerUrl.replace("{clientId}", Client.getClientId()));
-- return Arrays.asList(new URL[]{new URL(configServerUrl.replace("{clientId}", Client.getClientId()))});
-- } catch (MalformedURLException e) {
-- Logger.getLogger(getClass().getName()).log(Level.WARNING, "Failed to configure remote config location,", e);
-- return Collections.emptySet();
-- }
-- }
--
--}
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_resolver.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_resolver.adoc
index dac7735,dac7735..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_resolver.adoc
+++ /dev/null
@@@ -1,131 -1,131 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Resolver
--
--[[Resolver]]
--== Tamaya Resolver (Extension Module)
--
--Tamaya _Resolver_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Resolver_ is an extension module. Refer to the link:../extensions.html[extensions documentation]
--for further details about modules.
--
--Tamaya Resolver provides a extendible dynamic resolution mechanism. It allows to use UNIX-styled (+${...}+ placeholder
--expressions in your configuration values. The resolver hereby supports transitive resolution and also prevents
--cycles to loop endlessly.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--
--=== Installation
--
--To benefit from dynamic value resolution you only must add the corresponding dependency to your module:
--
--[source, xml, subs="verbatim,attributes"]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-resolver</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--The module automatically registers an according +Filter+ that is automatically called, whenever a value
--is accessed.
--
--
--=== Available Resolvers
--
--Currently the module defines the following resolvers:
--
--.Available Resolvers
--[cols="<.1,<.2,<.1"]
--|=======
--| _Expression_
--| _Description_
--| _Example_
--
--| +conf:<configKey>+
--| Reads another configKey and replaces the expression with the value found.
--| conf-ref=${conf:anotherConf.entryKey}
--
--| +resource:<resourceRef>+
--| Reads a resource from the current classpath and replaces the expression with the given text content.
--| cp-ref=${resource:Testresource.txt}
--
--| +file:<fileRef>+
--| Reads a resource from the current classpath and replaces the expression with the given text content.
--| file-ref=${file:c:\myFile.txt}
--
--|+url:<url>+
--|Reads an URL and replaces the expression with the given text content.
--| url-ref=${url:http://www.google.com}
--
--|=======
--
--
--=== SPI: Implementing your own Resolvers
--
--The module also provides a small SPI for adding your own resolver implementations. Basically the
--first and most important thing to do is implementing the +ExpressionResolver+ interface:
--
--.Implementing a Custom Resolver
--[source, java]
-------------------------------------------------
--public class PwdDecrypter implements ExpressionResolver {
--
-- @Override
-- public String getResolverPrefix() {
-- return "decrypt:";
-- }
--
-- @Override
-- public String evaluate(String expression) {
-- return decrypt(expression);
-- }
--
-- private String decrypt(String s) {
-- ...
-- }
--}
-------------------------------------------------
--
--Basically that is all you must do, after having registered the class with the +ServiceLoader+ it will be found
--and loaded by the implementation. With that all expressions that start with the given prefix are passed to the
--resolver, so all the following expressions will be sent to the implementation:
--
--[source,listing]
-------------------------------------------------
--blabla ${decrypt:myname}
--blabla ${decrypt:myname} foo blabla ${decrypt:myname}
-------------------------------------------------
--
--Hereby evaluation is repeated until no further change of values could be detetced. In case of a endless loop
--the evaluation is broken after a (configurable) number of cycles.
--
--
--Under the hood instances of +ExpressionResolver+ are managed by an implementation of the +ExpressionEvaluator+
--interface:
--
--[source, java]
-------------------------------------------------
--public interface ExpressionEvaluator {
-- /**
-- * Evaluates the current expression.
-- * @param key the key, not null.
-- * @param value the value to be filtered/evaluated.
-- * @return the filtered/evaluated value, including null.
-- */
-- String evaluateExpression(String key, String value);
--}
-------------------------------------------------
--
--Implementing and registering this interface gives you full control, but in most cases you should be fine with
--the default implementation in place.
[2/8] incubator-tamaya-site git commit: TAMAYA-274 Updated
documentation. TAMAYA-355 Updated documentation. TAMAYA-353 Updated
documentation.
Posted by an...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_resources.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_resources.adoc
index 131909b,131909b..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_resources.adoc
+++ /dev/null
@@@ -1,167 -1,167 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Resources
--
--[[Resources]]
--== Tamaya Resources (Extension Module)
--
--Tamaya _Resources_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Resources_ defines some additional tools to locate resources in your classpath or file system based on
--descriptive ant-styled resource patterns.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--
--=== Installation
--
--To use this module add the following dependency:
--
--[source, listing, subs="verbatim,attributes"]
-------------------------------------------------
--<dependency>
-- <grooupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-resources</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Usage
--
--The module's main entry point is the singleton class +org.apache.tamaya.resource.ConfigResources+. This class
--provides access to a +ResourceResolver+ instance:
--
--[source,java]
-------------------------------------------------
--ResourceResolver resolver = ConfigResources.getResourceResolver();
-------------------------------------------------
--
--[source,java]
-------------------------------------------------
--public interface ResourceResolver {
-- Collection<URL> getResources(Collection<String> expressions) {...}
-- Collection<URL> getResources(String... expressions) {...}
-- Collection<URL> getResources(ClassLoader classLoader, String... expressions){...}
-- Collection<URL> getResources(ClassLoader classLoader, Collection<String> expressions);
--}
-------------------------------------------------
--
--Hereby the methods allow to resolve expressions to a collection of URLs. In case the expression is also targeting the
--current classpath the target +ClassLoader+ to be used can be passed additionally.
--
--The default implementation provides resource resolution mechanism similar to the functionality offered by Spring.
--So by default resources can be looked up
--
--* from files
--* from the classpath
--* optionally ant-styled expressions can be used.
--
--
--=== Examples
--
--There are numerous ways how a resource pattern can be defined. Following the most important variants
--are listed:
--
--[source,listing]
-------------------------------------------------
--// explicitly searching the file system
--file:myroot/aa?a/*.file
--file:myroot/b*/b?/*.file
--file:myroot/**/*.file
--
--// explicitly searching the classpath
--classpath:myroot/**/*.file
--classpath:javax/annotation/*.class
--classpath:javax/**/sql/*.class
--classpath:javax/annotation/**/R*.class
--classpath:javax/annotation/R?so*.class
--classpath:META-INF/maven/org.apache.geronimo.specs/**/*
--
--// search both classpath and files
--javax/annotation/*.class
--javax/**/sql/*.class
--javax/annotation/**/R*.class
--javax/annotation/R?so*.class
--META-INF/maven/org.apache.geronimo.specs/**/*
--myroot/**/*.file
--myroot/aa?a/*.file
--myroot/b*/b?/*.file
-------------------------------------------------
--
--Summarizing the resources module provides useful functionality that helps to locate resources on the file system and
--in the classpath. This can be used to implement +PropertySourceProvider+ implementations that are based on
--corresponding resource path patterns instead of concrete files.
--
--
--=== Overall Usage Example
--
--Given the functionality we can easily implement a +PropertySourceProvider+ that reads all files from a classpath
--location, hereby traversing down all folders:
--
--
--[source, java]
---------------------------------------------------------------
--public class PathBasedConfigSourceProvider implements ConfigSourceProvider {
--
-- @Override
-- public Iterable<ConfigSource> getConfigSources(ClassLoader classloader) {
-- List<PropertySource> propertySources = new ArrayList<>();
-- Collection<URL> resources = ConfigResources.getResourceResolver().getResources(classLoader, "META-INF/cfg/**/*.properties");
-- for(URL url:resources){
-- Properties props = new Properties();
-- try(InputStream is = url.openStream()){
-- props.load(is);
-- propertySources.add(new PropertiesBasedConfigSource(url.toString(), props));
-- }
-- catch(Exception e){
-- e.printStackTrace();
-- }
-- }
--
-- return propertySources;
-- }
--
-- private final static class PropertiesBasedConfigSource implements ConfigSource {
-- private String name;
-- private Map<String,String> properties = new HashMap<>();
--
-- public PropertiesBasedConfigSource(String name, Properties props) {
-- this.name = name;
-- props.forEach((k,v) -> this.properties.put(k.toString(), v.toString()));
-- }
--
-- @Override
-- public String getName() {
-- return name;
-- }
--
-- @Override
-- public String get(String key) {
-- return properties.get(key);
-- }
--
-- @Override
-- public Map<String, String> getProperties() {
-- return properties;
-- }
-- }
--}
---------------------------------------------------------------
--
--
--=== SPI
--
--The +ResourceResolver+ that is returned by the +ConfigResources+ singleton is determined by the
--current +ServiceContext+, by default you can replace the default implementation by registering an
--alternate implementation with an overriding +@Priority+ annotation added using the +ServiceLoader+.
--
--Additionally a +BaseResourceResolver+ class can be used to reduce the amount of code to be written
--on your own.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_server.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_server.adoc
index 35338d9,35338d9..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_server.adoc
+++ /dev/null
@@@ -1,239 -1,239 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Configuration Server
--
--toc::[]
--
--
--[[Server]]
--== Tamaya Configuration Server (Extension Module)
--
--Tamaya _Server_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--The Tamaya _Server_ module provides support for providing scoped configuration using a http server serving JSON formatted
--configuration properties.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To benefit from configuration server support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-server</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Providing configuration using the Tamaya Built-in Configuration Server
--
--The most simple way for providing configuration is to start the internal server:
--
--[source, java]
-------------------------------------------------
--// using context path: '/', port 8085
--org.apache.tamaya.server.Server.start();
--
--// optionally pass the root context path and/or port:
--// org.apache.tamaya.server.Server.start(8088);
--// org.apache.tamaya.server.Server.start("/appconf", 7787);
-------------------------------------------------
--
--This will start a simple server instance that serves the following URL patterns:
--
--* +GET ${CONTEXT}/config+ provides access to the full configuration tree.
--* +GET ${CONTEXT}/config/filtered/${path}+ let you filter the configuration returned using regular expression (comma separated).
-- E.g. +${CONTEXT}/config/filtered/java,sun+ will return all configuration entries starting with _java_ and _sun_.
--
--Additionally the server module has the following options implemented, which can be passed as additional, optional
--parameters:
--
--* +format+ allows to define the target format. By default the +ACCEPT+ header of the http request is checked, but this
-- setting can be explicitly controlled by passing this parameter explicitly. The value is the expected MIME type to be
-- returned. By default the service supports the following types:
-- ** text/html
-- ** text/plain
-- ** application/xml
-- ** application/json
--
--
--=== Using the Configuration Servlets
--
--You can also register a servlet, e.g. as follows;
--
------------------------------------------------------------
--<servlet>
-- <servlet-name>config-servlet</servlet-name>
-- <servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class>
-- <init-params>
-- <init-param key="javax.ws.rs.Application">org.apache.tamaya.server.Server$ResourceLoader</init-param>
-- </init-params>
--</servlet>
------------------------------------------------------------
--
--
--==== Formatting used by Default
--
--The server module formats the configuration returned by default in the following variants:
--
--.Formatting for +text/json+
--
--[source, json]
-------------------------------------------------
--{
-- "java.vendor.url": "http://java.oracle.com/",
-- "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/",
-- "java.vm.info": "mixed mode",
-- "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
-- "java.vm.specification.name": "Java Virtual Machine Specification",
-- "java.vm.specification.vendor": "Oracle Corporation",
-- "java.vm.specification.version": "1.8",
-- "java.vm.vendor": "Oracle Corporation",
-- "java.vm.version": "25.45-b02",
-- "sun.arch.data.model": "64",
-- "sun.boot.class.path": "C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes",
-- "sun.boot.library.path": "C:\apps\jdk18\jre\bin",
-- "sun.cpu.endian": "little",
-- "sun.cpu.isalist": "amd64",
-- "sun.desktop": "windows",
-- "sun.io.unicode.encoding": "UnicodeLittle",
-- "sun.java.command": "com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start",
-- "sun.java.launcher": "SUN_STANDARD",
-- "sun.jnu.encoding": "Cp1252",
-- "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers",
-- "sun.os.patch.level": "",
-- "_class": "org.apache.tamaya.functions.FilteredConfiguration",
-- "_info.filter": "java.v,sun",
-- "_info.format": "application/json",
-- "_info.timestamp": "1441463200571",
-- "_timestamp": "1441463200571",
-- "_type": "Configuration"
--}
-------------------------------------------------
--
--
--.Formatting for +application/xml+
--
--[source, xml]
-------------------------------------------------
--<configuration>
-- <entry key="java.vendor.url">http://java.oracle.com/</entry>
-- <entry key="java.vendor.url.bug">http://bugreport.sun.com/bugreport/</entry>
-- <entry key="java.vm.info">mixed mode</entry>
-- <entry key="java.vm.name">Java HotSpot(TM) 64-Bit Server VM</entry>
-- <entry key="java.vm.specification.name">Java Virtual Machine Specification</entry>
-- <entry key="java.vm.specification.vendor">Oracle Corporation</entry>
-- <entry key="java.vm.specification.version">1.8</entry>
-- <entry key="java.vm.vendor">Oracle Corporation</entry>
-- <entry key="java.vm.version">25.45-b02</entry>
-- <entry key="sun.arch.data.model">64</entry>
-- <entry key="sun.boot.class.path">C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes</entry>
-- <entry key="sun.boot.library.path">C:\apps\jdk18\jre\bin</entry>
-- <entry key="sun.cpu.endian">little</entry>
-- <entry key="sun.cpu.isalist">amd64</entry>
-- <entry key="sun.desktop">windows</entry>
-- <entry key="sun.io.unicode.encoding">UnicodeLittle</entry>
-- <entry key="sun.java.command">com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start</entry>
-- <entry key="sun.java.launcher">SUN_STANDARD</entry>
-- <entry key="sun.jnu.encoding">Cp1252</entry>
-- <entry key="sun.management.compiler">HotSpot 64-Bit Tiered Compilers</entry>
-- <entry key="sun.os.patch.level"></entry>
-- <entry key="_class">org.apache.tamaya.functions.FilteredConfiguration</entry>
-- <entry key="_info.filter">java.v,sun</entry>
-- <entry key="_info.format">application/xml</entry>
-- <entry key="_info.timestamp">1441463383687</entry>
-- <entry key="_timestamp">1441463383687</entry>
-- <entry key="_type">Configuration</entry>
--</configuration>
-------------------------------------------------
--
--
--.Formatting for +text/plain+
--
--[source, text]
-------------------------------------------------
--
--Configuration:
-- java.vendor.url: http://java.oracle.com/,
-- java.vendor.url.bug: http://bugreport.sun.com/bugreport/,
-- java.vm.info: mixed mode,
-- java.vm.name: Java HotSpot(TM) 64-Bit Server VM,
-- java.vm.specification.name: Java Virtual Machine Specification,
-- java.vm.specification.vendor: Oracle Corporation,
-- java.vm.specification.version: 1.8,
-- java.vm.vendor: Oracle Corporation,
-- java.vm.version: 25.45-b02,
-- sun.arch.data.model: 64,
-- sun.boot.class.path: C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes,
-- sun.boot.library.path: C:\apps\jdk18\jre\bin,
-- sun.cpu.endian: little,
-- sun.cpu.isalist: amd64,
-- sun.desktop: windows,
-- sun.io.unicode.encoding: UnicodeLittle,
-- sun.java.command: com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start,
-- sun.java.launcher: SUN_STANDARD,
-- sun.jnu.encoding: Cp1252,
-- sun.management.compiler: HotSpot 64-Bit Tiered Compilers,
-- sun.os.patch.level: ,
-- _class: org.apache.tamaya.functions.FilteredConfiguration,
-- _info.filter: java.v,sun,
-- _info.format: text/plain,
-- _info.timestamp: 1441463082020,
-- _timestamp: 1441463082021,
-- _type: Configuration
-------------------------------------------------
--
--
--.Formatting for +application/html+
--
--[source, html]
-------------------------------------------------
--<html>
--<head><title>System Configuration</title></head>
--<body>
--<h1>Sysem Configuration</h1>
--<p>This view shows the system configuration of devbox-win at Sat Sep 05 16:30:59 CEST 2015.</p><pre>
--Configuration:
-- java.vendor.url: http://java.oracle.com/,
-- java.vendor.url.bug: http://bugreport.sun.com/bugreport/,
-- java.vm.info: mixed mode,
-- java.vm.name: Java HotSpot(TM) 64-Bit Server VM,
-- java.vm.specification.name: Java Virtual Machine Specification,
-- java.vm.specification.vendor: Oracle Corporation,
-- java.vm.specification.version: 1.8,
-- java.vm.vendor: Oracle Corporation,
-- java.vm.version: 25.45-b02,
-- sun.arch.data.model: 64,
-- sun.boot.class.path: C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes,
-- sun.boot.library.path: C:\apps\jdk18\jre\bin,
-- sun.cpu.endian: little,
-- sun.cpu.isalist: amd64,
-- sun.desktop: windows,
-- sun.io.unicode.encoding: UnicodeLittle,
-- sun.java.command: com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start,
-- sun.java.launcher: SUN_STANDARD,
-- sun.jnu.encoding: Cp1252,
-- sun.management.compiler: HotSpot 64-Bit Tiered Compilers,
-- sun.os.patch.level: ,
-- _class: org.apache.tamaya.functions.FilteredConfiguration,
-- _info.filter: java.v,sun,
-- _info.format: text/html,
-- _info.timestamp: 1441463459653,
-- _timestamp: 1441463459654,
-- _type: Configuration
--</pre>
--</body>
--</html>
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_spring.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_spring.adoc
index bc4d760,bc4d760..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_spring.adoc
+++ /dev/null
@@@ -1,177 -1,177 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Spring Integration
--
--toc::[]
--
--
--[[Spring]]
--== Tamaya Spring Integration (Extension Module)
--
--Tamaya _Spring_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Spring_ currently provides full integration with Spring and Spring Boot:
--
--* A Spring +@Configuration+ implementation that also provides a Tamaya based version of
-- +org.springframework.context.support.PropertySourcesPlaceholderConfigurer+.
--* +org.apache.tamaya.integration.spring.TamayaEnvironment+ is the Tamaya based implementation of the Spring
-- +Environment+ interface.
--* +TamayaSpringPropertySource+ implements an additional Spring +PropertySource+.
--* Finally +org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor+ implements a Bean +PostProcessor+,
-- which adds all the fully fledged Tamaya configuration capabilities to Spring.
--
--
--=== Compatibility
--
--Both modules are based on Java 8, so they will run on Java 8 and beyond. The extension shown here works in
--Spring Framework as well as Spring Boot.
--
--
--=== Installation
--
--To benefit from Tamaya Spring integration add the following dependencies to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-spring</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Registering Tamaya Spring Configuration
--
--Basically to activate the Tamaya Spring support the most simple thing is to a enable the Tamaya package for being
--scanned for Spring components, e.g. using by annotation:
--
--[source, java]
----------------------------------------------------------
--@SpringBootApplication
--@ComponentScan({"org.apache.tamaya.integration.spring"})
--public class SampleWebFreeMarkerApplication {
--
-- public static void main(String[] args) throws Exception {
-- SpringApplication.run(SampleWebFreeMarkerApplication.class, args);
-- }
--
--}
----------------------------------------------------------
--
--Of course, you can still use Spring's XML configuration in a similar way:
--
--[source, xml]
----------------------------------------------------------
--<beans xmlns="http://www.springframework.org/schema/beans"
-- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-- xmlns:context="http://www.springframework.org/schema/context"
-- xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">
--
-- <context:annotation-config />
-- <context:component-scan base-package="org.apache.tamaya.integration.spring"/>
--
-- ...
--
--</beans>
----------------------------------------------------------
--
--
--Though not recommended you can explicitly register the Tamaya related beans in your context configuration by hand:
--files:
--
--[source, xml]
----------------------------------------------------------
--<bean id="tamayaInjectionProcessor" name="tamayaInjectionProcessor" class="org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor"/>
--<bean id="tamayaConfigProvider" name="tamayaConfigProvider" class="org.apache.tamaya.integration.spring.TamayaSpringConfig"/>
----------------------------------------------------------
--
--
--=== Configuring your Context
--
--After activation you can use Tamaya as a backend for property resolution, e.g. +propertyValue+
--is resolved from the current Tamaya configuration. See example below:
--
--[source, xml]
----------------------------------------------------------
--<bean id="configuredBean" name="configuredBean" class="org.apache.tamaya.integration.spring.ConfiguredSpringBean">
-- <property name="message" value="${propertyValue}"/>
--</bean>
----------------------------------------------------------
--
--
--=== Configuring your Beans
--
--Similarly you can inject any kind of configuration as supported by Tamaya into your Spring managed beans:
--
--[source, java]
----------------------------------------------------------
--@ConfigDefaultSections("app.root") // optional <1>
--@Component
--public class ConfiguredSpringBean {
--
-- @Value("${application.message:Hello World}") <2>
-- private String message;
--
-- @Autowired
-- private Environment env;
--
-- @ConfigProperty(key = "alternateMessage", required = false) <3>
-- private String anotherMessage = "N/A";
--
-- @ConfigProperty(key="java.version")
-- private String javaVersion;
--
-- @ConfigProperty(key="number", defaultValue="23") <4>
-- @ConfigFallbackKeys=({"testNum", "[notavailable]"}) <5>
-- private int testNumber;
--
-- ...
--}
----------------------------------------------------------
--
--<1> You can configure default section prefixes. This is an optional feature.
--<2> Tamaya does not require you to change your code. You can still work with
-- Spring injection for your configuration, but Tamaya will override Spring
-- configuration by default.
--<3> You can also define entries as optional, which allows you to perform
-- default inialization using Java idoms.
--<4> Tamaya allows you to define an ordered list of key candidates, which are
-- combined with the section prefix, if present, to the full keys. Keys added
-- in brackets ([]) are interpreted as absolute keys, so the example above
-- the key candidate list evaluates to +app.root.number", "app.root.testNum",
-- "notavailable"+.
--<5> You can configure default values used, if no other value can be evaluated
-- for the given keyset.
--
--Summarizing you get all the nice features of Tamaya out of the box running
--with your Spring code.
--
--=== Working with Dynamic Values
--
--Integration into Spring also includes for support for _dynamic values_:
--
--[source, java]
----------------------------------------------------------
--@ConfigProperty(key = "foreground.color", required = false, defaultValue = "#DDDDDD")
--private DynamicValue<Color> foregroundColor;
----------------------------------------------------------
--
--Dynamic values are a very flexible mechanism for managing configuration changes.
--You can even use an update policy to define how you want to handle configuration
--changes for your configuration parameter:
--
--[source, java]
----------------------------------------------------------
--foregroundColor.setUpdatePolicy(UpdatePolicy.IMMEDEATE);
--foregroundColor.addPropertyChangeListener(() -> {
-- System.out.println("New forground color: " + foregroundColor.get();
--});
----------------------------------------------------------
--
--IMPORTANT: For a full description of Tamaya's injection API please
-- refer to the link:extensions/mod_injection.html[corresponding documentation].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_usagetracker.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_usagetracker.adoc
index e773c59,e773c59..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_usagetracker.adoc
+++ /dev/null
@@@ -1,161 -1,161 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Usage Tracking
--
--toc::[]
--
--
--[[UsageTracker]]
--== Tamaya Usage Tracking (Extension Module)
--
--Tamaya _UsageTracker_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _UsageTracker_ allows to record and count the configuration access and consumer locations in your local
--VM.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--
--=== Installation
--
--To use Tamaya _usagetracker_ you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-usagetracker</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Tracking Configuration Access
--
--The model module also allows tracking which code accesses configuration properties or configuration parameters.
--It checks the stacktrace to evaluate the calling code location, hereby any unwanted packages can be implicitly
--ommitted from the stacktrace. Also the maximal length of the stacktrace retained can be constraint in length.
--The usages are recorded as +Usage+ instances. Hereby for each parameter accessed a corresponding +Usage+
--instance is created. It can be accessed by calling +Usage ConfigUsageStats.getUsage(String key)+. Usage
--statistics for calling +Config.getPropertyNames()+ can be obtained calling +Usage getUsageAllProps();+.
--
--Usage tracking is disabled by default. It can be enabled by calling +ConfigUsageStats.enableUsageTracking(true);+.
--+ConfigUsageStats.isUsageTrackingEnabled()+ returns the current tracking status.
--
--The +Usage+ class itself provides access to further fainer grained usage data (+AccessDetail+) containing:
--
--* the access point (+fqn.ClassName#method(line: xxx)+).
--* the number of accesses
--* the first an last access
--* the values read
--* the access stacktrace (filtered by ignored packages).
--
--[source,java]
-------------------------------------------------------------
--public final class Usage {
-- [...]
-- public String getKey();
-- public void clearMetrics();
-- public int getReferenceCount();
-- public int getUsageCount();
-- public Collection<AccessDetail> getAccessDetails(Class type);
-- public Collection<AccessDetail> getAccessDetails(Package pack);
-- public Collection<AccessDetail> getAccessDetails(String lookupExpression);
-- public Collection<AccessDetail> getAccessDetails();
-- public void trackUsage(String value);
-- public void trackUsage(String value, int maxTraceLength);
--
--
-- public static final class AccessDetail {
-- [...]
-- public void clearStats();
-- public long trackAccess(String value);
-- public long getAccessCount();
-- public String getAccessPoint();
-- public long getFirstAccessTS();
-- public long getLastAccessTS();
-- public String[] getStackTrace();
-- public Map<Long, String> getTrackedValues();
-- }
--
--}
-------------------------------------------------------------
--
--With +ConfigUsageStats.clearUsageStats()+ the collected statistics can be reset at any time. Summarizing the main
--singleton for configuration statistics is defined as follows:
--
--[source,java]
-------------------------------------------------------------
--public final class ConfigUsageStats{
-- public static Set<String> getIgnoredUsagePackages();
-- public static void addIgnoredUsagePackages(String... packageName);
-- public static void enableUsageTracking(boolean enabled);
-- public static Usage getUsage(String key);
-- public static Collection<Usage> getUsages();
-- public static void clearUsageStats();
-- public static Usage getUsageAllProperties();
-- public static boolean isUsageTrackingEnabled();
-- public static String getUsageInfo();
--}
-------------------------------------------------------------
--
--
--==== Customizing the Stacktrace for Usage Reporting
--
--The stacktrace tracked by the system can be customized in several ways:
--
--* +ConfigUsageStats.addIgnoredPackageNames(String...)+ allows to add additional ignored package names.
--* With +Usage.setMaxTraceLength(int)+ the maximal size of the stacktraces logged can be set. Setting a
-- negative value will disable stacktrace logging completelely.
--
--
--=== Accessing Usage Statistics
--
--Bascially usage statistics are available in two forms:
--
--* The +Usage/AccessDetail+ object tree can be accessed programmatically from the +ConfigUsageStats+
-- singleton.
--* With +ConfigUsageStats.getUsageInfo()+ also a textual representation of the usage statistics
-- can be obtained, as illustrated below (a snipped from the current test output):
--
--[source,listing]
-------------------------------------------------------------
--Apache Tamaya Configuration Usage Metrics
--=========================================
--DATE: Sat Apr 30 21:51:09 CEST 2016
--
--220 <<all>>:
-- - 220 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
--3 java.version:
-- - 2 test.model.TestConfigAccessor#readProperty(line:43), first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
-- - 1 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016
--
-------------------------------------------------------------
--
--
--=== Auto-Documentation of Classes with Configuration Injection
--
--A special feature of this module is that it observes +ConfigEvent+ published through Tamaya'as event channel
--(+tamaya-events+ module). If no metaconfiguration model is found the model manager by default automatically creates
--models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment
--time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different
--behaviour. Nevertheless this means that after your system has been started you should have access to a complete
--set of +ConfigModel+ instances that automatically document all the classes in your system that consume configuration
--(through injection).
--
--
--== UsageTracker Module SPI
--
--=== The ConfigUsageStatsSpi
--
--The methods for managing and tracking of configuration changes are similarly delegated to an
--implementation of the +org.apache.tamaya.model.spi.ConfigUsageStatsSpi+ SPI.
--By implementing this SPI and registerting it with the +ServiceContext+ the usage tracking
--logic can be adapted or replaced.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_validation.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_validation.adoc
index 0b97ccf,0b97ccf..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_validation.adoc
+++ /dev/null
@@@ -1,104 -1,104 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Configuration Validation
--
--toc::[]
--
--
--[[Validation]]
--== Tamaya Validation: Validating Configuration (Extension Module)
--
--Tamaya _Validation_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== Overview
--
--Tamaya _Validation_ adds support to validate a configuration against a set of rules
--defined in a Tamaya Metaconfiguration XML file.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will run on Java 8 and beyond.
--
--
--=== Installation
--
--To activate configuration _validation_ you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-validation</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--The component will extend Tamaya's +tamaya-metamodel+ module and adds an additional meta provider ruleset
--so validation rules can also be added to the default meta configuration XML file as separate sections.
--
--
--=== Usage
--
--This module expects meta-configuration to be located at the following locations. Hereby multiple files
--are supported:
--
--[source, text]
-------------------------------------------------
---Dtamaya-validation=<an URL> // any resolvable URL
--./tamaya-validation-*.xml // file
--META-INF/tamaya-validation-*.xml // classpath (multiple entries-possible)
-------------------------------------------------
--
--
--=== The Validation XML Format
--
--The configuration validation is defined by simple configuration meta-data entries.
--
--[source, xml]
-------------------------------------------------
--<configuration-validation>
-- ...
-- <provider>The Validation Provider</provider> <!-- optional -->
-- <section name="org.mycompany">
-- <section name="security" required="true">
-- <description>The description of ma area.</description>
-- </section>
-- </section>
-- <section name="minimal"/>
-- <section name="validated.sections" at-least="1">
-- <section name="customValidated" validator="myFQValidatorClassName"/>
-- <section name="withParams" >
-- <param name="int" type="int"/>
-- <param name="aText" expression="[a|b|c]" required="true"/>
-- <param name="aValidatedText" validator="myValidatorClass">
-- <description>This kind of params are more complex...</description>
-- </param>
-- </section>
-- </section>
-- <validator class="a,b,c,MyGlobalValidator"/>
--</configuration-validation>
-------------------------------------------------
--
--
--==== The Example Explained
--
--* The *provider* entry is used for generating validation message, when a validation fails.
--* Section itself can be recursively defined, where each level can have it's own validations.
--* Sections added, but without validation rules are _defined_ section. Configuration outside of
-- defined sections can be flagged out using WARNING messages.
--* Sections can be _reuired_ and additionally also _validated_.
--* There is also the possibility to register global validators, which are called by the validation
-- logic once a configuration has been completely loaded.
--
--Similar to sections also parameters can be validated:
--
--* they can be marked as _required_
--* they can have a certain type, meaning they must be convertible to the given type
--* they can have an additional custom validator.
--* they can have an optional description for error analysis and error output.
--
--Similar to section parameters that are not defined, but encountered may be flagged out with
--a WARNING message.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_vertx.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_vertx.adoc
index a066a05,a066a05..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_vertx.adoc
+++ /dev/null
@@@ -1,185 -1,185 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration for Vertx
--
--toc::[]
--
--
--[[JNDI]]
--== Integration with Vertx (Extension Module)
--Tamaya _JNDI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Vertx_ provides configuration services that can be used in a Vertx environment:
--
--* +AbstractConfiguredVerticle+ defines a subclass extending +AbstractVerticle+, which allows you to
-- use Tamaya Injection API.
--* Additionally you deply a +ConfigVerticle+, which registers services to access configuration
-- using asynchronous event bus.
--
--
--=== Compatibility
--
--The module requires Java 8, so it will not run on Java 7.
--
--
--=== Installation
--
--To use Tamaya's _Vertx_ support you only must add the corresponding dependency to
--your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-vertx</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Functionality Provided
--
--==== Extending AbstractConfiguredVerticle
--
--Main artifact is the +AbstractConfiguredVerticle+ class, which implements a
--base verticle class for Vertx:
--
--[source, java]
-------------------------------------------------
--public abstract class AbstractConfiguredVerticle extends AbstractVerticle{
--
-- private Configuration configuration;
--
-- public AbstractConfiguredVerticle() {
-- configure();
-- }
--
-- public Configuration getConfiguration(){
-- if(this.configuration==null){
-- this.configuration = ConfigurationProvider.getConfiguration();
-- }
-- return this.configuration;
-- }
--
-- public void setConfiguration(Configuration configuration){
-- this.configuration = configuration;
-- configure();
-- }
--
-- protected void configure(){
-- ConfigurationInjection.getConfigurationInjector().configure(this, getConfiguration());
-- }
--
-- protected final String getConfigProperty(String key);
-- protected final String getConfigPropertyOrDefault(String key, String defaultValue);
-- protected final <T> T getConfigProperty(String key, Class<T> type);
-- protected final <T> T getConfigPropertyOrDefault(String key, Class<T> type, T defaultValue);
--}
-------------------------------------------------
--
--Using this verticle as a superclass, provides you
--
--* embedded convenience methods for programmatic configuration access (+getConfigProperty*+ methods).
--* support for configuration injection based on link:../mod_injection.html[Tamaya's injection API].
--
--
--The following code snippet gives you an example, what you can do with this functionality:
--
--[source, java]
-------------------------------------------------
--public cllass MyVerticle extends AbstractConfiguredVerticle{
--
-- @Override
-- public void start(){
-- String configuredValue = getConfigPropertyOrDefault("myKey");
-- [...]
-- BigDecimal bd = getConfigureddPropertyOrDefault("MyNum", BigDecimal.ZERO);
-- [...]
-- }
--}
-------------------------------------------------
--
--
--As menioned you can also use the injection API:
--
--[source, java]
-------------------------------------------------
--public cllass MyVerticle extends AbstractConfiguredVerticle{
--
-- @Config("myKey")
-- private String configuredValue;
--
-- @Config(value="MyNum", defaultValue="0.0")
-- private BigDecimal bd;
--
--
-- @Override
-- public void start(){
-- [...]
-- }
--}
-------------------------------------------------
--
--
--==== Accessing Configuration using the Vertx event bus
--
--Additionally the extension allows to access configuration values from the event bus:
--
--[source, java]
-------------------------------------------------
--@Override
--public void start(){
-- // the selector allows to apply a regex on the configuration key to select a
-- // a configuration sub set.
-- String selector = "user.";
-- vertx().eventBus().send(
-- "CONFIG-MAP", // event bus address
-- selector,
-- new Handler<AsyncResult<Message<String>>>() {
-- @Override
-- public void handle(AsyncResult<Message<String>> reply) {
-- testContext.assertNotNull(reply.result());
-- testContext.assertNotNull(reply.result().body());
-- Map<String,String> config = Json.decodeValue(reply.result().body(),
-- Map.class);
-- // do something with the config
-- // ...
-- }
-- });
-------------------------------------------------
--
--
--Similar only single values can be accessed:
--
--[source, java]
-------------------------------------------------
--@Override
--public void start(){
-- vertx().eventBus().send(
-- "CONFIG-VAL", // event bus address
-- "user.home", // property key
-- new Handler<AsyncResult<Message<String>>>() {
-- @Override
-- public void handle(AsyncResult<Message<String>> reply) {
-- String value = reply.result().body();
-- // do something with the config value
-- // ...
-- }
-- });
-------------------------------------------------
--
--
--Finally the event bus targets to be used can be configured using Tamaya configuration,
--see the code snippet from the implementation:
--
--[source, java]
-------------------------------------------------
--@ConfigProperty(key = "tamaya.vertx.config.map", defaultValue = "CONFIG-MAP")
--private String mapBusTarget;
--
--@ConfigProperty(key = "tamaya.vertx.config.value", defaultValue = "CONFIG-VAL")
--private String valBusTarget;
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_yaml.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_yaml.adoc
index f6c07b6,f6c07b6..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_yaml.adoc
+++ /dev/null
@@@ -1,118 -1,118 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Builder
--
--toc::[]
--
--
--[[YAML]]
--== Tamaya YAML (Extension Module)
--
--Tamaya _YAML_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== Overview
--
--Tamaya _YAML_ provides support for reading configuration using the YAML format (yaml.org). YAML hereby
--use intendation for expressing hierarchy, which makes yaml configuration files very easily readable and compact.
--
--
--=== Compatibility
--
--The YAML module is based on Java 8, so it will run on Java 8 and beyond.
--
--
--=== Installation
--
--To use YAML as configuration format you must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-yaml</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--This extension also transitively requires the +tamaya.formats+ module.
--
--
--=== Reading configuration in YAML
--
--For reading YAML based onfiguration most easily a +YAMLFormat+ can be provided:
--
--[source, java]
-------------------------------------------------
--PropertySource ps = ConfigurationFormats.createConfigSource(
-- getClassLoader().getResource("myFileConfig.yaml"), new YAMLFormat()));
-------------------------------------------------
--
--
--=== Examples
--
--The YAML module adds instances of +ConfigurationFormat+ so YAML configuration can be read and mapped to the
--according property values. E.g. the following file is a simple and correct YAML configuration:
--
--[source,yaml]
------------------------------------------------------------------
--invoice: 34843
--date : 2001-01-23
--bill-to: &id001
-- given : Chris
-- family : Dumars
-- address:
-- lines: |
-- 458 Walkman Dr.
-- Suite #292
-- city : Royal Oak
-- state : MI
-- postal : 48046
--ship-to: *id001
--product:
-- - sku : BL394D
-- quantity : 4
-- description : Basketball
-- price : 450.00
-- - sku : BL4438H
-- quantity : 1
-- description : Super Hoop
-- price : 2392.00
--tax : 251.42
--total: 4443.52
--comments:
-- Late afternoon is best.
-- Backup contact is Nancy
-- Billsmer @ 338-4338.
------------------------------------------------------------------
--
--Hereby the above file, by default is mapped as follows into +Map<String,String>+ typed properties:
--
--[source,listing]
------------------------------------------------------------------
--invoice -> 34843
--date -> Tue Jan 23 01:00:00 CET 2001
--bill-to.family -> Dumars
--bill-to.given -> Chris
--bill-to.address.state -> MI
--bill-to.address.postal -> 48046
--bill-to.address.city -> Royal Oak
--bill-to.address.lines -> 458 Walkman Dr.
--Suite #292
--
--ship-to.given -> Chris
--ship-to.address.state -> MI
--ship-to.family -> Dumars
--ship-to.address.postal -> 48046
--ship-to.address.city -> Royal Oak
--ship-to.address.lines -> 458 Walkman Dr.
--Suite #292
--
--product -> {sku=BL394D, quantity=4, description=Basketball, price=450.0},{sku=BL4438H, quantity=1, description=Super Hoop, price=2392.0}
--_product.collection-type -> List
--
--tax -> 251.42
--total -> 4443.52
--comments -> Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/quickstart.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/quickstart.adoc
index ac32884,ac32884..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/quickstart.adoc
+++ /dev/null
@@@ -1,224 -1,224 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--== Apache Tamaya: Quickstart
--
--
--The fastest way to start with Tamaya is just using the _Core_ implementation,
--implementing the **Config JSR API** in a minimalistic way. For that add the following
--Maven dependency to your project:
--
--=== Adding the Tamaya Dependency
--
--[source,xml,subs="verbatim,attributes"]
------
--<dependency>
-- <groupId>{tamaya_mvn_group_id}</groupId>
-- <artifactId>tamaya-core</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
------
--
--=== Start Coding
--
--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:
--
--[source,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));
------
--
--
--=== Add/define your configuration data
--
--As seen you can immedeatly start working with your configuration backend, without adding any kind of
--default configuration. Nevertheless the _core_ implementation also comes with a _default_ mechanism,
--where you can store your configuration as +.properties+ in your classpath:
--
--[source]
------
--META-INF/javaconfig.properties
------
--
--Additionally also system properties are taken into account, hereby overriding the _default_ properties.
--Overall Tamaya by default defines the following configuration model per default (most significant first):
--
--. Environment Properties
--. System Properties
--. `META-INF/javaconfig.properties`
--
--
--== Advanced Topics
--
--=== Multiple configuration files
--
--By default you can provide multiple `javaconfig.properties` files, e.g. as part
--of multiple jars loaded into your system. The system creates one
--`ConfigSource` for each file found on the classpath. All `ConfigSource`
--instances created are ordered by their precedence.
--
--By default the precendence of a +ConfigSource+ is evaluated based on an _ordinal_ value
--calculated as follows:
--
--. the systems checks for a `config.ordinal` configuration value and tries to convert to
-- an `int` ordinal value.
--. the systems checks if the config source has a method +int getOrdinal()+. If present
-- the result is used as ordinal.
--. the systems checks if the config source has a `@Priority` annotation and uses the
-- annotation's value as ordinal.
--. if all of the above fails, +0+ is assumed as ordinal.
--
--NOTE: Since evaluation of the `config.ordinal` is always done first, it is possible to change
-- the ordinal value by adding a corresponding configuration entry to a config source.
--
--Tamaya Core uses the following default ordinals (see also the ConfigJSR spec):
--
--[width=70]
--[cols="3,1", option="headers"]
--|===
--| Source | Ordinal
--| System Properties | 400
--| Environment Properties | 300
--| Properties from `META-INF/javaconfig.properties` | 100
--|===
--
--That means that the value of a configuration variable `x` passed as `-Dx=yes` has
--a higher precedence then the entry for configuration variable `x` specified in
--`META-INF/javaconfig.properties` as `x=no`.
--
--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:
--
--[source]
------
--# override default ordinal for property files
--config.ordinal=123
------
--
--This assigns an ordinal of 123 to each entry in that config source providing this configuration
--properties.
--
--=== Using additional features of Tamaya
--
--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 link:extensions/extensions.html[this list] for a complete
--overview.
--
--==== Dynamic Resolution and Value Placeholders
--
--[source,xml,subs="verbatim,attributes"]
------
--<dependency>
-- <artifactId>org.apache.tamaya.ext</id>
-- <artifactId>tamaya-resolver</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
------
--
--
--With that it is possible to define values with Unix styled placeholders that are
--resolved on configuration access, e.g.
--`mykey=my${dynamicValue}´. For further details refer to the module documentation.
--This module also provides a `Resolver` singleton:
--
--[source,java]
------
--String myExpression = ...;
--String resolved = Resolver.evaluateExpression(myExpression);
------
--
--
--==== Ant-styled Path Resolution of Resources
--
--[source,xml,subs="verbatim,attributes"]
------
--<dependency>
-- <artifactId>org.apache.tamaya.ext</id>
-- <artifactId>tamaya-resolution</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
------
--
--This module provides a `Resolver` singleton that allows to
--resolve configuration resources using a ant-styled resource
--description, e.g.
--
--
--[source,xml,subs="verbatim,attributes"]
------
--Collection<URL> urls = ResourceResolver.getResources("META-INF/cfg/**/*.properties");
------
--
--For further details refer to the module documentation.
--
--
--==== Configuration Injection
--
--[source,xml,subs="verbatim,attributes"]
------
--<dependency>
-- <artifactId>org.apache.tamaya.ext</id>
-- <artifactId>tamaya-inject</artifactId>
-- <version>{tamaya_version_development}</version>
--</dependency>
------
--
--With this extension you can let Tamaya inject configuration into instances of
--annotated classes or let Tamaya implement a configuration template.
--
--Corresponding configuration:
--
--[source,xml,subs="verbatim,attributes"]
------
--public class MyType {
-- @Config("my.key")
-- private String typeName;
--
-- public String getName() {
-- return name;
-- }
--}
--
--MyType type = new MyType();
--ConfigurationInjector.configure(type);
------
--
--Or the same as template:
--
--[source,xml,subs="verbatim,attributes"]
------
--public interface MyTypeTemplate {
-- @Config("my.key")
-- public String getName();
--}
--
--MyTypeTemplate type = ConfigurationInjector.createTemplate(MyTypeTemplate.class);
------
--
--Currently the following resolvers are available:
--
--[width="60"]
--[cols="1,4"]
--|===
--| Conf
--| Cross-reference to another configuration entry
--
--| URL
--| Referencing a resource addressable by an URL.
--
--| File
--| Reference to a file, replacing the expression with the file's text value.
--
--| Resource
--| Reference to classpath resource, replacing the expression with the resource's text value.
--
--|===
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/spisupport.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/spisupport.adoc
index 2b2fb4a,2b2fb4a..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/spisupport.adoc
+++ /dev/null
@@@ -1,63 -1,63 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya: Base Module
--
--toc::[]
--
--
--[[SPISupport]]
--== Tamaya Base
--
--Tamaya _Base_ is a core module only depending on the ConfigJSR API. It implements various API and SPI related
--artifacts in a portable way. Tamaya's core module reuses this functionality to build up a fully fledged
--Tamaya ConfigJSR API implementatation.
--
--=== What functionality does this module provide?
--
--Tamaya _Base_ provides a few helpful base classes that can be used to implement aspects of a Configuration system:
--
--* +BaseConfigSource+ provides an abstract *base class* for implementation of your own ConfigSources.
--* +DefaultConfig+ provides you with a simple implementation of the +Config+ interface. This is also very useful
-- for mocking configuration during test execution, but not only constraint to that use case.
--* An +EnumConverter+,that is a converter implementation that can automatically select the currect enumeration values based
-- on a configured entry.
--* +MapConfigSource+ implements a config source based on +java.util.Map+.
--* +PriorityServiceComparator+ compares arbitrary services based on their +@Priority+ annotations (also handling the
-- case, where no such annotation is present).
--* +PropertiesResourceConfigSource+ is an implementation of a +ConfigSource+ based on a +Properties+ instance,
-- loadable from any +URL+.
--+ +ConverterManager+ is a useful service class managing registered instances of +Converter+. It provides a simple
-- way to use type conversion logic.
--+ +Filter+ allow interception of evaluated config values before they get passed to any type conversion logic.
--+ +FilterContext+ provides another helpful class that manages +Filter+ instances and provides an
-- easy to use high level API.
--+ +ConfigSourceComparator+ provides an implementation that compares +ConfigSources+ based on their +getOrdinal()+
-- values and their class names.
--
--NOTE: It is highly recommended that you also read the link:../core.html[documentation] of Tamaya's
-- core implementation, since this describes the abstrations in use in more
-- detail. This module allows to reuse Tamaya's implementation artifacts but
-- still allows alternate implementations of the core API to be used.
--
--=== Compatibility
--
--The module is based on Java 8, so it will run on Java 8 and beyond.
--
--
--=== Installation
--
--To use Tamaya's _Base_ you only have to add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya</groupId>
-- <artifactId>tamaya-base</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--The component will not register any components but only provides portable base classes for some common SPI
--implementation tasks. It only depends on the API, so it should be safely reusable also with other implementations
--of the Tamaya API as well.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/usecases.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/usecases.adoc
index d97d2c2,d97d2c2..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/usecases.adoc
+++ /dev/null
@@@ -1,472 -1,472 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--== Apache Tamaya: Use Cases and Requirements
--
--toc::[]
--
--== Use Cases
--
--=== Simple Access
--
--Users want to be able to access configuration in a unified way both in SE and EE. EE may provide additional
--mechanism, such as injection, but the SE mechanisms should work as well, so any code written in SE is fully
--portable to EE as well.
--This can only be achieved by providing a static accessor, e.g.
--
--[source,java]
--------------------------------------------------------------
--Config config = ConfigProvider.getConfig();
--------------------------------------------------------------
--
--The call above should work exactly the same in EE. To enable this the static call must be delegated in the
--internals of the singleton, depending on the runtime. In EE the executing component can behave contextually,
--or even be loaded within the CDI environment (at least for post loading, application runtime aspects, but not earlier).
--
--Additionally in EE it should also be possible to inject Configuration, which gives you the same results as the call
--above:
--
--[source,java]
--------------------------------------------------------------
--@Inject
--private Config cfg;
--------------------------------------------------------------
--
--
--=== Simple Lookup of Properties
--
--Users just want to create a configuration ad hoc, from given property files. The
--files could be locally in the file system, on the classpath.
--
--Tamaya should provide a simple Java API for accessing key/value based configuration. Hereby users want to access
--properties as simple String values.
--
--Hereby returning Java 8 Optional values must be considered as well, instead of returning +null+.
--
--
--=== Value Placeholders
--
--Users just want to to be able to add placeholders to the values of configuration (not the keys). The mechanisms for
--resolving the placeholders hereby should be not constraint to one single lanmguage like EL. Instead of different
--replacement strategies should be selectable, e.g. by prefixing an expression with the name of the resolver that
--should do the work (eg +"blabla ${env:HOME} using Java version ${sys:java.version}."+.
--This allows resolution mechanism to be isolated easily and also allows to use simpler mechanisms, if no more complex
--ones like EL are required. This is especially useful to deal with low resource environment like ME.
--
--
--=== Type Safe Properties
--
--Users just want to access properties not only as Strings, but let Tamaya do the conversion to the required
--or the configred target type. By defauklt all java.ui.lang wrapper and primitive types should be supported, but also
--other common types like date/time types, math numeric types and more.
--
--It must be possible that users can register their own custom types.
--
--Finally users also want to be able to dynamically provide or override type adaption (conversion), when reading a value,
--for a certain key/value pair.
--
--
--=== Configuration Templates
--
--Users want to be able to let Tamaya implement an interface template based on configuration.
--This use case is pretty similar to the injection use case. Basically the values are not injected,
--but cached within the template proxy returned, e.g. as +DynamicValue+.
--Similarly it could even be possible to define callback methods (default methods)
--or register listeners to DynamicValue instances returned.
--
--Templates hereby can easily be managed, but provide a excellent mechanism to provide type-safe configuration
--to clients in a very transparent way. Details can be controlled by using the same annotations as for
--normal configuration injection.
--
--
--=== Java 8 Functional Support
--
--Users want to be able to benefit from the new programming styles introduced with Java 8. Configuration
--should provide extension points for different aspects, where additional code can be hooked in easily.
--In short: were possible functional interfaces should be modelled.
--
--Examples:
--
--* code that converts a configuration to another kind of configuration: +UnaryOperator<Configuration>+
--* code that creates any kind of result based on a configuration: +Function<Configuration,T>+
--* Adapters for type conversion are defined as +Function<String,T>+
--* Key, value filters ccan be modelled as +BiFunction<String,String,String>+
--* etc.
--
--
--=== Configuration Locations
--
--Users want to be able to
--
--* read configuration from different locations.
--* By default classpath and file resources are
-- supported. But similarly remote access using a JSON ReST call should be possible.
--* Tamaya should define a JSON and XML format for configuration.
--* Configuration locations should be scannable using ant-styled resource patterns, if possible.
--* Scanning and reading logic can be modularized by using a +ConfigReader+ interface.
--
--
--=== Configuration Formats
--
--Users want to be able to use the format they prefer.
--
--* properties, xml-properties and ini-format should be supported by default
--* Other/custom formats should be easily addable by registering or providing the format on configuration evaluation (read).
--* When possible Tamaya should figure out which format to be used and how the InputStream should be correctly
-- interpreted.
--
--
--=== Multiple Configurations
--
--When systems grow they must be modularized to keep control. Whereas that sounds not really fancy, it leads to additional
--aspects to be considered by a configuration system.
--
--* Different code modules, libraries, plugins or products want to have their "own" separated configuration.
--* Similar it should be possible to add fully specific additional configurations.
--
--The default configuration hereby should always be present, whereas additional configurations are optional.
--Users want to be able to check the availability of such an additional configuration.
--
--Of course, additional configuration must be identifiable. The best way to do is to be discussed, nevertheless the
--mechanism must not depend on Java EE and the identifying keys must be serializable easily.
--Basically simple names are sufficient and woukld provide exact this required functionality.
--
--
--=== External Configuration
--
--Users want to be able to replace, override, extend or adapt any parts or all of an existing configuration from
--external sources.
--This also must be the case for multi-context environments, where the context identifiers are
--the only way to link to the correct remote configuration.
--
--
--=== Context Dependent Configuration
--
--In multi tenancy setups or complex systems a hierarchical/graph model of contexts for configurations is required, or different runtime contexts are executed in parallel
--within the same VN. What sounds normal for EE also may be the case for pure SE environments:
--
--* Users want to be able to model different layers of runtime context
--* Users want to identify the current layer, so configuration used may be adapted.
--
--
--
--=== Dynamic Provisioning (UC8)
--
--In Cloud Computing, especially the PaaS and SaaS areas a typical use case would be that an application (or server)
--is deployed, configured and started dynamically. Typically things are controlled by some "active controller components",
--which are capable of
--
--* creating new nodes (using IaaS services)
--* deploying and starting the required runtime platform , e.g. as part of a PaaS solution.
--* deploying and starting the application modules.
--
--All these steps require some kind of configuration. As of today required files are often created on the target node
--before the systems are started, using proprietary formats and mechanism. Similarly accessing the configuration in place
--may require examining the file system or using again proprietary management functions. Of course, a configuration
--solution should not try to solve that, but it can provide a significant bunch of functionality useful in such scenarios:
--
--* provide remote capabilities for configuration
--* allow configuration to be updated remotely.
--* allow client code to listen for configuration changes and react as needed.
--
--
--=== Minimal Config Source SPI
--
--Users expect that implementing an additional configuration config source is as easy as possible.
--So there should be an SPI defined that allows any kind of data source to be used for providing configuration data.
--The interface to be implemented is expected to be minimal to reduce the implementation burden. Default
--methods should be used where possible, so only a few methods are expected to be required to implement.
--
--
--=== Combine Configurations
--
--Users want to be able to combine different configurations to a new configuration instance.
--Hereby the resulting configuration can be
--
--* a union of both, ignoring duplicates (and optionally log them)
--* a union of both, duplicates are ignored
--* a union of both, conflicts are thrown as ConfigException
--* an intersection of both, containing only keys present and equal in both configurations
--* an arbitrary mapping or filter, modelled by an +CombinationPolicy+, which basically can be modelled
-- as +BiFunction<String, String, String>+, hereby
-- ** a result of +null+ will remove the key
-- ** any other result will use the value returned as final value of the combination.
--
--
--=== MX/ReST Management
--
--Users want to be have comprehensive management support, which should allow
--
--* to change configuration
--* to remove configuration
--* to view configuration and its provider details
--
--
--=== Adaptable Service Context
--
--Tamaya should support an adaptable +ServiceContext+ to resolve any kind of implememntation services, both API services as core
--framework services. The +ServiceContext+ should be dynamically replecable by configuring an alternate instance of
--using the Java *ServiceContet+.
--
--This decouples component usage from its load and management part and als greatly simplifies integration with
--new/alternate runtime environments.
--The service context is exptected to provide
--
--* single singleton instances: these service can be cached.
--* access to multiple instances which implement some commons SPI interface.
--* as useful priorization of components is done by the model itself.
--
--
--=== Configuration Injection
--
--Users want to be able to polulate configured items by injecting configured values. Hereby
--
--* the lifecycle of the instances is not managed by Tamaya
--* all references to items configured are managed as weak references, to prevent memoryleaks.
--* Injection should if possible evaluate the properties by defaults. Even properties without
-- any annotations are possible.
--* Users expect to exclude certain properties from calculation
--* Beside injection of properties it is also possible to call setter methods with one parameter similarly.
--* Basically injection is performed, when the instance is passed to the Tamaya configuration system. It should also
-- be possible to inject/provide final values, especially Strings. Changes on configured values should be
-- reflected in the current value. Setters methods similarly can be called again, with the new values, on changes.
--* Users expect to control dynamic values and recall of setter methods, basically the following strategies should be
-- supported:
-- ** inject only once and ignore further changes.
-- ** reinject/reinitialize on each change
--
--* Dynamic Values can easily be modeled as +ConfiguredValue+ instances, which should have the following functionality:
-- ** access the current value
-- ** access the new value
-- ** access the latest value access time in ms
-- ** access the latest value update time in ms
-- ** evaluate easily if the value has changed since the last access
-- ** accept the change
-- *** as a shortcut it should be possible to accept the change on access of the value implicitly, hereby always accessing
-- the latest valid value.
-- ** ignore the change
-- ** register +Consumer<DynamicValue>+ liasteners to listen on the changes (ans also removing them later again).
--
--All observing functionality can be done completely asynchronously and in parallel.
--
--
--[[Requirements]]
--== Requirements
--=== Core Configuration Requirements
--==== General
--
--Tamaya must provide a Java SE API for accessing key/value based configuration. Hereby
--
--* +Configuration+ is modelled by an interface
--* +Configuration+ is organized as key/value pairs, using a subset of functionality present on +Map<String,String>+ as
-- follows:
-- ** access a value by key (+get+)
-- ** check if a value is present (+containsKey+)
-- ** get a set of all defined keys (+keySet+)
-- ** a configuration must be convertible to a +Map+, by calling +toMap()+
-- ** a configuration must provide access to its meta information.
--* +Configuration+ value access methods must never return null.
--* The API must support undefined values.
--* The API must support passing default values, to be returned if a value is undefined.
--* The API must allow to throw exceptions, when a value is undefined. Customized exceptions hereby should be supported.
--* Properties can be stored in the classpath, on a file or accessible by URL.
--* Properties can be stored minimally in properties, xml-properties or ini-format.
--
--
--==== Minimalistic Property Source
--
--For enabling easy integration of custom built configuration sources a minimalistic API/SPI must be defined, that
--
--* is modelled by an interface
--* is a minimal subset of +Configuration+ necessary to implement a configuration.
--* must be convertible to a "Configuration+.
--
--==== Extension Points
--
--For supporting more complex scenarios, +Configuration+
--
--* must implement the composite pattern, meaning new +Configuration+ instances can be created by combining existing
-- configurations.
--* must be adaptable, by creating a new configuration by applying a +UnaryOperator<COnfiguration>+ to it.
--* must be queryable, by passing a +ConfigQuery+ to an +Configuration+ instance.
--
--
--==== Type Safety
--
--Besides Strings +Configuration+ should also support the following types:
--
--* Primitive types
--* Wrapper types
--* All other types (by using a +PropertyAdapter+
--
--Hereby type conversion should be done as follows:
--
--. Check if for the given target type an explicit adapter is registered, if so, use the registered adapter.
--. If no adapter is present, check if the target type T has static methods called +T of(String), T getInstance(String), T valueOf(String), T from(String)+. If so
--use this method to create the non value of T.
--. Check if the target type has a constructor T(String). If so, try to instantiate an instance using the constructor.
--. Give up, throw a IllegalArgument exception.
--
--=== Configuration Fomats
--
--By default Tamaya support the following configuration formats:
--
--* .properties
--* .xml properties
--* .ini files
--
--It must be possible to add additional formats by registering them with the current +ServiceContext+.
--
--=== Mutability
--
--* Configurations can be mutable, mutability can be accessed as a property.
--* Configuration can be changed by collecting the changes into a +ConfigCHangeSet+ and apply this set to the
-- given +Configuration+ instance.
--* Besides the points above, +Configuration+ is immutable.
--
--=== Serializability and Immutability of Configuration
--
--* Configuration is modelled as a service. Therefore serialization may not work. This can be mitigated by adding
-- a freeze feature, where the know key/value pairs are extracted into an immutable and serializable form.
--
--=== Configuration Combination Requirements
--
--At least the following composition policies must be supported:
--
--* override: subsequent entries override existing ones.
--* aggregate-exception: key/values were added, in case of conflicts a +ConfigException+ must be thrown.
--* aggregate-ignore-duplicates: similar to union, whereas duplicates are ignored (leaving the initial value loaded).
--* aggregate-combine: conflicting entries were resolved by adding them both to the target configuration by
-- redefining partial keys.
--* custom: any function determining the key/values to be kept must be possible
--
--When combining configuration it must also be possible to override (file/classpath) configuration by
--
--* system properties.
--* command line arguments.
--
--
--=== Configuration Injection
--
--As metnioned configuration can be injected by passing a unconfigured instance of an annotated class to the
--+ConfigurationInjector.configure+ static method:
--
--[source, java]
--.Configuring a POJO
------------------------------------------------------
--MyPojo instance = new MyPojo();
--ConfigurationInjector.configure(instance);
------------------------------------------------------
--
--Hereby
--* It must be possible to define default values to be used, if no valid value is present.
--* It must be possible to define dynamic expressions, at least for default values.
--* The values configured can be reinjected, if the underlying configuration changes. This should also be the case
-- for final classes, such as Strings.
--* Reinjection should be controllable by an loading policy.
--* It must be possible to evaluate multiple keys, e.g. current keys, and as a backup deprecated keys
-- from former application releases.
--* It must be possible to evaluate multiple configurations.
--* The type conversion of the properties injected must be configurable, by defining a +PropertyAdapter+.
--* The value evaluated for a property (before type conversion) must be adaptable as well.
--* It must be possible to observe configuration changes.
--
--Similar annotations must be present at least:
--
--* *@Config* defining the key of the property to be evaluated. It takes an optional value, defining the
-- property name. It must be possible to add multiple annotations of this kind to define an order of evaluation
-- of possible keys.
--* The *@Config* annotation should also provide an optional default String value, to be used, when no other key is present.
--* *@WithConfig* (optional) defines the name of the configuration to be used. Similar to +@Config+ multiple
-- configuration can be defined for lookup.
--* *@WithConfigOperator* allows to adapt the String value evaluated, *before* it is passed as input to injection or
-- type conversion.
--* *@WithConverter* allows to adapt the conversion to the required target type, hereby overriding any default
-- conversion in place.
--* *@WithLoadPolicy* allows to define the policy for (re)injection of configured values.
--* *@ObservesConfigChange* allows to annotate methods that should be called on configuration changes.
--* *@DefaultAreas" allows to define a key prefix key to be used for the configured key, if no absolute key
-- is defined.
--
--=== Configuration Templates
--
--For type safe configuration clients should be able to define an interface and let it implement by the
--configuration system based on +Configuration+ available:
--
--* Clients define an interface and annotate it as required (similar to above)
--* The interface methods must not take any arguments
--* The configuration system can be called to return such an interface implementation.
--* The configuration system returns a proxy hereby providing type-safe access the values required.
--* Similar to configured types also templates support multiple values and custom adapters.
--* It is possible to listen on configuration changes for templates, so users of the templates
-- may react on configuration changes.
--
--The following snippet illustrates the requirements:
--
--[source, java]
--.Type Safe Configuration Template Example
------------------------------------------------------
--public interface MyConfig {
--
-- @Config(key="myCurrency", defaultValue="CHF")
-- String getCurrency();
--
-- @Config(key="myCurrencyRate")
-- Long getCurrencyRate();
--
--}
------------------------------------------------------
--
--Templates can be accessed by calling the +ConfigInjector.createTemplate(Class)+ method:
--
--[source, java]
--.Accessing a type safe Configuration Template
------------------------------------------------------
--MyConfig config = ConfigInjector.createTemplate(MyConfig.class);
------------------------------------------------------
--
--[[RequirementsServer]]
--=== Server Configuration Requirements
--
--* Ensure Configuration can be transferred over the network easily.
--* Beside serializability text based formats for serialization in +XML+ and +JSON+ must be defined.
--* A management API must be defined, which allows to inspect the configuration in place, e.g. using
-- JMX or REST services.
--
--[[RequirementsJavaEE]]
--
--Java EE leads to the following requirements:
--
--* Configuration must be contextual, depending on the current runtime context (e.g. boot level, ear, war, ...).
--* Hereby contextual aspects can even exceed the levels described above, e.g. for SaaS scenarios.
--* Resources can be unloaded, e.g. wars, ears can be restarted.
--* The different contextual levels can also be used for overriding, e.g. application specific configuration
--may override ear or system configuration.
--* Configuration may be read from different sources (different classloaders, files, databases, remote locations).
--* Configuration may be read in different formats (deployment descriptors, +ServiceLoader+ configuration, alt-DD feature, ...)
--* JSF also knows the concept of stages.
--* Many SPI's of Java EE require the implementation of some well defined Java interface, so it would be useful if the
-- configuration solution supports easy implementation of such instances.
--* In general it would be useful to model the +Environment+ explicitly.
--* Configuration used as preferences is writable as well. This requires mutability to be modelled in way, without the
-- need of synchronization.
--* JNDI can be used for configuration as well.
--
--[[RequirementsMultitenancy]]
--
--Configurations made in the tenant or user layer override the default app configuration etc., so
--
--* It must be possible to structure Configuration in layers that can override/extend each other.
--* The current environment must be capable of mapping tenant, user and other aspects, so a corresponding configuration
-- (or layer) can be derived.
--
--[[RequirementsExtensions]]
--=== Extensions Requirements
--
--It must be possible to easily add additional functionality by implementing external functional interfaces operating
--on +Configuration+.
--
--* +UnaryOperator<Configuration>+ for converting into other version of +Configuration+.
--* +ConfigQuery<T>+ extending +Function<T, Configuration>+.
--
--
[5/8] incubator-tamaya-site git commit: TAMAYA-274 Updated
documentation. TAMAYA-355 Updated documentation. TAMAYA-353 Updated
documentation.
Posted by an...@apache.org.
TAMAYA-274 Updated documentation.
TAMAYA-355 Updated documentation.
TAMAYA-353 Updated documentation.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/1c033714
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/1c033714
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/1c033714
Branch: refs/heads/master
Commit: 1c033714eb241b602ea7b46bd46c5e6d5aa65381
Parents: 15c355a 43f983e
Author: Anatole Tresch <at...@gmail.com>
Authored: Mon Nov 5 00:14:41 2018 +0100
Committer: Anatole Tresch <at...@gmail.com>
Committed: Mon Nov 5 00:14:41 2018 +0100
----------------------------------------------------------------------
content/documentation-new/api.adoc | 778 ------------------
content/documentation-new/core.adoc | 283 -------
content/documentation-new/extensions.adoc | 65 --
.../documentation-new/extensions/mod_camel.adoc | 132 ---
.../documentation-new/extensions/mod_cdi.adoc | 244 ------
.../extensions/mod_classloader_support.adoc | 79 --
.../extensions/mod_collections.adoc | 245 ------
.../extensions/mod_consul.adoc | 66 --
.../documentation-new/extensions/mod_etcd.adoc | 192 -----
.../extensions/mod_events.adoc | 308 -------
.../extensions/mod_features.adoc | 87 --
.../extensions/mod_filter.adoc | 117 ---
.../extensions/mod_formats.adoc | 290 -------
.../extensions/mod_functions.adoc | 136 ----
.../extensions/mod_hazelcast.adoc | 118 ---
.../extensions/mod_injection.adoc | 481 -----------
.../documentation-new/extensions/mod_jndi.adoc | 68 --
.../extensions/mod_jodatime.adoc | 80 --
.../documentation-new/extensions/mod_json.adoc | 80 --
.../extensions/mod_management.adoc | 97 ---
.../extensions/mod_metamodel.adoc | 632 --------------
.../extensions/mod_mutable_config.adoc | 236 ------
.../extensions/mod_optional.adoc | 61 --
.../documentation-new/extensions/mod_osgi.adoc | 814 -------------------
.../extensions/mod_remote.adoc | 111 ---
.../extensions/mod_resolver.adoc | 131 ---
.../extensions/mod_resources.adoc | 167 ----
.../extensions/mod_server.adoc | 239 ------
.../extensions/mod_spring.adoc | 177 ----
.../extensions/mod_usagetracker.adoc | 161 ----
.../extensions/mod_validation.adoc | 104 ---
.../documentation-new/extensions/mod_vertx.adoc | 185 -----
.../documentation-new/extensions/mod_yaml.adoc | 118 ---
content/documentation-new/quickstart.adoc | 224 -----
content/documentation-new/spisupport.adoc | 63 --
content/documentation-new/usecases.adoc | 472 -----------
templates/footer.thyme | 7 +-
37 files changed, 5 insertions(+), 7843 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/api.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/api.adoc
index 581c368,581c368..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/api.adoc
+++ /dev/null
@@@ -1,778 -1,778 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--[[CoreDesign]]
--== Apache Tamaya: Configuration API
--
--Tamaya implements the Java JSR 382 Configuration API. You will find the spec link:http://jcp.org/jsr/?id=382[here].
--Also worth reading might be Tamaya's link:../highleveldesign.html[High Level Design Documentation].
--
--[[API]]
--== The Configuration API
--The Configuration API provides the main artifacts to access and change configuration, which are:
--
--* The package +javax.config+ defines a simple but complete SE *API* for accessing key/value based _Config_:
-- ** +Config+ hereby models _configuration_, the main interface. +Config+ provides
-- *** access to literal key/value pairs.
-- ** +ConfigProvider+ provides with +getConfig()+ the static entry point for accessing configuration.
-- A default +Config+ instance is automatically created on first access collecting and adding all discoverable artifacts.
--
--* The package +javax.config.spi+ provides interfaces used for extending and/or
-- adapting functionality, as well as artifacts for creating
-- +Config+ instances programmatically:
-- ** _ConfigSource:_ is the interface to be implemented for adding configuration entries. A +ConfigSource+ hereby
-- *** is minimalistic and can be implemented in any way. E.g. there is no distinction that
-- the configuration data provided is managed locally, remotely. There is even no
-- requirement that the configuration data is always fully available. Summarizing a
-- +ConfigSource+
-- *** provides property access for single key/value pairs in _raw_ format (meaning no postprocessing
-- is applied yet).
-- *** can _optionally_ provide access to a +Map<String,String>+, providing all its properties at once.
-- *** defines the default ordinal to be used for establishing the order of significance among all
-- auto-discovered property sources.
-- ** _ConfigSourceProvider:_ allows to automatically register multiple property sources, e.g. all config files found in
-- a file system folder.
-- ** +ConfigProviderResolver+ defines the abstract entry point to be extended for providing configuration. It is the
-- main implementation hook for an API implementation provider.
-- ** A +Config+ can also be created by using a +ConfigBuilder+, which can be obtained from the +ConfigProviderResolver+.
-- It allows to build up a +Config+ by adding config sources and converters in various ways.
--
-- == Tamaya Configuration API Extensions
--
-- Tamaya provides a few mechanisms that extend the standard API, which have shown to be very useful:
--
--* +Filter+ allows filtering of property values prior before getting returned to the caller. Filters by default are
-- registered as global filters, filtering _raw_ values. The final +String+ value of a configuration entry is the
-- final value after all registered filters have been applied.
--* A +ConfigValueCombinationPolicy+ optionally can be registered to change the logic how key/value
-- pairs from subsequent property sources in the property source chain are combined to calculate the final
-- _raw_ value passed over to the filters registered.
--* Tamaya provides a much more powerful +TamayaConfigBuilder+, extending the default +ConfigBuilder+
-- adding additional methods for managing the config source order, adding filters and multiple converters.
--* Finally Tamaya uses a flexible +ServiceContext+ and +ServiceContextManager+ to provide an abstraction to
-- the underlying runtime environment, allowing different component loading and lifecycle strategies to be used.
-- This is very useful since component (service) loading in Java SE, Java EE, OSGI and other runtime environments
-- may differ significantly. In most cases even extension programmers will not have to deal with these two
-- artifacts.
--
--To integrate Tamaya modules with config implementations, the only things the implementations should do, is to
--implement the +ConfigContextSupplier+ with an implementation of +Config+. Hereby a +ConfigContext+ is the abstraction
--of the inner components (+ConfigSource, Filter, ConfigValueCombinationPolicy, Converter+) required to implement a
--+Config+. Also the ordering of the config sources, filters and converters is defined by the context.
--
--Summarizing a +ConfigurationContext+ contains the ordered property sources, property filters, converters and combination
--policy used.
--
--
--[[APIKeyValues]]
--=== Excourse: Key/Value Pairs
--
--Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple
--and most commonly used approach is 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.
--
--[source,properties]
--.A simple properties file
----------------------------------------------
--a.b.c=cVal
--a.b.c.1=cVal1
--a.b.c.2=cVal2
--a=aVal
--a.b=abVal
--a.b2=abVal
----------------------------------------------
--
--Now you can use +java.util.Properties+ to read this file and access the corresponding properties, e.g.
--
--[source,properties]
----------------------------------------------
--Properties props = new Properties();
--props.readProperties(...);
--String val = props.getProperty("a.b.c");
--val = props.getProperty("a.b.c.1");
--...
----------------------------------------------
--
--
--==== Why Using Strings Only
--
--There are good reason for keeping non-String-values as core storage representation of configuration. Mostly
--there are several huge advantages:
--
--* Strings are simple to understand
--* Strings are human readable and therefore easy to prove for correctness
--* Strings can easily be used within different languages, different VMs, files or network communications.
--* Strings can easily be compared and manipulated
--* Strings can easily be searched, indexed and cached
--* It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in
-- production as well in testing.
--
--On the other hand there are also disadvantages:
--
--* Strings are inherently not type safe, they do not provide validation out of the box for special types, such as
--numbers, dates etc.
--* In many cases you want to access configuration in a typesafe way avoiding conversion to the target types explicitly
-- throughout your code.
--* Strings are neither hierarchical nor multi-valued, so mapping hierarchical and collection structures requires some
-- extra efforts.
--
--Nevertheless most of these disadvantages can be mitigated easily, hereby still keeping all the benefits from above:
--
--* Adding type safe adapters on top of String allows to add any type easily, that can be directly mapped from String.
-- This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more.
--* Also multi-valued, complex and collection types can be defined. A corresponding +PropertyAdapter+ knows how to
-- parse and create the target instance required.
--* Strings ca also be used as references pointing to other locations and formats, where configuration is
-- accessible.
--
--
--[[API Configuration]]
--
--=== Config
--
--+Config+ is the main artifact modelling configuration. It allows reading single property values or all known
--properties, but also supports type safe access:
--
--[source,java]
--.Interface Configuration
----------------------------------------------
--public interface Config{
-- <T> T getValue(String key, Class<T> type);
-- <T> Optional<T> getOptionalValue(String key, Class<T> type);
-- Iterable<String> getPropertyNames();
--
-- Iterable<ConfigSource> getConfigSources();
--}
----------------------------------------------
--
--Hereby
--
--* +<T> T getValue(String, Class<T>)+ provides type safe accessors for all basic wrapper types of the JDK. If a
-- key cannot be found a +NoSuchElementException+ is thrown.
--* +getOptionalValue+ allows to use +Optional+ for handling default values as needed.
--* +getPropertyNames()+ provides access to all keys, whereas entries from non-scannable config sources may not
-- be included.
--* +getConfigSources()+ allows access to the underlying config sources.
--
--
--Instances of +Config+ can be accessed from the +ConfigProvider+ singleton:
--
--[source,java]
--.Accessing Configuration
----------------------------------------------
--Config config = ConfigProvider.getConfig();
----------------------------------------------
--
--Hereby the singleton is backed up by an instance of +ConfigProviderResolver+ registered using Java's +ServiceLoader+
--mechanism.
--
--
--[[Converter]]
--==== Property Type Conversion
--
--As illustrated in the previous section, +Config+ also allows access of typed values. Internally
--all properties are strictly modelled as Strings. As a consequence non String values must be derived by converting the
--String values into the required target type. This is achieved with the help of +Converter+:
--
--[source,java]
----------------------------------------------
--@FunctionalInterface
--public interface Converter<T>{
-- T convert(String value);
--}
----------------------------------------------
--
--Tamaya additionally offers a +ConversionContext+, which contains additional meta-information about the key
--accessed, including the key'a name and additional metadata. This can be very useful, e.g. when the implementation
--of a +Converter+ requires additional metadata for determining the correct conversion to be applied:
--
--[source,java]
----------------------------------------------
--ConversionContext context = ConversionContext.getContext();
----------------------------------------------
--
--+Converter+ instances can be implemented and registered by default using the Java +ServiceLoader+. The ordering
--of the registered converters, by default, is based on the annotated +@Priority+ values (priority +0+ is assumed if the
--annotation is missing). The first non-null result of a converter is returned as the final configuration value.
--
--Access to converters is provided by Tamaya's +ConfigContext+. The Config JSR does not provide a methgod to
--access the currently registered converters.
--
--NOTE: Tamaya, different to the JSR allows to register multiple converters for a type. Tamaya will walk through
-- all converters for a type, using the first value evaluated to non-null as the result of a conversion
-- process.
--
--
--[[ExtensionPoints]]
--=== Extension Points
--
--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 (e.g. Java Time API and JSR 354) as well.
--
--Tamaya
--
--* +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.
--* +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.
--
--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:
--
--[source,java]
--.Applying a +ConfigQuery+ using a method reference
----------------------------------------------
--SecurityContext context = ConfigQuery.from(ConfigProvider.getConfig()).query(ConfigSecurity::targetSecurityContext);
----------------------------------------------
--
--NOTE: +ConfigSecurity+ is an arbitrary class only for demonstration purposes.
--
--
--Operator calls basically look similar:
--
--[source,java]
--.Applying a +ConfigOperator+ using a lambda expression:
----------------------------------------------
--Configuration secured = ConfigOperator.from(config)
-- .with((config) ->
-- config.get("foo")!=null?;
-- FooFilter.apply(config):
-- config);
----------------------------------------------
--
--
--
--[[SPI]]
--== SPI
--
--[[PropertyValue]]
--=== PropertyValue, PropertyValueBuilder
--
--On the API properties are represented as Strings only, whereas in the SPI value are represented as +ProeprtyValue+,
--which contain
--
--* the property's _key_ (String)
--* the property's _value_ (String)
--* the property's _source_ (String, typically equals to the property source's name)
--* any additional meta-data represented as _Map<String,String>_
--
--This helps to kepp all value relevant data together in one place and also allows to choose any kind of
--representation for meta-data entries. The +PropertyValue+ itself is a final and _serializable_ data container,
--which also has a powerful builder API (e.g. for using within filters):
--
--[source,java]
------------------------------------------------------------------
--public final class PropertyValue implements Serializable{
-- [...]
--
-- public static PropertyValue of(String key, String value, String source);
--
-- public String getKey();
-- public String getSource();
-- public String getValue();
-- public Map<String, String> getMetaEntries();
-- public String getMetaEntry(String key);
-- public PropertyValueBuilder toBuilder();
--
-- public static PropertyValueBuilder builder(String key, String source);
-- public static PropertyValueBuilder builder(String key, String value, String source);
--
-- /**
-- * Maps a map of {@code Map<String,String>} to a {@code Map<String,PropertyValue>}.
-- * @param config the String based map, not null.
-- * @param source the source name, not null.
-- * @return the corresponding value based map.
-- */
-- public static Map<String,PropertyValue> map(Map<String, String> config, String source);
--
-- /**
-- * Maps a map of {@code Map<String,String>} to a {@code Map<String,PropertyValue>}.
-- * @param config the String based map, not null.
-- * @param source the source name, not null.
-- * @param metaData additional metadata, not null.
-- * @return the corresponding value based map.
-- */
-- public static Map<String,PropertyValue> map(Map<String, String> config, String source,
-- Map<String,String> metaData);
--}
------------------------------------------------------------------
--
--When writing your own datasource you can easily create your own +PropertyValues+:
--
--[source,java]
------------------------------------------------------------------
--PropertyValue val = PropertyValue.of("key","value","source");
------------------------------------------------------------------
--
--If you want to add additional metadata in most cases you would use the builder API:
--
--[source,java]
------------------------------------------------------------------
--PropertyValue val = PropertyValue.builder("key","value","source")
-- .addMetaEntry("figured", "true")
-- .build();
------------------------------------------------------------------
--
--+PropertyValues+ are type safe value objects. To change a value you have to create a
--new instance using a builder:
--
--[source,java]
------------------------------------------------------------------
--PropertyValue val = PropertyValue.builder("key","value","source")
-- .addMetaEntry("figured", "true")
-- .build();
--PropertyValue newVal = val.toBuilder().setValue("anotehrValue")
-- .addMetaEntry("remote", "true")
-- .removeMetaEntry("figured")
-- .build();
------------------------------------------------------------------
--
--[[ConfigSource]]
--=== Interface ConfigSource
--
--We have seen that constraining configuration aspects to simple literal key/value pairs provides us with an easy to
--understand, generic, flexible, yet extensible 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.
--
--Though there are advantages in using these types as a model, there are some 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.
--
--To render an implementation of a custom +PropertySource+ as convenient as possible only the following methods were
--identified to be necessary:
--
--[source,java]
----------------------------------------------
--public interface ConfigSource{
-- int getOrdinal();
-- String getName();
-- String getValue(String key);
-- Map<String,String> getProperties();
--}
----------------------------------------------
--
--Hereby
--
--* +getValue+ looks similar to the methods on +Map+. It may return +null+ in case no such entry is available.
--* +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.
--* +int getOrdinal()+ defines the ordinal of the +PropertySource+. Property sources are managed in an ordered chain, where
-- property sources with higher ordinals override ones with lower ordinals. If the ordinal of two property sources is
-- the same, the natural ordering of the fully qualified class names of the property source implementations is 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.
-- Implementations of this API may provide additional functionality to adapt the default ordinal of auto-discovered
-- property sources.
--* Finally +getName()+ returns a (unique) name that identifies the +PropertySource+ within its containing +ConfigurationContext+.
--
--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.
--
--+ConfigSources+ to be picked up (auto-discovered) automatically and be added to the _default_ +Configuration, must be
--registered using the Java +ServiceLoader+ (or the mechanism provided by the current active +ServiceContext+, see later
--in this document for further details).
--
--
--[[ConfigSourceProvider]]
--=== Interface ConfigSourceProvider
--
--Instances of this type can be used to register multiple instances of +ConfigSource+.
--
--[source,java]
----------------------------------------------
--@FunctionalInterface
--public interface ConfigSourceProvider{
-- Iterable<ConfigSource> getConfigSources();
--}
----------------------------------------------
--
--This allows to evaluate the config sources to be read/that are available dynamically. All config sources
--are read out and added to the current chain of +ConfigSource+ instances within the current +Config+,
--refer also to [[Config]].
--
--+ConfigSourceProviders+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the
--current active +ServiceContext+.
--
--
--[[Filter]]
--=== Interface Filter
--
--Also +Filters+ can be added to a +Config+. They are evaluated each time before a configuration value
--is passed to the user. Filters can be used for multiple purposes, such as
--
--* resolving placeholders
--* masking sensitive entries, such as passwords
--* constraining visibility based on the current active user
--* ...
--
--NOTE: Filters are not defined by the configuration JSR, but an useful extension of the Tamaya toolkit.
--
--For +Filters+ to be picked up automatically and added to the _default_ +Config+ must be, by default,
--registered using the Java +ServiceLoader+ (or the mechanism provided by the current active +ServiceContext+).
--Similar to config sources they are managed in an ordered filter chain, based on the
--class level +@Priority+ annotations (assuming +0+ if none is present).
--
--A +Filter+ is defined as follows:
--
--[source,java]
----------------------------------------------
--@FunctionalInterface
--public interface Filter{
-- String filterProperty(String key, String value);
--}
----------------------------------------------
--
--Hereby:
--
--* returning +null+ will remove the key from the final result.
--* 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.
--
--Additionally Tamaya allows to configure an additional +FilterContext+, which can be accessed from the filter
--implementation. +FilterContext+ provides additional metdata, including the property accessed, which is useful
--in many use cases:
--
--[source,java]
----------------------------------------------
--FilterContext context = FilterContext.getContext();
----------------------------------------------
--
--
--[[ConfigValueCombinationPolicy]]
--==== Interface ConfigValueCombinationPolicy
--
--This interface is purely optional and can be used to adapt the way how property key/value pairs are combined to
--build up the final configuration _raw_ value to be passed over to the +Filters+. The default implementation
--is just overriding all values read before with the new value read. Nevertheless for collections and other use cases
--more intelligent logic is required.
--
--[source,java]
----------------------------------------------
--@FunctionalInterface
--public interface ConfigValueCombinationPolicy{
--
-- ConfigValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR =
-- new ConfigValueCombinationPolicy(){
-- @Override
-- public String collect(String currentValue, String key,
-- ConfigSource configSource) {
-- String value = configSource.getValue(key);
-- return value!=null?value:currentValue;
-- }
-- };
--
-- String collect(String currentValue, String key,
-- ConfigSource configSource);
--}
----------------------------------------------
--
--Looking at the +collect+ method's signature, returning a value allows also to filter/combine/use meta entries.
--
--
--[[ConfigContext]]
--==== The Config Context
--
--A +Config+ provides some access to it's underlying elements by exposing the +getPropertySources()+
--method. Nevertheless a +Config+ at least also contains +Converters+. In Tamaya the underlying
--implementation also supports filtering as well as multiple converters, organized as a
--converter chain.
--
--All these artifacts can be accessed using Tamaya's +ConfigContext+:
--
--[source,java]
--.Accessing the current +ConfigContext+
----------------------------------------------
--Config config = ...;
--ConfigContext context = ConfigContext.from(config);
----------------------------------------------
--
--The +ConfigContext+ provides access to the internal artifacts that determine the +Config+ and
--also defines the ordering of the property sources, filters and converters contained:
--
--* +ConfigSources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances).
--* +Filters+ registered, which filter values before they are returned to the client
--* +Converter+ instances that provide conversion functionality for converting String values to any other types.
--* the current +ConfigValueCombinationPolicy+ that determines how property values from different config sources are
-- combined to the final property value returned to the client.
--
--NOTE: Implementations of the JSR API that want to interoperate with the Tamaya extensions best
-- implement the +ConfigContextSupplier+ interface by the +Config+ implementation.
--
--
--[[Mutability]]
--==== Changing the current Config
--
--A +Config+ is not mutable once it is created. In many cases mutability is also not needed. Nevertheless
--there are use cases where the current +Config+ must be adapted:
--
--* New configuration files where detected in a folder observed by Tamaya.
--* Remote configuration, e.g. stored in a database or alternate ways has been updated and the current system must
-- be adapted to these changes.
--* The overall configuration context is manually setup by the application logic.
--* Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the
-- tests executed.
--
--In such cases the +Config+ may change, meaning it must be possible:
--
--* to add and load +ConfigSource+ instances
--* to define the +Converter+ used for a type
--
--In Tamaya, additionally it is also possible:
--
--* to remove and reorder +ConfigSource+ instances
--* to add or remove +Converter+ instances
--* to add or remove +Filter+ instances
--* to redefine the current +ConfigValueCombinationPolicy+ instances.
--
--The JSR provides a +ConfigBuilder+, which can be obtained as follows:
--
--[source,java]
--.Accessing a +ConfigBuilder+
----------------------------------------------
--ConfigBuilder emptyConfigBuilder = ConfigProviderResolver.getInstance().getConfigBuilder();
----------------------------------------------
--
--Finally when we are finished a new +Config+ can be created:
--
--[source,java]
--.Creating and applying a new +Config+
----------------------------------------------
--Config config = emptyConfigBuilder.withPropertySources(new MyPropertySource())
-- .withDiscoveredConverters()
-- .build();
----------------------------------------------
--
--Unfortunately the JSR API is rather constraint, so Tamaya provides a more powerful builder
--(extending the JSR +ConfigBuilder+), that allows to add, remove or
--reorder config sources, converters and filters or changing any other aspect of a +Config+:
--
--A +TamayaConfigBuilder+ can be obtained in several ways:
--
--[source,java]
--.Chain manipulation using a fresh +TamayaConfigBuilder+
----------------------------------------------
--TamayaConfigBuilder builder = TamayaConfigBuilder.create();
--builder.withDiscoveredSources();
--ConfigSource configSource = builder.getConfigSource("sourceId");
--
--// changing the priority of a config source. The ordinal value hereby is not considered.
--// Instead the position of the property source within the chain is changed.
--builder.decreasePriority(configSource);
--
--// Alternately a comparator expression can be passed to establish the defined ordering...
--builder.sortFilters(MyFilterComparator::compare);
----------------------------------------------
--
--Alternately a new builder can be created from any +Config+ instance:
--
--[source,java]
--.Chain manipulation using a fresh +TamayaConfigBuilder+
----------------------------------------------
--Config config = ...;
--TamayaConfigBuilder builder = TamayaConfigBuilder.from(config);
--ConfigSource configSource = builder.getConfigSource("sourceId");
--
--// changing the priority of a config source. The ordinal value hereby is not considered.
--// Instead the position of the property source within the chain is changed.
--builder.decreasePriority(configSource);
--
--// Alternately a comparator expression can be passed to establish the defined ordering...
--builder.sortFilters(MyFilterComparator::compare);
----------------------------------------------
--
--Finally if a new +Config+ can be created.
--Optionally the new +Config+ can also be installed as the new _default_ +Config+
--instace as illustrated below:
--
--[source,java]
--.Creating and applying a new +Config+
----------------------------------------------
--Config newConfig = builder.build();
--
--// Apply the new config to replace the current configuration:
--ConfigProviderResolver.getInstance().registerConfig(newConfig, Thread.currentThread().getContextClassLoader());
----------------------------------------------
--
--
--[[ConfigProviderResolver]]
--==== Implementing and Managing Configuration
--
--The most important SPI for Config is the +ConfigProviderResolver+ abstract class, which is backing up the
--+ConfigProvider+ singleton. Implementing this class allows
--
--* to fully determine the implementation class for +Config+
--* to manage the current +Config+ in the scope and granularity required.
--* to provide access to the right +Config+ based on the current runtime context.
--* Performing changes as set with the current +ConfigBuilder+.
--
--[[BuilderCore]]
--== The TamayaConfigtBuilder interface in Detail
--
--=== Overview
--
--The Tamaya builder module provides a generic (one time) builder for creating +Config+ instances,
--e.g. as follows:
--
--[source,java]
-----------------------------------------------------------------
--TamayaConfigBuilder builder = TamayaConfigBuilder.create();
--// do something
--Config config = builder.build();
-----------------------------------------------------------------
--
--Basically the builder allows to create configuration instances completely independent of the current configuration
--setup. This gives you full control how and when +Config+ is created.
--
--
--=== Supported Functionality
--
--The builder allows you to add +ConfigySource+ instances:
--
--[source,java]
------------------------------------------------------------------
--TamayaConfigBuilder builder = ...
--builder.withConfigSources(sourceOne, sourceTwo, sourceThree
--Config config = builder.build();
------------------------------------------------------------------
--
--Hereby the ordering of the config sources is not changed, regardless of the ordinals provided
--by the config 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.
--
--Similarly you can add +Filters+:
--
--[source,java]
------------------------------------------------------------------
--builder.withFilters(new MyConfigFilter());
------------------------------------------------------------------
--
--...or +ConfigSourceProvider+ instances:
--
--[source,java]
------------------------------------------------------------------
--builder.addConfigSourceProvider(new MyPropertySourceProvider());
------------------------------------------------------------------
--
--
--
--[[ServiceContext]]
--==== The ServiceContext
--
--The +ServiceContext+ allows to define how components are loaded in Tamaya. It is the glue layer, which interacts
--with the underlying runtime system such as Java SE, Java EE, OSGI, VertX etc.
--The +ServiceContext+ hereby defines access methods to obtain components, whereas itself it is available from the
--+ServiceContextManager+ singleton:
--
--[source,java]
--.Accessing the +ServiceContext+
----------------------------------------------
--ServiceContext serviceContext = ServiceContextManager.getServiceContext();
--
--public interface ServiceContext{
-- int ordinal();
-- <T> T getService(Class<T> serviceType);
-- <T> List<T> getServices(Class<T> serviceType);
--}
----------------------------------------------
--
--With the +ServiceContext+ a component can be accessed in two different ways:
--
--. 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.
--. access all items given a type. This will return (by default) all instances loadedable from the current
-- runtime context, ordered by priority (the most significant components added first).
--
--
--## Examples
--### Accessing Configuration
--
--_Config_ is obtained from the ConfigProvider singleton:
--
--[source,java]
--.Accessing +Config+
----------------------------------------------
--Config config = ConfigProvider.getConfig();
----------------------------------------------
--
--Many users in a SE context will probably only work with _Config_, since it offers all functionality
--needed for basic configuration with a very lean memory and runtime footprint. It is also possible
--to access optional values:
--
--[source,java]
----------------------------------------------
--Config config = ConfigProvider.getConfig();
--String myKey = config.getValue("myKey", String.class); // never returns null
--Optional<Integer> myLimit = config.getOptionalValue("all.size.limit", Integer.class);
----------------------------------------------
--
--
--### Environment and System Properties
--
--By default environment and system properties are included into the _Config_. So we can access the current
--_PROMPT_ environment variable as follows:
--
--[source,java]
----------------------------------------------
--String prompt = ConfigProvider.getConfig().getValue("PROMPT", String.class);
----------------------------------------------
--
--Similary the system properties are directly applied to the _Config_. So if we pass the following system
--property to our JVM:
--
--[source,java]
----------------------------------------------
--java ... -Duse.my.system.answer=yes
----------------------------------------------
--
--we can access it as follows:
--
--[source,java]
----------------------------------------------
--boolean useMySystem = ConfigProvider.getConfig().getValue("use.my.system.answer", boolean.class);
----------------------------------------------
--
--
--### Adding a Custom Configuration
--
--Adding a classpath based configuration is simply as well: just implement an according _ConfigSource_. With the
--_tamaya-spi-support_ module you just have to perform a few steps:
--
--. Define a ConfigSource as follows:
--
--[source,java]
----------------------------------------------
-- public class MyConfigSource extends PropertiesResourceConfigSource{
--
-- public MyConfigSource(){
-- super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"), DEFAULT_ORDINAL);
-- }
-- }
----------------------------------------------
--
--Then register +MyConfigSource+ using the +ServiceLoader+ by adding the following file:
--
--[source,listing]
----------------------------------------------
--META-INF/servicesjavax.config.spi.ConfigSource
----------------------------------------------
--
--...containing the following line:
--
--[source,listing]
----------------------------------------------
--com.mypackage.MyConfigSource
----------------------------------------------
--
--
--[[APIImpl]]
--== API Implementation
--
--The Config API is implemented by the +tamaya-base+ and +tamaya-core+ module. Refer to the link:core.html[Core documentation] for
--further details.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/core.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/core.adoc
index e7a2c46,e7a2c46..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/core.adoc
+++ /dev/null
@@@ -1,283 -1,283 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--[[Core]]
--== Tamaya Core Implementation
--=== Overview
--
--Tamaya Core provides an implementation of the link:api.html[Configuration API] and adds additional functionality
--and building blocks for supporting SPI implementations.
--
--Tamaya contains the following core artifacts:
--
--* *tamaya-base* provides implementations and base classes for different API artifacts such as +Config,
-- ConfigContext, ConfigBuilder, BaseConfigSource+ and more. It is
-- built as an independent module, which also can be used with other implementations.
--* The *tamaya-core*
-- implementation
-- ** leverages these base classes to build up a full API implementation, adding converter
-- implementations for most common Java types.
-- ** A +java.util.ServiceLoader+ based +ServiceContext+ implementation. This allows component priorization based
-- on the +@Priority+ annotations.
-- ** A +PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances,
-- thus providing type conversion for all important types.
--* A simple default configuration setup using the current classpath and an optional staging variable.
--* It collects all +ConfigSource+ and +ConfigSourceProvider+ instances registered with the +ServiceLoader+ and
-- registers them in the global +ConfigurationContext+
--* It provides a +ConfigBuilder+ implementation (+DefaultConfigBuilder+), including an extended +TamayaConfigBuilder+
-- variant.
--
--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
--
--* placeholder and resolution mechanisms (+org.apache.tamaya.ext:tamaya-resolver+)
--* dynamic resource path lookup, e.g. with ant styled patterns (+org.apache.tamaya.ext:tamaya-resources+)
--* configuration injection and configuration templates (+org.apache.tamaya.ext:tamaya-injcetion-api+)
--* abstraction for reusable formats (+org.apache.tamaya.ext:tamaya-formats+)
--* integration with other existing solutions (e.g. +org.apache.tamaya.ext:tamaya-spring+)
--* configuration and configuration isolation targeting Java EE (+org.apache.tamaya.ext:tamaya-injection-ee+)
--* dynamic configuration and configuration updates (+org.apache.tamaya.ext:tamaya-events+)
--* remote configuration (+org.apache.tamaya.ext:tamaya-etcd, org.apache.tamaya.ext:tamaya-consul,
-- org.apache.tamaya.ext:tamaya-hazelcast+)
--* and more
--
--For details about the extension modules available and their functionality refer to the link:extensions.html[extension user guide].
--
--
--[[CoreConverters]]
--=== Default Converters
--
--The _SPI_ base module provides several +Converter+ implementations, which are automatically registered by the
--_Core_ module. Find below the listing of converters automatically registered with the Core module:
--
--[width="100%",frame="1",options="header",grid="all"]
--|=======
--|_Target Type_ |_Class Name_ |_Supported Formats_
--|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF
--|java.math.BigInteger |BigIntegerConverter |0xFF, 1234
--|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0
--|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123
--|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123
--|java.ui.lang.Class |ClassConverter |<fully qualified class name>
--|java.util.Currency |CurrencyConverter |CHF, 123
--|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
--|_Enums_ |EnumConverter |<Enum item name>
--|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
--|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
--|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String)
--|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String)
--|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)>
--|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
--|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY
--|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
--|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true
--|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true
--|ZoneId |ZoneIdConverter |Europe/Zurich
--|=======
--
--
--=== Registering Converters
--
--Additional +Converters+ can be implemented easily. It is recommended to register them using
--the +java.util.ServiceLoader+, meaning you add a file under +META-INF/service/javax.config.spi.Converter+
--containing the fully qualified class names of the converters to be registered (one line each) to enable
--auto-discovery.
--
--Alternatively you can also use a +TamayaConfigBuilder+ to add additional converters programmatically.
--
--
--[[ComponentLoadingAndPriorization]]
--=== Component Loading and Priorization
--
--Tamaya _Core_ in general loads all components by default using the +java.util.ServiceLoader+ mechanism. This means that
--new components must be registered by adding a file under +META-INF/service/<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 such a functionality with the possibility to add +@Priority+
--annotations to the components registered. By default, and if no annotation is added +0+ is assumed
--as priority. Hereby higher values preceed lower values, meaning
--
--* if a _singleton_ component is accessed from the current +ServiceContext+ the component with the
-- higher value effectively _overrides/replaces_ any component with lower values.
--* if a _collection_ of components is obtained from the +ServiceContext+ the components are _ordered_
-- based on their priorities, where the ones with higher priority are before components with lower
-- priority.
--* if priorities _match_ Tamaya _Core_ additionally sorts them using the _simple class name_.
-- This ensures that ordering is still defined and predictable in all scenarios.
--
--NOTE: 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:
--
--
--[[RegisteringConfigSources]]
--=== Registering ConfigSources
--
--+ConfigSource+ implementations that provide configuration properties are registered as components as described in the
--previous section. Hereby the precedence (ordering) of property sources is not hard-coded. Instead a +Comparator<ConfigSource>+
--can be passed to a +ConfigurationContextBuilder+ to perform automatic ordering of the property sources
--registered. The default implementation hereby uses the following logic:
--
--. It checks for an property entry +config.ordinal+ if present the value is parsed into an +int+ value and used as
-- the ordinal val value.
--. It checks for an explicit method +int getOrdinal()+, if found its value is taken as an ordinal.
--. It checks for a +@Priority+ annotation, if present the priority value is used as an ordinal.
--. If none of the above works, +0+ is assumed as ordinal value.
--. If multiple +ConfigSource+ instances share the same ordinal value, they are ordered based on their fully qualified
-- class names.
--
--Custom implementations of the config source comparator can be applied by calling
--+TamayaConfigBuilder.sortSources(Comparator<ConfigSource>)+. The default comparator can be replaced
--by passing the fully qualified comparator class name as system property:
--
--+-Dconfig-source-comparator=a.b.c.MyComparatorClass+
--
--The ladder allows to adapt the ordering of auto-discovered config sources, even if the value returned by
--+int getOrdinal()+ cannot be changed.
--
--
--[[CoreConfigSources]]
--== Configuration Setup in Core
--
--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:
--
--. Read environment properties and add them prefixed with +env.+
--. Read all files found at +META-INF/javaconfig.properties+
-- and +META-INF/javaconfig.xml+
--
--
--=== Overview of Registered Default Config Sources and Providers
--
--The Tamaya Core implementation provides a couple of default +ConfigSource+ implementations, which are automatically
--registered. They are all in the package +org.apache.tamaya.base.configsource+:
--
--[width="100%",frame="1",options="header",grid="all"]
--|=======
--|_Type_ |_Class Name_ |_Ordinal Used_
--|META-INF/javaconfig.properties |JavaConfigurationProvider |100
--|META-INF/javaconfig.xml |JavaConfigurationProvider |100
--|JNDI Entries |JNDIConfigSource |200
--|Environment Properties |EnvironmentConfigSource |300
--|System Properties |SystemConfigSource |1000
--|=======
--
--NOTE: Similarly to converters the config sources shown here are defined within the "tamaya-base* module
-- and automatically registered with the *tamaya-core* implementation using Tamaya's auto-discovery mechanisms.
--
--NOTE: +JNDIConfigSource+ is provided by the `tamaya-jndi` extension module.
--
--
--=== Abstract Class PropertiesFileConfigSource
--
--The abstract class +PropertiesFileConfigSource+ can be used for implementing a +ConfigSource+ based on a +URL+
--instance that points to a +.properites+ file. It requires a +URL+ to be passed on the constructor:
--
--[source,java]
----------------------------------------------
--PropertiesFileConfigSource(URL url);
----------------------------------------------
--
--
--==== Abstract Class PropertiesConfigSource
--
--The abstract class +PropertiesConfigSource+ can be used for implementing a +ConfigSource+ based on a +Properties+
--instance. It requires a +Properties+ to be passed on the constructor:
--
--[source,java]
----------------------------------------------
--PropertiesConfigSource(Properties properties);
----------------------------------------------
--
--
--==== Abstract Class BaseConfigSource
--
--The abstract class +BaseConfigSource+ can be used for implementing custom +ConfigSource+ classes. It requires only
--one method to implemented:
--
--[source,java]
--.Implementing a ConfigSource using BaseConfigSource
----------------------------------------------
--public class MyConfigSource extends BaseConfigSource{
--
-- public String getName(){
-- // return a unique name for the config source, e.g. based on the underlying resource. This name also
-- // allows to access the property source later
-- }
--
-- public Map<String, String> getProperties(){
-- // Get a map with all properties provided by this config source
-- }
--
--}
----------------------------------------------
--
--By default the ordinal of the config sources will be 1000, unless the key +config.ordinal+
--as defined in +ConfigSource.CONFIG_ORDINAL+ is present in the current +ConfigSource+. Of course
--it is also possible to override the inherited +protected void initializeOrdinal(final int defaultOrdinal)+,
--or directly +int getOrdinal()+.
--
--
--[[CoreConfigSourceProviders]]
--=== Default ConfigSourceProvider in Core
--
--With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also a default +ConfigSourceProvider+
--present that loads all +.properties+ files found at +META-INF/javaconfig.properties+
--and +META-INF/javaconfig.xml+.
--
--
--=== Replacing the property value evaluation policy
--
--Tamaya's core implementation allows to replace the complete logic how a configuration value or the current configuration
--properties are calculated from a given +ConfigContext+ by implementing the +ConfigValueEvaluator+
--interface:
--
--[source,java]
----------------------------------------------
--/**
-- * Component SPI which encapsulates the evaluation of a single or full <b>raw</b>value
-- * for a {@link ConfigurationContext}.
-- */
--public interface ConfigValueEvaluator {
--
-- /**
-- * Evaluates single value using a {@link ConfigContext}.
-- * @param key the config key, not null.
-- * @param context the context, not null.
-- * @return the value, or null.
-- */
-- ConfigValue evaluteRawValue(String key, ConfigContext context);
--
-- /**
-- * Evaluates all property values from a {@link ConfigurationContext}.
-- * @param context the context, not null.
-- * @return the value, or null.
-- */
-- Iterable<ConfigValue> evaluateRawValues(ConfigContext context);
--
--}
----------------------------------------------
--
--The default implementation +DefaultConfigValueEvaluator+ implements the following logic:
--
--. Collect all +ConfigSources+ from the context.
--. Access +String get(String)+ (single key access)/ +Map<String,String> getProperties()+
-- (config map access) from each property source and combine the previous with the next value using
-- the +ConfigValueCombinationPolicy+ in place.
--
--The resulting _raw_ value(s) are then finally handed over to the registered filters and finally
--converted to +String/Map<String,String>+ as required by the user API.
--
--To replace this default behaviour you must register your implementation with the current
--+ServiceContext+.
--
--
--[[Extensions]]
--== Adding Extensions
--
--Tamaya _Core_ only implements the link:api.html[API]. 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.
--
--For detailed information on the extensions available refer to the link:extensions.html[extensions documentation].
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions.adoc
index 26b5832,26b5832..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions.adoc
+++ /dev/null
@@@ -1,65 -1,65 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--== Apache Tamaya: Extension Modules
--
--toc::[]
--
--=== Mature Extensions
--
--Mature extensions have a stable API and SPI, similar to the API and Implementations provided.
--
--[width="100%",frame="1",options="header",grid="all"]
--|=======
--|_Artifact_ |_Description_ |_Links_
--| | N/A: currently no extensions have reached that maturity level. | -
--|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. |link:extensions/mod_filter.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-features+ |Provides a simple feature check for loaded extensions. |link:extensions/mod_features.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-injection-api+ |Provides Tamaya's injection annotations API. |link:extensions/mod_injection.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and configuration template support. |link:extensions/mod_injection.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-injection-cdi+ | Java EE/standalone compliant CDI integration using CDI for injection. | link:extensions/mod_cdi.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-jndi+ |Provides a JNDI based PropertySource. |link:extensions/mod_jndi.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-microprofile+ |Implemenation and Integration with the Microprofile API. | link:extensions/mod_microprofile.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-osgi+ |Integration with OSGI containers. |link:extensions/mod_osgi.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-spring+ |Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation]
--|=======
--
--=== Extensions Sandbox
--
--Extensions in _draft state_ rather experimental or not yet very mature. API changes may occurr at any time
--and the may also have severe issues or even not work at all. So use at your own risk or join and help
--us getting them stable and well tested!
--
--NOTE: All extensions currently require Java 8.
--
--[width="100%",frame="1",options="header",grid="all"]
--|=======
--|_Artifact_ |_Description_ |_Links_
--|+org.apache.tamaya.ext:tamaya-camel_beta+ |Integration with Apache Camel. | link:extensions/mod_camel.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-classloader-support+ |Configuration services considering classloaderas. |link:extensions/mod_classloader_support.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-commons_beta+ |Integration Support for Apache Commons. | -
--|+org.apache.tamaya.ext:tamaya-configured-sysprops_beta+ | Tamaya configuration to be provided as +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-consul_beta+ |Integration with consul clusters. | link:extensions/mod_consul.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-etcd_beta+ |Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-hazelcast_beta+ |Integration with Hazelcast datagrids. | link:extensions/mod_hazelcast.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-jodatime_beta+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-management_alpha+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-metamodel_alpha+ |Provides an XML API for building configuration. |link:extensions/mod_metamodel-staged.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-remote_alpha+ |Remote configuration support using the server API. |link:extensions/mod_remote.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-server_alpha+ |Publishes configuration as a REST service. |link:extensions/mod_server.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-ui_alpha+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-uom_beta+ |Provides additional converters based on the Units of Measurement JSR. |link:extensions/mod_uom.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-usagetracker_beta+ |Allows tracking of configuration usage. |link:extensions/mod_usagetracker.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-validation-alpha+ |Provides an XML API for validating configuration. |link:extensions/mod_validation.html[Documentation]
--|+org.apache.tamaya.ext:tamaya-vertx-alpha+ |Provides Vertx integration. |link:extensions/mod_vertx.html[Documentation]
--|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_camel.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_camel.adoc
index b21df17,b21df17..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_camel.adoc
+++ /dev/null
@@@ -1,132 -1,132 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration with Apache Camel
--
--toc::[]
--
--
--[[Camel]]
--== Integration with Apache Camel (Extension Module)
--
--Tamaya _Camel_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--The Tamaya _Camel_ module provides different artifacts which allows integration of Apachae Tamaya
--configuration with Apache Camel.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To benefit from configuration builder support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-camel</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Functionality Provided
--
--Tamaya Camel comes basically with three artifacts:
--
--* A Camel +ResolverFunction+ implementation adding explicit property resolution
-- (+org.apache.tamaya.camel.TamayaPropertyResolver+).
--* A Camel +PropertiesComponent+ implementation, which allows implicitly preconfigures the resolvers from above and
-- additionally allows using Tamaya configuration as Camel _overrides_
-- (+org.apache.tamaya.camel.TamayaPropertiesComponent+).
--
--
--=== Configuring using Camel Java DSL
--
--Camel integration using Java DSL is basically simple:
--
--[source, java]
-------------------------------------------------
--import org.apache.tamaya.camel.TamayaPropertiesComponent;
--
--camelContext.addComponent("properties", new TamayaPropertiesComponent());
-------------------------------------------------
--
--Given so you can then use +cfg+ or +tamaya+ as prefix for resolving entries with Tamaya as follows:
--
--[source, java]
-------------------------------------------------
--RouteBuilder builder = new RouteBuilder() {
-- public void configure() {
-- from("direct:hello1").transform().simple("{{cfg:message}}");
-- }
--};
--camelContext.addRoutes(builder);
--builder = new RouteBuilder() {
-- public void configure() {
-- from("direct:hello2").transform().simple("{{tamaya:message}}");
-- }
--};
--camelContext.addRoutes(builder);
-------------------------------------------------
--
--
--Optionally you can also configure +TamayaPropertiesComponent+ that all currently known Tamaya properties are used
--as Camel overrides, meaning they are evaluated prior to all other available resolver functions in the Camel
--+PropertiesComponent+:
--
--[source, java]
-------------------------------------------------
--TamayaPropertiesComponent props = new TamayaPropertiesComponent();
--props.setTamayaOverrides(true);
-------------------------------------------------
--
--
--=== Configuring using Camel XML DSL
--
--Camel integration using XML DSL is basically very similar. You just have to add the +properties+ component as bean
--as well. All other configuration parameters (e.g. file URIs are similar supported). In the example code below we
--again use Tamaya as the main configuration solutions only using Camel's default behaviour as a fallback:
--
--[source, xml]
-------------------------------------------------
--<beans xmlns="http://www.springframework.org/schema/beans"
-- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-- xsi:schemaLocation="
-- http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
-- http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
-- ">
--
-- <routeContext id="myCoolRoutes" xmlns="http://camel.apache.org/schema/spring">
-- <route id="r1">
-- <from uri="direct:hello1"/>
-- <transform>
-- <simple>{{message}}</simple>
-- </transform>
-- </route>
-- <route id="r2">
-- <from uri="direct:hello2"/>
-- <transform>
-- <simple>{{cfg:message}}</simple>
-- </transform>
-- </route>
-- <route id="r3">
-- <from uri="direct:hello3"/>
-- <transform>
-- <simple>{{tamaya:message}}</simple>
-- </transform>
-- </route>
-- </routeContext>
--
-- <bean id="properties" class="org.apache.tamaya.camel.TamayaPropertiesComponent">
-- <property name="tamayaOverrides" value="true"/>
-- </bean>
--
--</beans>
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_cdi.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_cdi.adoc
index deb8842,deb8842..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_cdi.adoc
+++ /dev/null
@@@ -1,244 -1,244 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: CDI Support
--
--toc::[]
--
--
--[[CDI]]
--== Tamaya CDI Integration (Extension Modules)
--
--Tamaya _CDI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Apache _CDI_ provides integration with CDI:
--
--* Loading of CDI managed SPI components as configuration extensions such as +ConfigSources, ConfigSourceProviders,
-- Converters, Filters, etc+. This also includes SPI defined by any Tamaya submodules.
-- This is useful when Tamaya is used as an application module managed by the CDI implementation.
--* Implement and enable Tamaya's configuration injection services (either using CDI injection or
-- Tamaya's standalone injection module.
--
--Hereby there are two implementations provided:
--
--* +tamaya-injection-cdi+ implements injection by using CDI's injection mechanism to inject configuration values into the
-- beans managed by the CDI systems.
--* +tamaya-injection-standalone+ implements injection by integrating the +tamaya-injection+ SE based injection module (also used
-- for Spring and OSGI injection) with CDI. Injection hereby is performed by the Tamaya SE module, whereas
-- beans and injection control overall are still managed by CDI.
--* One difference, of course, is that +tamaya-injection-standalone+ also provides an SE compatible API (+ConfigurationInjection,
-- ConfigurationInjector+), which is not available, when using the purely CDI based variant.
--
--Most annotations used are defined as part of the Config JSR API, whereas Tamaya adds additional features not available
--in the JSR as separate modules. This allows you to code against the injection API without dependency on the concrete
--injection implementation. As a consequence your components will be compatible regardless if deployed in a pure SE or as
--Java EE (CDI) or Spring environment:
--
-------------------------------------------------
--<dependency>
-- <groupId>javax.config</groupId>
-- <artifactId>config-api</artifactId>
-- <version>{config_api_version}</version>
--</dependency>
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-injection-api</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Compatibility
--
--All modules are based on Java 8, so they will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To benefit from Tamaya CDI integration you only must one of the following dependencies to your module. Ensure that
--you never have installed both CDI extensions at the same time because this may be lead to unforseen side-effects.
--
--.CDI Java EE Application Configuration
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-cdi</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--.To use Tamaya's _standalone injection support_, you additionally should add the
--following dependency. If this dependency is missing injection is purely based on
--CDI injection features.
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-injection-standalone</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--Both components will auto-register its components and override the default +ServicceContext+ in use. Additionally they
--register CDI extensions that implement Configuration injection as described before.
--
--For working with a pure non Java EE environment have a look at the link:mod_injection-standalone.html[tamaya-injection-standalone module].
--
--Additionally you have to register Tamaya's CDI extension modules into your `beans-xml`:
--
--Contents of `META-INF/services/javax.enterprise.inject.spi.Extension`:
--[source, properties]
-------------------------------------------------
--# Register Tamaya to perform injection
--# org.apache.tamaya.cdi.TamayaCDIInjectionExtension
--# org.apache.tamaya.cdi.TamayaSEInjectionExtension
--org.apache.tamaya.cdi.TamayaCDIAccessor
-------------------------------------------------
--
--If you want to use CDI standard injection (using +@Inject @Config+), activate
--+org.apache.tamaya.cdi.TamayaCDIInjectionExtension+ as a CDI extension.
--
--If you want to use +SE based injection+ (using +@Config+ *without* +@Inject+),
--activate +org.apache.tamaya.cdi.TamayaSEInjectionExtension+ instead of.
--
--Though not recommended, it is possible to activate both extension at the same time.
--
--
--=== Annotating your Classes
--
--Basically annotating your classes is stright forward. Depending
--on the module deployed, your annotations are handled by a CDI producer (+tamaya-cdi-ee+) or the
--Tamaya SE injection mechanism (+tamaya-cdi-se+). All types injected by this module are injected
--using _dependent scope_.
--
--
--[source, java]
----------------------------------------------------------
--@RequestScoped
--public class ConfiguredClass{
--
-- @Config
-- private String testProperty;
--
-- @Config(key="a.b.c.key1",
-- defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
-- String value1;
--
-- @Config(key="foo")
-- private String value2;
--
-- @Config(defaultValue="N/A")
-- private String runtimeVersion;
--
-- @Config(defdaultValue="${sys:java.version}")
-- private String javaVersion2;
--
-- @Config(defaultValue="5")
-- private Integer int1;
--
-- ...
--
--}
----------------------------------------------------------
--
--
--
--=== Registering CDI managed components into the Application's ConfigurationContext
--
--As mentioned both modules allow to provide Tamaya SPI extensions modules as ordinary CDI managed beans. By default
--extensions should be registered using +@Singleton+ or +@ApplicationScoped+ scope annotations. So you can define/deploy
--additional application specific +PropertySources+ and other artifacts simply by defining a CDI managed bean implementing
--the required SPI interface:
--
--[source, java]
----------------------------------------------------------
--@Singleton
--public class TestConfigSource implements ConfigSource{
--
-- final Map<String,String> config = new HashMap<>();
--
-- public TestConfigSource(){
-- config.put("a.b.c.key1", "keys current a.b.c.key1");
-- config.put("a.b.c.key2", "keys current a.b.c.key2");
-- config.put("{"+getName()+"}source", getClass().getName());
-- }
--
-- @Override
-- public int getOrdinal() {
-- return 10;
-- }
--
-- @Override
-- public String getName() {
-- return getClass().getName();
-- }
--
-- @Override
-- public String get(String key) {
-- return config.get(key);
-- }
--
-- @Override
-- public Map<String, String> getProperties() {
-- return config;
-- }
--
--}
----------------------------------------------------------
--
--To enable this (optional) feature you must replace Tamaya's +ServiceContext+ with the
--CDI aware implementation:
--
--Contents of `META-INF/services/org.apache.tamaya.spi.ServiceContext`:
--[source, properties]
-------------------------------------------------
--# Registering a CDI aware service context
--org.apache.tamaya.cdi.CDIAwareServiceContext
-------------------------------------------------
--
--
--=== Advanced Use Cases
--
--Beside basic configuration Tamaya also covers additional requirements:
--
--* _Reading multiple keys, where the first successful one is determining the value of the configuration, is
-- simply possible, by defining additional keys with +@ConfigFallbackKeys+ annotation.
-- E.g. for trying first +a.b+ and then +new.b+ you would configure it as follows:
--
--[source,java]
----------------------------------------------------------------------------------------
--@Config(key="a.b")
--@ConfigFallbackKeys({"new.b"})
--private String value;
----------------------------------------------------------------------------------------
--
--* When you must apply a some special conversion, or you use a type that is not registered
-- for conversion, you can configure a custom converter to be applied as follows:
--
--[source,java]
----------------------------------------------------------------------------------------
--@Config(key="a.b")
--@WithConverter(MyConverter.class)
--private MySpecialFooType value;
----------------------------------------------------------------------------------------
--
--* Often multiple keys in a class belong to the same root section. So instead of copying this to
-- every entry you can define the most common root sections in the type's header:
--
--[source,java]
----------------------------------------------------------------------------------------
--@ConfigDefaultSections({"aaaa", "new"});
--public class MyType{
--
--@Config(key="b"}
--@ConfigFallbackKeys({"[legacy.bKey]"}) // lookups: "aaaa.b", "new.b", legacy.bKey
--private String value;
----------------------------------------------------------------------------------------
--
--In the example above +legacy.bKey+ defines an absolute key, which is not combined with any defined
--default section parts.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_classloader_support.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_classloader_support.adoc
index 501bcc8,501bcc8..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_classloader_support.adoc
+++ /dev/null
@@@ -1,79 -1,79 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Classloader Isolation Support
--
--toc::[]
--
--[[Classloader]]
--== Tamaya Classloader Aware ServiceContext (Extension Module)
--
--Tamaya _Classloader_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--The Tamaya _Classloader_ support provides an alternative implementation of +java.util.ServiceLoader+, which is aware
--of classloaders, hereby preventing multiple loading of components within a classloader hierarchy.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To benefit from configuration server support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-classloader-support</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--The component will auto.register its components and override the default +ServiceContext+ in use by default
--with an instance of type +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+ with a precendence value
--(component priority) of +10+.
--
--
--=== How it works
--
--Basically the component manages a +Map+ of all classloaders encountered. When services are accessed, the component
--will evaluate the services as follows:
--
--* the component walks up the class loader hierarchy.
--* in a next step the hierarchy is traversed down from the parent to the current classloader. Hereby it is checked
-- if the service list for the required type has been loaded already. If not the service configuration files are
-- evaluated.
--* This configuration file evaluation will ignore all resources already loaded by any of the already traversed parent
-- classloaders.
--* For each configuration file newly visible to the classloader currently traversed, the corresponding services are
-- loaded unleyy, the same service class already has been loaded by one its parent classloaders or another file
-- loaded with this classloader.
--* Finally all services found are returned as the full collection of services valid for the given context (classloader).
--
--This ensures no service is loaded multiple times, even when it is referenced multiple times in several service
--configurations. Additionally every service is loaded on the classloader where it is also declared the first time.
--
--
--=== Control Logging
--
--The service component by default only logs errors. But it is possible to change this by reconfiguring the logging
--levels on the following logging names/path: +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+
--
--* _INFO_ logs additional info on the services accessed.
--* _FINEST_ logs additional info on the services scanned and selected.
--
--
--=== Classloader Aware Configuration
--
--The mechanism above is used to provide a classloader aware implementation of +ConfigurationContext+
--(+org.apache.tamaya.clsupport.internal.CLAwareConfigurationContext+). Similarly to the service variants
--this class provides a context implementation that manages the core configuration aspects considering classloading
--hierarchies:
--
--* +PropertySource+, +PropertySourceProviders+
--* +PropertyFilters+, +PropertyCombinationPolicy+
[7/8] incubator-tamaya-site git commit: TAMAYA-274 Some minor
additions. TAMAYA-353 Some minor additions.
Posted by an...@apache.org.
TAMAYA-274 Some minor additions.
TAMAYA-353 Some minor additions.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/7fc31c0a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/7fc31c0a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/7fc31c0a
Branch: refs/heads/master
Commit: 7fc31c0a7af3b6af39b39a7fe997a961ed898d5e
Parents: 1c03371
Author: Anatole Tresch <at...@gmail.com>
Authored: Mon Nov 5 00:16:15 2018 +0100
Committer: Anatole Tresch <at...@gmail.com>
Committed: Mon Nov 5 00:16:15 2018 +0100
----------------------------------------------------------------------
content/documentation/api.adoc | 366 ++++++++++---------
content/documentation/core.adoc | 66 ++--
content/documentation/extensions.adoc | 4 -
.../extensions/mod_classloader_support.adoc | 4 +
.../extensions/mod_collections.adoc | 177 ++++++---
.../documentation/extensions/mod_events.adoc | 29 +-
.../documentation/extensions/mod_filter.adoc | 14 +-
.../documentation/extensions/mod_formats.adoc | 98 +++--
.../documentation/extensions/mod_functions.adoc | 22 +-
.../documentation/extensions/mod_injection.adoc | 66 +---
content/documentation/extensions/mod_jndi.adoc | 2 +-
.../documentation/extensions/mod_jodatime.adoc | 2 +-
content/documentation/extensions/mod_json.adoc | 6 +-
.../documentation/extensions/mod_metamodel.adoc | 2 +-
.../extensions/mod_microprofile.adoc | 2 +-
.../extensions/mod_mutable_config.adoc | 42 +--
.../documentation/extensions/mod_optional.adoc | 2 +-
.../documentation/extensions/mod_resolver.adoc | 21 +-
.../documentation/extensions/mod_resources.adoc | 17 +-
.../documentation/extensions/mod_server.adoc | 36 +-
.../extensions/mod_usagetracker.adoc | 25 +-
.../extensions/mod_validation.adoc | 2 +-
content/documentation/extensions/mod_vertx.adoc | 6 +-
content/documentation/extensions/mod_yaml.adoc | 4 +-
content/documentation/quickstart.adoc | 38 +-
content/documentation/spisupport.adoc | 29 +-
26 files changed, 572 insertions(+), 510 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/api.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/api.adoc b/content/documentation/api.adoc
index 9e133fe..56d7b19 100644
--- a/content/documentation/api.adoc
+++ b/content/documentation/api.adoc
@@ -12,28 +12,32 @@ link:../highleveldesign.html[High Level Design Documentation]
== The Tamaya API
The API provides the artifacts as described in the link:../highleveldesign.html[High Level Design Documentation], which are:
-* The package +org.apache.tamaya+ defines a simple but complete SE *API* for accessing key/value based _Configuration_:
+* The package +org.apache.tamaya+ defines a simple but complete SE *API* for accessing _Configuration_:
** +Configuration+ hereby models _configuration_, the main interface of Tamaya. +Configuration+ provides
*** access to literal key/value pairs.
*** functional extension points (+with, query+) using a unary +ConfigOperator+ or
a function +ConfigurationQuery<T>+.
- ** +ConfigurationProvider+ provides with +getConfiguration()+ the static entry point for accessing configuration.
+ ** +Configuration+ also provides with +current()+ and +current(ClassLoader)+ static access point for
+ obtaining the current configuration.
** +ConfigException+ defines a runtime exception for usage by the configuration system.
** +TypeLiteral+ provides a possibility to type safely define the target type to be returned in case non-String types
- are accessed.
- ** +PropertyConverter+, which defines conversion of configuration values (String) into any required target type.
+ are accessed. It is especially useful when accessing collections from Tamaya.
+ ** +PropertyConverter+, which defines conversion of configuration values (one or multiple Strings) into any
+ required target type.
* The package +org.apache.tamaya.spi+ provides interfaces used for extending and/or
adapting Tamaya's core functionality, as well as artifacts for creating
+Configuration+ instances programmatically:
** _PropertySource:_ is the the interface to be implemented for adding configuration entries. A +PropertySource+ hereby
*** is minimalistic and can be implemented in any way. E.g. there is no distiction that
- the configuration data provided is managed locally, remotedely. There is even no
+ the configuration data provided is managed locally, remotely. There is even no
requirement that the configuration data is always fully available. Summarizing a
+PropertySource+
- *** provides property access for single key/value pairs in _raw_ format (meaning no postprocessing
- is applied yet). A single property hereby is modelled as +PropertyValue+, which also includes
- its source and additional arbitrary metadata entries.
+ *** provides property access for property values. A single property value hereby is modelled as +PropertyValue+,
+ which by default contains a single literal value. Nevertheles Tamaya also supports more complex scenarios
+ by allowing property values to have children either as array/list type or as named fields. These children
+ themselves are recursively also modelled by property values. This makes it possible to map also complex
+ structures such as JSON, XML or YAML data. Finally a property value also may contain additional metadata entries.
*** can _optionally_ provide access to a +Map<String,PropertyValue>+, providing all its properties at once.
*** defines the default ordinal to be used for establishing the order of significance among all
auto-discovered property sources.
@@ -42,36 +46,32 @@ The API provides the artifacts as described in the link:../highleveldesign.html[
** +ConfigurationProviderSpi+ defines the interface to be implemented by the delegating bean that is implementing the
+ConfigurationProvider+ singleton.
** +PropertyFilter+ allows filtering of property values prior getting returned to the caller. Filters by default are
- registered as global filters, filtering _raw_ values. The final +String+ value of a configuration entry is the
- final value after all registered filters have been applied.
- ** A +PropertyValueCombinationPolicy+ optionally can be registered to change the logic how key/value
- pairs from subsequent property sources in the property source chain are combined to calculate the final
- _raw_ value passed over to the filters registered.
- ** A +ConfigurationContext+ is the container of all inner components (+PropertySource, PropertyFilter,
- PropertyValueCombinationPolicy, PropertyConverter+) required to implement a +Configuration+. Also the ordering
+ registered as global filters. The final value of a configuration entry is the final value after all registered
+ filters have been applied.
+ ** A +ConfigurationContext+ is the container of all components that make up a configuration (+PropertySource,
+ PropertyFilter, PropertyConverter, MetadataProvider+) required to implement a +Configuration+. Also the ordering
of the property sources, filters and converters is defined by the context.
- A +ConfigurationContext+ is automatically created on startup collecting and adding all registered artifacts.
- Based on this +ConfigurationContext+ the _default_ +Configuration+ is created, which can be accessed from
- +ConfigurationProvider.getConfiguration+.
+ By default a +ConfigurationContext+ is automatically created on first use for each classloader collecting and
+ adding all registered artifacts. Based on a +ConfigurationContext+ a +Configuration+ can be created.
Summarizing a +ConfigurationContext+ contains the ordered property sources, property filters, converters and combination
policy used. Once a +ConfigurationContext+ is instanciated a corresponding +Configuration+ instance can be
- created easily by calling +ConfigurationProvider.createConfiguration(context)+.
- ** Finally Tamaya also supports _programmatically_ creating +Configuration+ instances and using them in your code
- as needed. This can be achieved most easily by building a custom +ConfigurationContext+ using a
- +ConfigurationContextBuilder+. This builder can be obtained calling +ConfigurationProvider.getConfigurationContextBuilder();+.
+ created easily using +ConfigurationBuilder+.
+ ** Whereas the Tamaya's API provides access to automatic configuration resources, it also allows to create
+ _programmatically_ +Configuration+ instances. This can be achieved using a
+ +ConfigurationContextBuilder+. This builder can be obtained calling +Configuration.createConfigurationBuilder();+.
** Finally +ServiceContext+ and +ServiceContextManager+ provide an abstraction to the underlying runtime environment,
allowing different component loading and lifecycle strategies to be used. This is very useful since component (service)
loading in Java SE, Java EE, OSGI and other runtime environments may be differ significantly. In most cases even
- extension programmers will not have to deal with these two artifacts.
+ extension programmers will not have to deal with these internals.
[[APIKeyValues]]
-=== Key/Value Pairs
+=== Key/Value Pairs and More
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.
+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.
[source,properties]
.A simple properties file
@@ -95,11 +95,38 @@ val = props.getProperty("a.b.c.1");
...
--------------------------------------------
+But we also have more complex configuration mechanism today. For example YAML is widely used format, which also
+supports lists and maps. Basically these can be mapped also as key/value pairs. Unfortunately this is not very
+useful in some cases:
+
+* a configuration client want to access a list of server configurations
+* a configuration client wants to map structures with named fields.
+* both of the above.
+
+As an example think of a server, which wants to extract a list of all members in the current cluster. Hereby:
+
+* A member is modelled by a +MembeConfigr+ class, with the fields +serverId, serverName, serverURL+.
+* The current members should be accessed as list, as follows:
+
+[source,java]
+----
+List<MemberConfig> members = configuration.get("cluster.members", new TypeLiteral<List<MemberConfig>>();
+----
+
+This coud be modelled as property as well, but it is more convenient to let Tamaya have a more flexible model
+to represent a configuration internally. This is why a +PropertyValue+ can have one of three flavors:
+
+. it is a simple literal value.
+. it is an object containing none to many child property values as named fields.
+. it is an array containing none to many child properties as unnamed array instances.
+
+Summarizing Tamaya is capable of fully represent the structures described by widely used configuration file formats.
+
==== Why Using Strings Only
There are good reason to keep of non String-values as core storage representation of configuration. Mostly
-there are several huge advantages:
+there are several advantages:
* Strings are simple to understand
* Strings are human readable and therefore easy to prove for correctness
@@ -146,24 +173,36 @@ public interface Configuration{
<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);
+ <T> Optional<T> getOptional(String key, TypeLiteral<T> type);
+ <T> Optional<T> getOptional(String key, Class<T> type);
Map<String,String> getProperties();
// extension points
- Configuration with(ConfigOperator operator);
- <T> T query(ConfigQuery<T> query);
+ Configuration map(UnaryOperator<Configuration> operator);
+ <T> T adapt(Function<Configuration,T> adapter);
ConfigurationContext getContext();
+ ConfigurationBuilder toBuilder();
+ static Configuration current();
+ static Configuration current(ClassLoader classsLoader);
+ static void setCurrent(Configuration config);
+ static void setCurrent(Configuration config, ClassLoader classLoader);
+ static ConfigurationBuilder createConfigurationBuilder();
+
+ // the deault EMPTY configuration
+ static Configuration EMPTY{}
}
--------------------------------------------
Hereby
* +<T> T get(String, Class<T>)+ provides type safe accessors for all basic wrapper types of the JDK.
-* +with, query+ provide the extension points for adding additional functionality.
+* +map, adapt+ provide the extension points for adding additional functionality.
* +getProperties()+ provides access to all key/values, whereas entries from non scannable property sources may not
be included.
* +getOrDefault+ allows to pass default values as needed, returned if the requested value evaluated to +null+.
* +getConfigurationContext()+ allows access to the underlying components of a +Configuration+ instance.
+* the +static+ methods allow access for obtaining or changing +Configuration+.
The class +TypeLiteral+ is basically similar to the same class provided with CDI:
@@ -193,7 +232,8 @@ public class TypeLiteral<T> implements Serializable {
--------------------------------------------
-Instances of +Configuration+ can be accessed from the +ConfigurationProvider+ singleton:
+Instances of +Configuration+ can be accessed using the +Configuration.current()+ or +Configuration.current(ClassLoader)+
+singleton:
[source,java]
.Accessing Configuration
@@ -237,10 +277,10 @@ We are well aware of the fact that this library will not be able to cover all ki
we have added _functional_ extension mechanisms to +Configuration+ that were used in other areas of the
Java eco-system (e.g. Java Time API and JSR 354) as well:
-* +with(ConfigOperator operator)+ allows to pass arbitrary unary functions that take and return instances of
+* +map(UnaryOperator<Configuration> 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.
-* +query(ConfigQuery query)+ allows to apply a function returning any kind of result based on a
+* +adapt(Function<Configuration,T)+ 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.
@@ -249,9 +289,9 @@ Both interfaces hereby are functional interfaces. Because of backward compatibil
use Lambdas and method references in Java 8:
[source,java]
-.Applying a +ConfigurationQuery+ using a method reference
+.Applying an Adapter using a method reference
--------------------------------------------
-ConfigSecurity securityContext = ConfigurationProvider.getConfiguration().query(ConfigSecurity::targetSecurityContext);
+ConfigSecurity securityContext = Configuration.current().adapt(ConfigSecurity::targetSecurityContext);
--------------------------------------------
NOTE: +ConfigSecurity+ is an arbitrary class only for demonstration purposes.
@@ -262,7 +302,7 @@ Operator calls basically look similar:
[source,java]
.Applying a +ConfigurationOperator+ using a lambda expression:
--------------------------------------------
-Configuration secured = ConfigurationProvider.getConfiguration()
+Configuration secured = Configuration.current()
.with((config) ->
config.get("foo")!=null?;
FooFilter.apply(config):
@@ -280,7 +320,7 @@ The class +ConfigException+ models the base *runtime* exception used by the conf
== SPI
[[PropertyValue]]
-=== PropertyValue, PropertyValueBuilder
+=== PropertyValue
On the API properties are represented as Strings only, whereas in the SPI value are represented as +ProeprtyValue+,
which contain
@@ -289,6 +329,7 @@ which contain
* the property's _value_ (String)
* the property's _source_ (String, typically equals to the property source's name)
* any additional meta-data represented as _Map<String,String>_
+* named or unnamed child objects, arrays or text filters.s
This helps to kepp all value relevant data together in one place and also allows to choose any kind of
representation for meta-data entries. The +PropertyValue+ itself is a final and _serializable_ data container,
@@ -299,36 +340,33 @@ which also has a powerful builder API (e.g. for using within filters):
public final class PropertyValue implements Serializable{
[...]
- public static PropertyValue of(String key, String value, String source);
+ public static ObjectValue createObject(){
+ public static ListValue createList(){
+ public static PropertyValue createValue(String key, String value){
+ public static ListValue createList(String key){
+ public static ObjectValue createObject(String key)
+
+ public final boolean isImmutable();
+ public PropertyValue immutable();
+ public PropertyValue mutable();
+ public final ValueType getValueType();
public String getKey();
+ public String getQualifiedKey();
public String getSource();
public String getValue();
+ public PropertyValue setValue(String value);
public Map<String, String> getMetaEntries();
public String getMetaEntry(String key);
public PropertyValueBuilder toBuilder();
- public static PropertyValueBuilder builder(String key, String source);
- public static PropertyValueBuilder builder(String key, String value, String source);
-
- /**
- * Maps a map of {@code Map<String,String>} to a {@code Map<String,PropertyValue>}.
- * @param config the String based map, not null.
- * @param source the source name, not null.
- * @return the corresponding value based map.
- */
+ public final PropertyValue getParent();
+ public final int getVersion();
+ public final boolean isRoot();
+ public final boolean isLeaf();
public static Map<String,PropertyValue> map(Map<String, String> config, String source);
-
- /**
- * Maps a map of {@code Map<String,String>} to a {@code Map<String,PropertyValue>}.
- * @param config the String based map, not null.
- * @param source the source name, not null.
- * @param metaData additional metadata, not null.
- * @return the corresponding value based map.
- */
public static Map<String,PropertyValue> map(Map<String, String> config, String source,
Map<String,String> metaData);
-}
----------------------------------------------------------------
When writing your own datasource you can easily create your own +PropertyValues+:
@@ -455,7 +493,7 @@ A +PropertyFilter+ is defined as follows:
[source,java]
--------------------------------------------
-// Functional Interface
+@FunctionalInterface
public interface PropertyFilter{
PropertyValue filterProperty(PropertyValue value, FilterContext context);
}
@@ -472,113 +510,71 @@ Hereby:
This method is called each time a single entry is accessed, and for each property in a full properties result.
-[[PropertyValueCombinationPolicy]]
-==== Interface PropertyValueCombinationPolicy
-
-This interface is purely optional and can be used to adapt the way how property key/value pairs are combined to
-build up the final configuration _raw_ value 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
-more intelligent logic is required.
-
-[source,java]
---------------------------------------------
-// FunctionalInterface
-public interface PropertyValueCombinationPolicy{
-
- PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR =
- new PropertyValueCombinationPolicy(){
- @Override
- public PropertyValue collect(PropertyValue currentValue, String key,
- PropertySource propertySource) {
- PropertyValue value = propertySource.get(key);
- return value!=null?value:currentValue;
- }
- };
-
- PropertyValue collect(PropertyValue currentValue, String key,
- PropertySource propertySource);
-
-}
---------------------------------------------
-
-Looking at the +collect+ method's signature, returning a +PropertyValue+ allows also to filter/combine/use meta entries.
-
-
[[ConfigurationContext]]
==== The Configuration Context
-A +Configuration+ is created from a +ConfigurationContext+. Each +Configuration+ instance provides it's underlying
-context by +Configuration.getContext()+:
+A +Configuration+ is created based on a +ConfigurationContext+, which ia accessible calling
++configuration.getContext()+:
[source,java]
-.Accessing the current +ConfigurationContext+
+.Accessing the +ConfigurationContext+ of a configuration
--------------------------------------------
Configuration config = ...;
ConfigurationContext context = config.getContext();
--------------------------------------------
-The +ConfigurationContext+ provides access to the internal artifacts that determine the +Configuration+ and
-also defines the ordering of the property sources, filters and converters contained:
+The +ConfigurationContext+ provides access to the internal artifacts that determine the +Configuration+.
+Similarly the context also defines the ordering and significance of property sources, filters and
+converters:
* +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances).
* +PropertyFilters+ registered, which filter values before they are returned to the client
* +PropertyConverter+ instances that provide conversion functionality for converting String values to any other types.
-* the current +PropertyValueCombinationPolicy+ that determines how property values from different PropertySources are
- combined to the final property value returned to the client.
[[Mutability]]
-==== Changing the current Configuration Context
-
-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:
+==== Changing a Configuration
-* New configuration files where detected in a folder observed by Tamaya.
-* Remote configuration, e.g. stored in a database or alternate ways has been updated and the current system must
- be adapted to these changes.
-* The overall configuration context is manually setup by the application logic.
-* Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the
- tests executed.
+A +Configuration+ is basically not mutable. Nevertheless when the containing property sources provide different
+values, e.g. because a configuration file has been updated, also the configuration values may change
+(dependiing on the significance of the changed property source).
-In such cases the +ConfigurationContext+ may change, meaning it must be possible:
+Nevertheless it is also possible to create a new +ConfigurationBuilder+ based on an existing configuration
+and add/remove property sources, filters or converters as needed.
-* to add or remove +PropertySource+ instances
-* to add or remove +PropertyFilter+ instances
-* to add or remove +PropertyConverter+ instances
-* to redefine the current +PropertyValueCombinationPolicy+ instances.
+A new configuration builder can be easily accessed from an existing configuration as follows:
-This is nothing new, a +ConfigurationContextBuilder+ already allows us to achive this. So we must only ensure that
-we can easily create a new +ConfigurationContextBuilder+ using a given +ConfigurationContext+ as input. This can be
-done by
+[source,java]
+.Accessing a +ConfigurationContextBuilder+
+--------------------------------------------
+Configuration config = ...;
+ConfigurationBuilder preinitializedConfigBuilder = config.toBuilder();
+--------------------------------------------
-* calling +ConfigurationContext.toBuilder()+, hereby returning a builder instance preinitialized with the values from the
- current +ConfigurationContext+.
-* calling +ConfigurationProvider.getConfigurationContextBuilder()+ and then applying the current +ConfigurationContext+
- by calling +setContext(ConfigurationContext)+ on the +ConfigurationContextBuilder+ instance.
+It is also possible to builkd up a configuration completely from scratch, having full control on the
+resources included:
[source,java]
.Accessing a +ConfigurationContextBuilder+
--------------------------------------------
-ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext().toBuilder();
-ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder();
+ConfigurationBuilder emptyConfigBuilder = Configuration.createConfigurationBuilder();
--------------------------------------------
-Finally when we are finished a new +ConfigurationContext+ can be created:
+Using the builder we then can change the configuration as needed:
[source,java]
-.Creating and applying a new +ConfigurationContext+
--------------------------------------------
-ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext()
- .toBuilder();
- .addPropertySources(new MyPropertySource())
- .addPropertyFilter(new MyFilter())
- .build();
+ConfigurationBuilder builder = Configuration.crteateConfigurationBuilder();
+builder.addPropertySources(new MyPropertySource())
+ .addPropertyFilter(new MyFilter())
+ .setMeta("a.b.c.collectionType", "List")
+ .build();
--------------------------------------------
-But let's also have a deeper look at what functionality a +ConfigurationContextBuilder+ provides. Basically such a
+
+Let's have a short look at the +ConfigurationBuilder+. Basically such a
builder allows to add, remove or reorder property sources, converters and filters or changing any other aspect
-of a +ConfigurationContext+:
+of a +Configuration+. Finally a new +Configuration+ instance can be built.
[source,java]
.Chain manipulation using +ConfigurationContextBuilder+
@@ -593,41 +589,37 @@ builder.decreasePriority(propertySource);
builder.sortPropertyFilters(MyFilterComparator::compare);
--------------------------------------------
-Finally if the new +ConfigurationContext+ is ready a new +Configuration+ can be created.
-Optionally the new +Configuration+ can also be installed as the new _default_ +Configuration+
-instace as illustrated below:
+Finally if a new +Configuration+ can be built. Optionally the new +Configuration+ can also be installed as
+the _default_ +Configuration+ instance as illustrated below:
[source,java]
-.Creating and applying a new +ConfigurationContext+
+.Creating and applying a new +Configuration+
--------------------------------------------
-ConfigurationContext context = builder.build();
-
// Creates a new matching Configuration instance
-Configuration newConfig = ConfigurationProvider.createConfiguration(context);
+Configuration config = builder.build();
// Apply the new context to replace the current configuration:
-ConfigurationProvider.setConfiguration(newConfig);
+Configuration.setCurrent(newConfig);
--------------------------------------------
-Hereby +ConfigurationProvider.setConfiguration(Configuration)+ can throw an +UnsupportedOperationException+.
-This can be checked by calling the method +boolean ConfigurationProvider.isConfigurationSettable()+.
+Hereby +Configuration.setCurrent(Configuration)+ can throw an +UnsupportedOperationException+.
+This can be checked by calling the method +boolean Configuration.isConfigurationSettable()+.
+== SPI
[[ConfigurationProviderSpi]]
-==== Implementing and Managing Configuration
+=== Implementing and Managing Configuration
One of the most important SPI in Tamaya is the +ConfigurationProviderSpi+ interface, which is backing up the
-+ConfigurationProvider+ singleton. Implementing this class allows
-
-* to fully determine the implementation class for +Configuration+
-* to manage the current +Configuration+ in the scope and granularity required.
-* to provide access to the right +Configuration+ based on the current runtime context.
-* Performing changes as set with the current +ConfigurationContextBuilder+.
++Configuration+ static accessor methods. Implementing this interface allows
-= Interface ConfigurationContextBuilder
+* to fully determine the implementation class for +Configuration, ConfigurationBuilder, ConfigurationContext+
+* to manage +Configurations+ in the scope and granularity required.
+* to provide access to the right +Configuration+ based on the current runtime context (e.g. classloader).
[[BuilderCore]]
-== Interface ConfigurationContextBuilder
+== Interface ConfigurationBuilder
+
=== Overview
The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances,
@@ -635,12 +627,12 @@ e.g. as follows:
[source,java]
---------------------------------------------------------------
-ConfigurationBuilder builder = new ConfigurationBuilder();
+ConfigurationBuilder builder = Configuration.createConfigurationBuilder();
// do something
Configuration config = builder.build();
---------------------------------------------------------------
-Basically the builder allows to create configuration instances completely independent of the current configuration
+Basically a builder allows to create configuration instances completely independent of the current configuration
setup. This gives you full control how and when +Configuration+ is created.
@@ -650,12 +642,12 @@ The builder allows you to add +PropertySource+ instances:
[source,java]
----------------------------------------------------------------
-ConfigurationContextBuilder builder = ConfigurationProvider.getConfigurationContextBuilder();
+ConfigurationBuilder builder = Configuration.createConfigurationBuilder();
builder.addPropertySources(sourceOne, sourceTwo, sourceThree
-Configuration config = ConfigurationProvider.createConfiguration(builder.build());
+Configuration config = builder.build();
----------------------------------------------------------------
-Hereby the ordering of the propertysources is not changed, regardless of the ordinals provided
+Hereby the ordering of the property sources 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.
@@ -674,10 +666,11 @@ builder.addPropertyFilters(new MyConfigFilter());
builder.addPropertySourceProvider(new MyPropertySourceProvider());
----------------------------------------------------------------
+...and of course converters and other artifacts.
[[ServiceContext]]
-==== The ServiceContext
+== The ServiceContext
The +ServiceContext+ allows to define how components are loaded in Tamaya. It is the glue layer, which interacts
with the underlying runtime system such as Java SE, Java EE, OSGI, VertX etc.
@@ -687,32 +680,54 @@ The +ServiceContext+ hereby defines access methods to obtain components, whereas
[source,java]
.Accessing the +ServiceContext+
--------------------------------------------
+// using an explicit classloader (recommended)
+ClassLoader classloader = ...;
+ServiceContext serviceContext = ServiceContextManager.getServiceContext(classloader);
+
+// using the default classloader
ServiceContext serviceContext = ServiceContextManager.getServiceContext();
public interface ServiceContext{
int ordinal();
<T> T getService(Class<T> serviceType);
+ <T> T getService(Class<T> serviceType, Supplier<T> serviceSupplier);
+ <T> T createService(Class<T> serviceType);
+ <T> T createService(Class<T> serviceType, Supplier<T> serviceSupplier);
<T> List<T> getServices(Class<T> serviceType);
+ <T> List<T> getServices(Class<T> serviceType, Supplier<List<T>> serviceSupplier);
+ <T> T register(Class<T> type, T instance, boolean force);
+ <T> List<T> register(Class<T> type, List<T> instances, boolean force);
+
+ Enumeration<URL> getResources(String resource) throws IOException;
+ URL getResource(String resource);
+
}
--------------------------------------------
With the +ServiceContext+ a component can be accessed in two different ways:
-. 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.
-. access all items given a type. This will return (by default) all instances loadedable from the current
- runtime context, ordered by priority (the most significant components added first).
+. access as as a single service. Hereby the detected services (if multiple) are sorted by priority and then finally
+ the most significant instance (the one with the highest priority value) is selected and cached.
+. access all items given a type. This will return (by default) all service instances loadedable from the current
+ runtime context (classloader), ordered by priority (the most significant components added first).
+. service lookup can be further customized by passing suppliers. The supplier is called if no default services
+ could be auto-detected. The supplied instance(s) are registered and cached for subsequent accesses.
+. the _register_ methods allow to explcitly register (and optionally override) a service or services
+ registered.
+. Finally the methods `getResource(s)` allow to load resources from the classpath. This is especially useful
+ when running in an OSGI context, where loading of resources from the classloaders will fail.
## Examples
### Accessing Configuration
-_Configuration_ is obtained from the ConfigurationProvider singleton:
+_Configuration_ is obtained from the `Configuration` interface using static accessors:
[source,java]
.Accessing +Configuration+
--------------------------------------------
-Configuration config = ConfigurationProvider.getConfiguration();
+Configuration config = Configuration.current();
+Configuration config = Configuration.current(Thread.currentThread().getContextClassLoader());
--------------------------------------------
Many users in a SE context will probably only work with _Configuration_, since it offers all functionality
@@ -721,9 +736,10 @@ very similar to *Map<String,String>*, whereas in Java 8 additionally usage of _O
[source,java]
--------------------------------------------
-Configuration config = ConfigurationProvider.getConfiguration();
-String myKey = config.get("myKey"); // may return null
-int myLimit = config.get("all.size.limit", int.class);
+Configuration config = Configuration.current();
+String myValue = config.get("myKey"); // access as (raw) String value.
+int myLimit = config.get("all.size.limit", int.class); // access a value using type conversion.
+List<URL> urls = config.get("all.urls", new TypeLiteral<List<URL>>(); // access a value using advanced type conversion.
--------------------------------------------
@@ -737,7 +753,7 @@ _PROMPT_ environment variable as follows:
String prompt = ConfigurationProvider.getConfiguration().get("PROMPT");
--------------------------------------------
-Similary the system properties are directly applied to the _Configuration_. So if we pass the following system
+Similary the system properties are directly applied to the _Configuration_. Let's assume, we pass the following system
property to our JVM:
[source,java]
@@ -745,18 +761,18 @@ property to our JVM:
java ... -Duse.my.system.answer=yes
--------------------------------------------
-we can access it as follows:
+We can then access the value from the configuration:
[source,java]
--------------------------------------------
-boolean useMySystem = ConfigurationProvider.getConfiguration().get("use.my.system.answer", boolean.class);
+boolean useMySystem = Configuration.current().get("use.my.system.answer", boolean.class);
--------------------------------------------
-### Adding a Custom Configuration
+### Adding additional configuration entries
-Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the
-_tamaya-spi-support_ module you just have to perform a few steps:
+Adding additional configuration entries is simple: just implement an according `PropertySource` and register
+it with the Java `ServiceLoader`. Using the _tamaya-spi-support_ extension library you just have to perform a few steps:
. Define a PropertySource as follows:
@@ -788,5 +804,13 @@ com.mypackage.MyPropertySource
[[APIImpl]]
== API Implementation
-The API is implemented by the +tamaya-core+ module. Refer to the link:core.html[Core documentation] for
+The Tamaya configuration API is implemented by the +tamaya-core+ module. Refer to the link:core.html[Core documentation] for
further details.
+
+Furhtermore Tamaya also implements or supports
+
+* the API as defined by JSR 310 (Config JSR)
+* the Microprofile API
+* the Spring Configuration Mechanism
+* integration with the OSGI `ConfigAdmin` API.
+* the Apache Camel Configuration SPI
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/core.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/core.adoc b/content/documentation/core.adoc
index f3cac3e..a63e199 100644
--- a/content/documentation/core.adoc
+++ b/content/documentation/core.adoc
@@ -2,31 +2,27 @@
:jbake-status: published
[[Core]]
-== Tamaya Core Implementation
+== Apache Tamaya: Core Implementation
=== Overview
-Tamaya Core provides an implementation of the link:api.html[Tamaya Configuration API] and adds additional functionality
+`tamaya-core` provides an implementation of the link:api.html[Tamaya Configuration API] and adds additional functionality
and building blocks for supporting SPI implementations.
Tamaya Core contains the following artifacts:
-* *tamaya-spisupport* provides implementations and base classes for different API artifacts such as +Configuration,
- ConfigurationContext, ConfigurationContextBuilder, ConfigurationProviderSpi, BasePropertySource+ and more. It is
- built as an independent core module, which also can be used with other implementations. The *tamaya-core*
- implementation leverages these base classes to build up a full API implementation.
-* A +java.util.ServiceLoader+ based +ServiceContext+ implementation. This allows component priorization based
- on the +@Priority+ annotations.
-* A +PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances,
- thus providing type conversion for all important types.
-* A simple default configuration setup using the current classpath and an optional staging variable.
-* It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and
- registers them in the global +ConfigurationContext+
-* It provides a +ConfigurationContextBuilder+ implementation (+DefaultConfigurationContextBuilder+) and allows to
- change the current +ConfigurationContext+.
-
-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
+* A service loader implementation, configurations and further logic required to run
+ in an OSGI environment.
+* Numerous *converters*, including an +EnumConverter+, that is a converter implementation that can automatically select
+ the currect enumeration values based on a configured entry.
+* A configurable `BannerManager`to print Tamaya's start logo on load.
+
+Basically `tamaya-core` leverages the base implementations contained in Tamaya's SPI support module, so it is quite
+small in size. All required components are implemented and registered, so basically the
+Core module with its trasitive dependencies (API and spi-support) is a complete configuration solution. Nevertheless
+it is also very minimalistic, but fortunately it can be easily extended/accommodated with additional features as needed.
+
+These extensions are managed in the extensions repository of the Tamaya project. Some of the most commonly used
+extensions are
* placeholder and resolution mechanisms (+org.apache.tamaya.ext:tamaya-resolver+)
* dynamic resource path lookup, e.g. with ant styled patterns (+org.apache.tamaya.ext:tamaya-resources+)
@@ -35,18 +31,15 @@ enough to be extended/accommodated with additional features as needed, such as
* integration with other existing solutions (e.g. +org.apache.tamaya.ext:tamaya-spring+)
* configuration and configuration isolation targeting Java EE (+org.apache.tamaya.ext:tamaya-injection-ee+)
* dynamic configuration and configuration updates (+org.apache.tamaya.ext:tamaya-events+)
-* remote configuration (+org.apache.tamaya.ext:tamaya-etcd, org.apache.tamaya.ext:tamaya-consul,
- org.apache.tamaya.ext:tamaya-hazelcast+)
-* and more
-For details about the extension modules available and their functionality refer to the link:extensions.html[extension user guide].
+For details about the extension modules available and their functionality refer to the link:extensions.html[extension
+user guide].
[[CorePropertyConverters]]
=== Default PropertyConverters
-The _SPI_ base module provides several +PropertyConverter+ implementations, which are automatically registered by the
-_Core_ module. Find below the listing of converters automatically registered with the Core module:
+The `tamaya-core` module provides several +PropertyConverter+ implementations, which are automatically registered:
[width="100%",frame="1",options="header",grid="all"]
|=======
@@ -59,29 +52,36 @@ _Core_ module. Find below the listing of converters automatically registered wit
|java.ui.lang.Class |ClassConverter |<fully qualified class name>
|java.util.Currency |CurrencyConverter |CHF, 123
|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
-|_Enums_ |EnumConverter |<Enum item name>
+|java.time.Duration |DurationConverter |<Duration as defined by Duration.parse(String)>
+|java.io.File |FileConverter |value -> new File(value)
|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE
+|java.time.Instant |InstantConverter |<Instant as defined by Instant.parse(String)>
|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
-|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String)
-|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String)
-|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)>
+|java.time.LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String)
+|java.time.LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)>
+|java.time.LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String)
|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY
+|java.time.OffsetDateTime |OffsetDateTimeConverter |<OffsetDateTime as defined by OffsetDateTime.parse(String)>
+|java.time.OffsetTime |OffsetTimeConverter |<OffsetTime as defined by OffsetTime.parse(String)>
+|java.util.Optional |OptionalConverter |
+|java.nio.Path |PathConverter |
|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE
+|java.util.Supplier |SupplierConverter |
|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true
|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true
-|ZoneId |ZoneIdConverter |Europe/Zurich
+|_Enums_ |EnumConverter |<Enum item name>
|=======
=== Registering PropertyConverters
-Additional +PropertyConverters+ can be implemented easily. It is recommended to register them using
+Additional +PropertyConverter+ classes can be implemented easily. It is recommended to register them 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 each) to enable
auto-discovery.
-Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters
+Alternatively you can also use a +ConfigurationBuilder+ to add additional converters
programmatically.
@@ -114,7 +114,7 @@ NOTE: Sorting the property sources based on their ordinal value is only the defa
+PropertySource+ implementations that provide configuration properties are registered as components as described in the
previous section. Hereby the precedence (ordering) of property sources is not hard-coded. Instead a +Comparator<PropertySource>+
-can be passed to a +ConfigurationContextBuilder+ to perform automatic ordering of the property sources
+can be passed to a +ConfigurationBuilder+ to perform automatic ordering of the property sources
registered. The default implementation hereby implements the following logic:
. It checks for an property entry +tamaya.ordinal+ if present the value is parsed into an +int+ value and used as
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc
index 76fc692..098652c 100644
--- a/content/documentation/extensions.adoc
+++ b/content/documentation/extensions.adoc
@@ -12,7 +12,6 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati
[width="100%",frame="1",options="header",grid="all"]
|=======
|_Artifact_ |_Description_ |_Links_
-| | N/A: currently no extensions have reached that maturity level. | -
|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation]
|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation]
|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. |link:extensions/mod_filter.html[Documentation]
@@ -34,8 +33,6 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati
|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation]
|=======
-NOTE: The former Tamaya _Builder_ extension module has been removed. The corresponding methods were integrated into
-Tamaya's main API's +ConfigurationContextBuilder+ interface.
=== Extensions Sandbox
@@ -43,7 +40,6 @@ Extensions in _draft state_ rather experimental or not yet very mature. API chan
and the may also have severe issues or even not work at all. So use at your own risk or join and help
us getting them stable and well tested!
-NOTE: All extensions currently require Java 8.
[width="100%",frame="1",options="header",grid="all"]
|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_classloader_support.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_classloader_support.adoc b/content/documentation/extensions/mod_classloader_support.adoc
index 50a3e61..6037153 100644
--- a/content/documentation/extensions/mod_classloader_support.adoc
+++ b/content/documentation/extensions/mod_classloader_support.adoc
@@ -10,6 +10,10 @@ toc::[]
Tamaya _Classloader_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
+CAUTION: Classloader support has been added into the main API and implementation module. This module probably is not
+ useful anymore and will probably be removed in the future.
+
+
=== What functionality this module provides ?
The Tamaya _Classloader_ support provides an alternative implementation of +java.util.ServiceLoader+, which is aware
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_collections.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_collections.adoc b/content/documentation/extensions/mod_collections.adoc
index 8078d46..8716688 100644
--- a/content/documentation/extensions/mod_collections.adoc
+++ b/content/documentation/extensions/mod_collections.adoc
@@ -20,7 +20,7 @@ Collections extension adds this functionality to the Tamaya eco-system.
=== Compatibility
-The module is based on Java 8, so it will not run on Java 7 and beyond.
+The module requires Java 8.
=== Installation
@@ -64,19 +64,21 @@ my.list.config.entry=1,34454,23,344545,3445
Additionally the module allows adding additional meta-entries, which allows to tweak some of the
inner-workings, e.g.
-* using your own +PropertyConverter+ implementation for parsing entries.
-* specifying a custom separator to split the items (default is {{','}}.
-* specifying a custom separator to split key/value pairs when parsing map entries.
-* specifying the implementation type of the collection item to be returned.
-* specifying the implementation type of the collection to be returned.
+* `item-converter`: using a custom +PropertyConverter+ implementation for parsing collection entries.
+* `entry-separator`: specifying a custom separator to split the list and map items (default is {{','}}.
+* `map-entry-separator`: specifying a custom separator to split key/value pairs when parsing map entries.
+* `collection-type`: specifying the implementation type of the collection to be returned.
+* `mapping-type`: specifying the implementation type of the collection item to be returned.
=== Supported Types
This module currently supports the following types:
+* +java.util.Iterable+
* +java.util.Collection+
* +java.util.List+
* +java.util.ArrayList+
+* +java.util.ArrayList+
* +java.util.LinkedList+
* +java.util.Set+
* +java.util.SortedSet+
@@ -87,17 +89,32 @@ This module currently supports the following types:
* +java.util.HashMap+
* +java.util.TreeMap+
-Hereby the collection type is determined by the parameter type accessed, e.g.
+
+==== Default Collection Type Mapping
+
+The collection type is determined by the parameter type accessed, e.g.
+config.get("mylist", ArrayList.class)+ will always return an +ArrayList+
as result.
+* if you have a generic type:
+ ** an `ArrayList` is returned for `Collection, List, ArrayList, Iterable`
+ ** a `HashSet` is returned for `Set, HashSet`
+ ** a `HashMap` is returned for `Map, HashMap`
+ ** a `TreeMap` is returned for `SortedMap, TreeMap`
+ ** a `TreeSet` is returned for `SortedSet, TreeSet`
+* in all other cases you have to explicitly define the collection type. Hereby you may
+ omit the `java.util` package. Collection types not contained in `java.util`
+ require adding an additional converter implementation.
NOTE: This means that depending on your use case you can access different
collection types based on the same configuration values, as long as their is
a +PropertyConverter+ that can convert the _raw configuration value_ to the
required target type.
+CAUTION: If you do *NOT* use `TypeLiteral` to define your target type, the item target type will not
+ be available to Tamaya due to Java's type erasure. In this case it will always return `String`
+ as item type.
-==== Configuring the target implementation type
+==== Configuring Collection Type Mapping
Tamaya Collections allows you to configure the _default_ target collection type by adding the
following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part +java.util.+
@@ -106,7 +123,7 @@ can be ommitted:
[ source, properties]
-----------------------------------------------
mylist=a,b,c
-_mylist.collection-type=LinkedList
+[META]mylist.collection-type=LinkedList
-----------------------------------------------
When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect, so you will still
@@ -117,17 +134,32 @@ This mechanism similarly applies to all kind of collections, so you can use it s
type returned when accessing +List+, +Map+ or +Collection+.
-=== Collecting Configuration Entries instead of Overriding
+=== Evaluating Collection Entries
+
+Tamaya's internal representation of configuration is a modelled by a `PropertyValue`. This class actually supports
+different models how configuration data can be represented:
-By default Tamaya applies always an overriding +CombinationPolicy+, where only the configuration entry for
-the most significant configuration entry is used. In case of collections (and maybe also other use cases),
-overriding is not always the mechanism of choice. E.g. when you want to have all entries added to your
-configuration to be *combined* to a new entry containing all values provided by any property sources.
+. as simple literal key-value pair, or
+. as map-like value object, or
+. as list-like list object.
-Therefore _Tamaya Collections_ also provides a more sophistiated +CombinationPolicy+ (automatically configured)
-that allows to adapt the way how configuration entries are combined. All you must do is declaring
-the mechanism to be applied by an according _meta-configuration_ parameter, e.g. for +my.list+ your config may
-look as follows:
+Tamaya's `ConversionContext` actually provides all values matching a given target key. As a consequence there
+are four basic algorithms, how a collection can be mapped from entries given:
+
+* _value_all:_ The list values are identiified by parsing the node value(s) into items, hereby
+ the items of all values are combined.
+* _value:_ The list values are identiified by parsing the node value(s) into items.
+ Hereby only the items of the most significant config entry are considered.
+* _node:_ The list values are identiified by using the node's child value(s) as items.
+ Hereby only the items of the most significant config entry are considered.
+* _node_all:_ The list values are identiified by using the node's child value(s) as items. Hereby
+ the items of all values are combined.
+* _override:_ This policy will try to guess the best _value_ and _node_ evaluation policy for most significant
+ `PropertyValue`.
+* _combine:_ This policy will try to guess the best _value_ and _node_ evaluation policy for each
+ `PropertyValue` and combine the values to one collection. *This is the default behaviour.*
+
+As an example consider the following configuration for +my.list+:
[source, properties]
-----------------------------------------------
@@ -136,23 +168,56 @@ my.list=1,2,3
# from PropertSource 2, with higher precedence
my.list=4,5,6
+-----------------------------------------------
+
+Using the _value_ evaluation policy this would result in the following final property:
-# without any additional meta-info these entries would be combined to
+[source, properties]
+-----------------------------------------------
my.list=4,5,6
-----------------------------------------------
-With Tamaya Collections you can now configure the combination policy as follows:
+Using the _value_all_ evaluation policy this would result in the following final property:
[source, properties]
-----------------------------------------------
-# use one of the default policies: override / collect
-_my.list.combination-policy=collect
+my.list=1,2,3,4,5,6
+-----------------------------------------------
-# or use your own custom CombinationPolicy to combine the values
-_my.list.combination-policy=com.mycomp.app.MyCombincationPolicy
+For the _node_based evaluation policies consider the following YAML input data:
+
+[source, yaml]
-----------------------------------------------
+# from PropertSource 1
+my.list:
+ - 1
+ - 2
+ - 3
-So declaring the +collect+ policy the resulting raw output of the entry looks as follows:
+# from PropertSource 2, with higher precedence
+my.list:
+ - 4
+ - 5
+ - 6
+-----------------------------------------------
+
+In this case the entries are mapped to `ListValue` instances with multiple children. Similar mappings would apply
+using JSON or XML configuration formats. In this case it is more useful to collect the child nodes, instead the
+values (which basically are `null` on the parent node level). This is excatly what the _node_ and _node_all_
+evaluaion policies are doing.
+
+With Tamaya Collections you can now configure the evaluation policy using metadata, e.g. when using the default
+metadata format of Tamaya:
+
+[source, properties]
+-----------------------------------------------
+# use one of the policies: node, node_all, value, value_all, override or collect
+[META]my.list.collection-mapping=collect
+-----------------------------------------------
+
+So declaring the +collect+ policy the resulting raw output of the entry looks as illustrated below. Hereby it is even
+possible to mix different representations. E.g. it is possible to add additional values in a simple property files,
+whereas other values are configured in YAML or other formats:
[source, properties]
-----------------------------------------------
@@ -160,20 +225,19 @@ So declaring the +collect+ policy the resulting raw output of the entry looks as
my.list=1,2,3,4,5,6
-----------------------------------------------
-The customizable policy mechanism of Tamaya Collections also honors the +item-separator+ meta-configuration
-parameter explained later in this document.
-=== Format of Collection Configuration
+=== Item Value Splitting
-By default collections are modelled as simple String values, that are tokenized into individual parts using a
+When evaluating collections from literal values, these values have to be tokenized into individual parts using a
defined +item-separator+ (by default +','+). So a given configuration entry of +1,2,3+ is mapped to +"1","2","3".
-If the target context type is something different than String the smae conversion logic is used as when mapping
-configuration parameters directly to non-String target types (implemented as +PropertyConverter+ classes, manahed
-within the current +ConfigurationContext+. The procedure is identical for all collection types, including +Map+ types,
-with the difference that each token in the list is parsed once more for separating it into a +key+ and a +value+.
-The default separator for map entries hereby is +"::"+. Map keys, as of now, are always of type +String+, whereas
-for values the same logic is applied as for non-map collection types.
+If the target context type is something different than String the same conversion logic is used as when mapping
+configuration parameters directly to non-String target types (implemented as +PropertyConverter+ classes).
+The procedure is identical for all collection types, including +Map+ types,
+with the difference that each token for a map is parsed additionally for separating it into a +key+ and a +value+ parts.
+The default separator for map entries hereby is +"="+. Map keys, as of now, are always of type +String+, whereas
+for values all convertible types are supported. All separator characters can be masked by prefixing them with a `\`
+character.
[source, properties]
-----------------------------------------------
@@ -181,11 +245,11 @@ for values the same logic is applied as for non-map collection types.
list=1,2,3,4,5,6
# a map, using the default format
-map=a::b, c::d
+map=a=b, c=d
-----------------------------------------------
-==== Trimming of entries
+==== Trimming
By default all tokens parsed are trimmed _before_ adding them to the final collection. In case of map entries this is
also the case for key/value entries. So the following configuration results in the identical values for
@@ -194,15 +258,15 @@ also the case for key/value entries. So the following configuration results in t
[source, properties]
-----------------------------------------------
# a list, using the default format
-list1=1,2,3,4,5,6
+list1=1, 2 ,3,4 , 5,6
list2=1, 2, 3, 4, 5, 6
# a map, using the default format
-map1=a::b, c::d
-map2=a :: b, c :: d
+map1=a =b, c= d
+map2=a=b, c = d
-----------------------------------------------
-Nevertheless truncation can be controlled by the usage of brackets, e.g. the last list or map entry will have a single
+Nevertheless trimming/truncation can be controlled by the usage of brackets, e.g. the last list or map entry will have a single
space character as value:
[source, properties]
@@ -211,7 +275,7 @@ space character as value:
list3=1, 2, 3, 4, 5, [ ]
# a map, with a ' ' value for key '0'
-map3=1 :: a, 2 :: b, 0::[ ]
+map3=1 = a, 2 = b, 0=[ ]
-----------------------------------------------
Hereby +\[+ escapes the sequence.
@@ -219,18 +283,18 @@ Hereby +\[+ escapes the sequence.
==== Customizing the format
-The item and entry separators (by default +','+ and +"::"+) can be customized by setting corresponding meta-data
-entries as follows, resulting in the same values as in the prevoius listing:
+The item and entry separators (by default +','+ and +"="+) can be customized by setting corresponding meta-data
+entries, resulting in the same values as in the previous listing:
[source, properties]
-----------------------------------------------
# a list, with a ' ' value at the end
list3=1__2__3__ 4__ 5__[ ]
-_list3.item-separator=__
+[META]list3.item-separator=__
# a map, with a ' ' value for key '0'
map3=1->a, 2->b, 0->[ ]
-_map3.map-entry-separator=->
+[META]map3.map-entry-separator=->
-----------------------------------------------
Of course these settings also can be combined:
@@ -239,6 +303,23 @@ Of course these settings also can be combined:
-----------------------------------------------
# a reformatted map
redefined-map=0==none | 1==single | 2==any
-_redefined-map.map-entry-separator===
-_redefined-map.item-separator=|
+[META]redefined-map.map-entry-separator===
+[META]redefined-map.item-separator=|
+-----------------------------------------------
+
+
+==== Using a custom Converter
+
+If configuring of item and map item separators as shown above is not sufficient, you still have an option: you can
+configure a custom converter to use for converting the given keys. This can be also configured by addinf a corresponding
+meta-configuration entry `item-converter`. As you would expect the converter must implement Tamaya's `PropertyConverter`
+interface:
+
+[source, properties]
-----------------------------------------------
+# a map using a custom converter
+server.0=server1, localhost:8001
+server.1.name=server2, localhost:8000, master=true
+server.2=server3, localhost:8003
+[META]server.item-converter=com.mycompany.config.ServerConverter
+-----------------------------------------------
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_events.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_events.adoc b/content/documentation/extensions/mod_events.adoc
index ccba9d1..44b0a94 100644
--- a/content/documentation/extensions/mod_events.adoc
+++ b/content/documentation/extensions/mod_events.adoc
@@ -27,7 +27,7 @@ change events.
=== Compatibility
-The module is based on Java 7, so it can be used with Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -59,7 +59,7 @@ public interface ConfigEvent<T> {
long getTimestamp();
}
-// @FunctionalInterface
+@FunctionalInterface
public interface ConfigEventListener {
void onConfigEvent(ConfigEvent<?> event);
@@ -94,20 +94,23 @@ public final class ConfigEventManager {
private ConfigEventManager() {}
- public static void addListener(ConfigEventListener l);
- public static <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
- public static void removeListener(ConfigEventListener l);
- public static <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
- public static <T extends ConfigEvent>
+ public static ConfigEventManager getInstance();
+ public static ConfigEventManager getInstance(ClassLoader classLoader);
+
+ public void addListener(ConfigEventListener l);
+ public <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
+ public void removeListener(ConfigEventListener l);
+ public <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
+ public <T extends ConfigEvent>
Collection<? extends ConfigEventListener> getListeners();
- public static <T extends ConfigEvent>
+ public <T extends ConfigEvent>
Collection<? extends ConfigEventListener> getListeners(Class<T> type);
- public static <T> void fireEvent(ConfigEvent<?> event);
- public static <T> void fireEventAsynch(ConfigEvent<?> event);
+ public <T> void fireEvent(ConfigEvent<?> event);
+ public <T> void fireEventAsynch(ConfigEvent<?> event);
- public static void enableChangeMonitoring(boolean enable);
- public static boolean isChangeMonitoring();
+ public void enableChangeMonitoring(boolean enable);
+ public boolean isChangeMonitoring();
public long getChangeMonitoringPeriod();
public void setChangeMonitoringPeriod(long millis);
@@ -263,7 +266,7 @@ In code freezing is a no-brainer:
[source,java]
.Freezing the current Configuration
--------------------------------------------------
-Configuration config = ConfigurationProvider.getConfiguration();
+Configuration config = Configuration.current();
Configuration frozenConfig = FrozenConfiguration.of(config);
--------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_filter.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_filter.adoc b/content/documentation/extensions/mod_filter.adoc
index bce6947..a41d187 100644
--- a/content/documentation/extensions/mod_filter.adoc
+++ b/content/documentation/extensions/mod_filter.adoc
@@ -22,7 +22,7 @@ explicitily no filtering is applied and everything is visible.
=== Compatibility
-The module is based on Java 7, so it will not run on Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -43,9 +43,9 @@ To benefit from filter support you only must add the corresponding dependency to
Tamaya Filter comes basically with 3 artifacts:
-* The +org.apache.tamaya.filter.ConfigurationFilter+ provides several static methods to register +PropertyFilter+
+* The +org.apache.tamaya.filter.ThreadBasedConfigurationFilter+ provides several static methods to register +PropertyFilter+
instances on the current thread.
-* The +org.apache.tamaya.filter.DefaultMetdataFilter+ is a +PropertyFilter+ with hides all entries starting with
+* The +org.apache.tamaya.filter.ThreadFilterContext+ is a +PropertyFilter+ with hides all entries starting with
an underscore ('_'), when a full property map is accessed.
@@ -95,22 +95,22 @@ is part of this module, So you can add a customized filter as follows:
[source, java]
-----------------------------------------------
try {
- ConfigurationFilter.getMapFilters().addFilter(new myFilter());
+ ThreadBasedConfigurationFilter.getMapFilters().addFilter(new myFilter());
// do your code with filtering active
}
finally {
// cleanup
- ConfigurationFilter.clearFilters();
+ ThreadBasedConfigurationFilter.clearFilters();
}
-----------------------------------------------
-The +FilterContext+ is a simple structure just providing some handy accessors to the dynamic thread-local
+The +ThreadFilterContext+ is a simple structure just providing some handy accessors to the dynamic thread-local
managed filters:
[source, java]
-----------------------------------------------
-public final class FilterContext implements PropertyFilter {
+public final class ThreadFilterContext implements PropertyFilter {
public void addIncludes(PropertyFilter filter);
public void addExcludes(int pos, PropertyFilter filter);
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_formats.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_formats.adoc b/content/documentation/extensions/mod_formats.adoc
index aa7d559..db3202c 100644
--- a/content/documentation/extensions/mod_formats.adoc
+++ b/content/documentation/extensions/mod_formats.adoc
@@ -24,7 +24,7 @@ Tamaya _Formats_ provides an abstraction for configuration formats provding the
=== Compatibility
-The module is based on Java 7, so it can be used with Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -66,34 +66,20 @@ public final class ConfigurationData {
public ConfigurationFormat getFormat();
public String getResource();
- public Set<String> getSectionNames();
- public Map<String,String> getSection(String name);
-
- public boolean hasDefaultProperties();
- public Map<String,String> getDefaultProperties();
- public Map<String,String> getCombinedProperties();
+ public List<PropertyValue> getData();
public boolean isEmpty();
}
-------------------------------------------------------
-In detail the data read from a file is organized into _sections_ as follows:
-
* with +getResource()+ and +getFormat()+ the underlying resource and the format that read this data can be accessed.
-* properties can be owned by
- ** named sections
- ** an (unnamed) default section
-* each section section contains a map of properties. Hereby the same key can be part of the default section and multiple
- named sections, depending on the configuration format.
-* The method +getSectionNames()+ returns a set of all section names.
-* With +getSection(String name)+ a named section can be accessed.
-* With +getDefaultSection()+ the 'default' section can be accessed. This is a convenience method.
-* With +getCombinedProperties()+ a flattened entry map can be accessed built up (by default) out of
- ** all entries from the default section, without any changes.
- ** all entries from named sections, where the key for each entry is prefix with the section name and a '::' separator.
-* The configuration format used determines the mapping of configuration data read into this structure. The format
- implementation can as well provide alternate implementations of how the data read should be mapped into the
- combined properties map.
+* +getData()+ allows access to the data read. Hereby this data can be mapped in different ways:
+** as (multiple) simple key-value literal pairs, or
+** as field-mapped object type values, or as
+** list values
+** the children of list and object values can be of any of the three types described above. As a consequence a simple
+ `PropertyValue` can be a simple literal value, or a complex tree/list structure, similar to common configuration
+ formats.
==== ConfigurationFormat
@@ -111,6 +97,7 @@ public interface ConfigurationFormat {
}
-------------------------------------------------------
+
=== Creating a default PropertySource for a ConfigurationFormat
The module defines a singleton +ConfigurationFormats+ which provides
@@ -121,32 +108,35 @@ using abstract +ConfigurationFormat+ implementations:
-------------------------------------------------------
public final class ConfigurationFormats {
- public static List<ConfigurationFormat> getFormats();
- public static List<ConfigurationFormat> getFormats(String... formatNames);
- public static List<ConfigurationFormat> getFormats(final URL url);
+ public static ConfigurationFormats getInstance();
+ public static ConfigurationFormats getInstance(ClassLoader classLoader);
+
+ public List<ConfigurationFormat> getFormats();
+ public List<ConfigurationFormat> getFormats(String... formatNames);
+ public List<ConfigurationFormat> getFormats(final URL url);
- public static ConfigurationData readConfigurationData(final URL url)
+ public ConfigurationData readConfigurationData(final URL url)
throws IOException;
- public static ConfigurationData readConfigurationData(URL url, ConfigurationFormat... formats)
+ public ConfigurationData readConfigurationData(URL url, ConfigurationFormat... formats)
throws IOException;
- public static ConfigurationData readConfigurationData(URL url, Collection<ConfigurationFormat> formats)
+ public ConfigurationData readConfigurationData(URL url, Collection<ConfigurationFormat> formats)
throws IOException;
- public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, ConfigurationFormat... formats);
- public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, Collection<ConfigurationFormat> formats);
- public static ConfigurationData readConfigurationData(String resource, InputStream inputStream,
+ public Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, ConfigurationFormat... formats);
+ public Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, Collection<ConfigurationFormat> formats);
+ public ConfigurationData readConfigurationData(String resource, InputStream inputStream,
ConfigurationFormat... formats)
throws IOException;
- public static ConfigurationData readConfigurationData(String resource, InputStream inputStream,
+ public ConfigurationData readConfigurationData(String resource, InputStream inputStream,
Collection<ConfigurationFormat> formats)
throws IOException;
- public static PropertySource createPropertySource(URL url, ConfigurationFormat... formats)
+ public PropertySource createPropertySource(URL url, ConfigurationFormat... formats)
throws IOException;
- public static PropertySource createPropertySource(URL url, Collection<ConfigurationFormat> formats)
+ public PropertySource createPropertySource(URL url, Collection<ConfigurationFormat> formats)
throws IOException;
- public static PropertySource createPropertySource(String resource, InputStream inputStream,
+ public PropertySource createPropertySource(String resource, InputStream inputStream,
ConfigurationFormat... formats);
- public static PropertySource createPropertySource(String resource, InputStream inputStream,
+ public PropertySource createPropertySource(String resource, InputStream inputStream,
Collection<ConfigurationFormat> formats);
}
-------------------------------------------------------
@@ -166,10 +156,10 @@ So creating a +PropertySource+ from a resource is basically a one liner:
[source,java]
-------------------------------------------------------
URL url = ...;
-PropertySource propertySource = ConfigurationFormats.createPropertySource(url);
+PropertySource propertySource = ConfigurationFormats.getInstance().createPropertySource(url);
// constraining the formats to be used (assumption: json and yaml extensions are loaded)
-PropertySource propertySource = ConfigurationFormats.createPropertySource(
+PropertySource propertySource = ConfigurationFormats.getInstance().reatePropertySource(
url,
ConfigurationFormats.getFormats("json", "yaml"));
-------------------------------------------------------
@@ -177,25 +167,19 @@ PropertySource propertySource = ConfigurationFormats.createPropertySource(
=== Customize how ConfigurationData maps to PropertySource
-For for the conversion of +ConfigurationData+ into a +PropertySource+ different approaches can be useful:
-
-. The +ConfigurationFormat+ that reads the data can provides all properties read either as sectioned properties
- or/and as default properties. The most simple cases is, where all properties have been added as 'default'
- properties. In this case the default properties can be used as the property sources properties without any change.
-. If the format did also add section based properties, the combined properties returned can be used, hereby
- replacing the '::' separator with a '.' separator.
-. In all other cases a custom mapping is useful, which can be acomplished by using the +MappedConfigurationDataPropertySource+
- and overriding the +Map<String,String> populateData(ConfigurationData data)+ method.
-
+For for the conversion of +ConfigurationData+ into a +PropertySource+ different approaches can be useful.
In most cases the usage of a +MappedConfigurationDataPropertySource+, is a good choice to start. This class
-provides a convenient default mapping and also allows to customized the mapping easily:
+provides a convenient default mapping and also allows to customized the mapping easily: it simply iterates over all
+values recursively and adds them using their fully qualified name as single value properties.
+
+This behaviour can be easily adapted by overriding the +popoulateData+ method:
[source,java]
-------------------------------------------------------
ConfigurationData data = ...;
MappedConfigurationDataPropertySource ps =
new MappedConfigurationDataPropertySource(data){
- protected Map<String, String> populateData(ConfigurationData data) {
+ protected Map<String, PropertyValue> populateData(ConfigurationData data) {
...
}
};
@@ -204,9 +188,9 @@ MappedConfigurationDataPropertySource ps =
Nevertheless, depending on the context, where a configuration source was read (classloader, time, source etc.) the
resulting properties can have different semnatics, especially different priorities. Also section
names may be mapped into different ordinals instead of using them as key prefixes (e.g. imagine configuration formats
-with a 'default', 'main', and 'overrides' sections). For such more complex or custom cases no simple mapping
+with a 'default', 'main', and 'overrides' sections). For such use cases no simple mapping
can be defined. Consequently the functionality mapping the normalized +ConfigurationData+ read to the
-appropriate collection of +PropertySource+ instances must be implemented.
+appropriate collection of +PropertySource+ instances must be implemented by the client code.
For this scenario the +BaseFormatPropertySourceProvider+ can be used, defining the following mapping
function that mus be implemented:
@@ -262,9 +246,9 @@ This file content by default is mapped to the following Tamaya properties:
-------------------------------------------------------
a=valA
a.b=valB
-section1::valA=sectionValA
-section1::a.b.c=SectionValC
-section2::a=val2Section2
+section1.valA=sectionValA
+section1.a.b.c=SectionValC
+section2.a=val2Section2
-------------------------------------------------------
Summarizing
@@ -272,7 +256,7 @@ Summarizing
* entries without a section are mapped to the _default_ section.
* entries with a section are mapped to a corresponding section, hereby everything between
the brackets is used as section name (trimmed).
-* section names are separated using a double colon (`::`).
+* section names are separated using a double colon (`.`), they are modelled as simple parent `PropertyValue` nodes.
+ConfigurationData+ allows to access all the different parts:
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_functions.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_functions.adoc b/content/documentation/extensions/mod_functions.adoc
index 50a2b8b..afb8b3c 100644
--- a/content/documentation/extensions/mod_functions.adoc
+++ b/content/documentation/extensions/mod_functions.adoc
@@ -51,36 +51,36 @@ For using the functionality shown in this document you only must add the corresp
The following sections explain the provided functions defined by +ConfigurationFunctions+ singleton.
-* *ConfigOperator filter(PropertyMatcher matcher)* creates a +ConfigOperator+ that creates a +Configuration+
+* *UnaryOperator<Configuration> filter(PropertyMatcher matcher)* creates a +UnaryOperator<Configuration>+ that creates a +Configuration+
containing only keys that are selected by the given _matcher predicate_. The +PropertyMatcher+ hereby allows to evaluate not only
the _key_, but also the _value_.
-* *ConfigOperator map(KeyMapper keyMapper)* creates a +ConfigOperator+ that maps the keys as defined
+* *UnaryOperator<Configuration> map(KeyMapper keyMapper)* creates a +UnaryOperator<Configuration>+ that maps the keys as defined
by the given _keyMapper_.
-* *ConfigOperator section(String section)* creates a +ConfigOperator+ that creates a +Configuration+ containing only
+* *UnaryOperator<Configuration> section(String section)* creates a +UnaryOperator<Configuration>+ that creates a +Configuration+ containing only
entries that are direct or indirect members of the given section.
-* *ConfigOperator section(String areaKey, boolean stripKeys)* creates a +ConfigOperator+ that creates a +Configuration+
+* *UnaryOperator<Configuration> section(String areaKey, boolean stripKeys)* creates a +UnaryOperator<Configuration>+ that creates a +Configuration+
containing only entries that are direct or indirect members of the given section. Hereby _stripKeys_ allows to determine
if the returned entries should be relative to the search criteria {{stripKeys=true}} or absolute keys.
* *isKeyInSection(String section, String sectionKey)* allows to easily determine if a given _key_ is a direct or indirect member
of a given section.
* *boolean isKeyInSections(String key, String... sectionKeys)* allows to easily determine if one key of given
_key_ is a direct or indirect member of at least one of the given _sectionKeys_.
-* *ConfigQuery<Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that
+* *Function<Configuration,Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that
also have parameters present).
-* *ConfigQuery<Set<String>> transitiveSections()* allows to query all the contained fully qualified section names,
+* *Function<Configuration,Set<String>> transitiveSections()* allows to query all the contained fully qualified section names,
including the transitive closure of sections.
-* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
+* *Function<Configuration,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
qualified section names that are selected by the given _predicate_.
-* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
+* *Function<Configuration,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
qualified section names that are selected by the given _predicate_, including the transitive closure of sections
identified.
-* *ConfigOperator sectionsRecursive(String... sectionKeys)* provides a +ConfigOperator+ that filters all sections identified
+* *UnaryOperator<Configuration> sectionsRecursive(String... sectionKeys)* provides a +UnaryOperator<Configuration>+ that filters all sections identified
by the given _sectionKeys_ and its child sections.
-* *ConfigOperator sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +ConfigOperator+
+* *UnaryOperator<Configuration> sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +UnaryOperator<Configuration>+
that filters all sections identified by the given _sectionKeys_ and its child sections. _stripKeys_ allows to
determine if the resulting configuration should be relative to the selected areas ({{stripKeys=true}}) or
absolute (filtering only).
-* *ConfigQuery<String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+
+* *Function<Configuration,String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+
representation.
[8/8] incubator-tamaya-site git commit: Moved collections, consul,
etcd and hazelcast modules into extensions. Updated docs to match
code.
Posted by an...@apache.org.
Moved collections, consul, etcd and hazelcast modules into extensions.
Updated docs to match code.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/8dd2accd
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/8dd2accd
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/8dd2accd
Branch: refs/heads/master
Commit: 8dd2accdecaff328afa462e36ff90350d7027ec1
Parents: 7fc31c0
Author: Anatole Tresch <at...@gmail.com>
Authored: Thu Nov 8 00:26:28 2018 +0100
Committer: Anatole Tresch <at...@gmail.com>
Committed: Thu Nov 8 00:26:28 2018 +0100
----------------------------------------------------------------------
content/documentation/extensions.adoc | 13 +-
.../extensions/mod_classloader_support.adoc | 2 +-
.../documentation/extensions/mod_consul.adoc | 42 +++--
content/documentation/extensions/mod_etcd.adoc | 165 +++----------------
.../documentation/extensions/mod_hazelcast.adoc | 57 ++-----
5 files changed, 68 insertions(+), 211 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc
index 098652c..3186910 100644
--- a/content/documentation/extensions.adoc
+++ b/content/documentation/extensions.adoc
@@ -13,23 +13,26 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati
|=======
|_Artifact_ |_Description_ |_Links_
|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-consul+ |Integration with consul clusters. |link:extensions/mod_consul.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-etcd+ |Integration with etcd clusters. |link:extensions/mod_etcd.html[Documentation]
|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation]
|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. |link:extensions/mod_filter.html[Documentation]
|+org.apache.tamaya.ext:tamaya-features+ |Provides a simple feature check for loaded extensions. |link:extensions/mod_features.html[Documentation]
|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation]
|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-hazelcast+ |Integration with Hazelcast datagrids. |link:extensions/mod_hazelcast.html[Documentation]
|+org.apache.tamaya.ext:tamaya-injection-api+ |Provides Tamaya's injection annotations API. |link:extensions/mod_injection.html[Documentation]
|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and configuration template support. |link:extensions/mod_injection.html[Documentation]
|+org.apache.tamaya.ext:tamaya-injection-cdi+ | Java EE/standalone compliant CDI integration using CDI for injection. | link:extensions/mod_cdi.html[Documentation]
|+org.apache.tamaya.ext:tamaya-jndi+ |Provides a JNDI based PropertySource. |link:extensions/mod_jndi.html[Documentation]
|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-microprofile+ |Implemenation and Integration with the Microprofile API. | link:extensions/mod_microprofile.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-microprofile+ |Implemenation and Integration with the Microprofile API. |link:extensions/mod_microprofile.html[Documentation]
|+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation]
|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation]
|+org.apache.tamaya.ext:tamaya-osgi+ |Integration with OSGI containers. |link:extensions/mod_osgi.html[Documentation]
|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-spring+ |Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-spring+ |Integration for Spring / Spring Boot. |link:extensions/mod_spring.html[Documentation]
|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation]
|=======
@@ -45,12 +48,8 @@ us getting them stable and well tested!
|=======
|_Artifact_ |_Description_ |_Links_
|+org.apache.tamaya.ext:tamaya-camel_beta+ |Integration with Apache Camel. | link:extensions/mod_camel.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-classloader-support+ |Configuration services considering classloaderas. |link:extensions/mod_classloader_support.html[Documentation]
|+org.apache.tamaya.ext:tamaya-commons_beta+ |Integration Support for Apache Commons. | -
|+org.apache.tamaya.ext:tamaya-configured-sysprops_beta+ | Tamaya configuration to be provided as +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-consul_beta+ |Integration with consul clusters. | link:extensions/mod_consul.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-etcd_beta+ |Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-hazelcast_beta+ |Integration with Hazelcast datagrids. | link:extensions/mod_hazelcast.html[Documentation]
|+org.apache.tamaya.ext:tamaya-jodatime_beta+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation]
|+org.apache.tamaya.ext:tamaya-management_alpha+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation]
|+org.apache.tamaya.ext:tamaya-metamodel_alpha+ |Provides an XML API for building configuration. |link:extensions/mod_metamodel-staged.html[Documentation]
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions/mod_classloader_support.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_classloader_support.adoc b/content/documentation/extensions/mod_classloader_support.adoc
index 6037153..d816f50 100644
--- a/content/documentation/extensions/mod_classloader_support.adoc
+++ b/content/documentation/extensions/mod_classloader_support.adoc
@@ -11,7 +11,7 @@ toc::[]
Tamaya _Classloader_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
CAUTION: Classloader support has been added into the main API and implementation module. This module probably is not
- useful anymore and will probably be removed in the future.
+ useful anymore and will be removed in the future.
=== What functionality this module provides ?
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions/mod_consul.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_consul.adoc b/content/documentation/extensions/mod_consul.adoc
index 8a988a5..094e8be 100644
--- a/content/documentation/extensions/mod_consul.adoc
+++ b/content/documentation/extensions/mod_consul.adoc
@@ -1,7 +1,7 @@
:jbake-type: page
:jbake-status: published
-= Apache Tamaya - Extension: Integration with consul (Hashicorp)
+= Apache Tamaya - Extension: Integration with Consul (Hashicorp)
toc::[]
@@ -22,7 +22,7 @@ defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension mod
=== Compatibility
-The module is based on Java 7, so it will not run on Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -39,28 +39,38 @@ To use _tamaya-consul_ you only must add the corresponding dependency to your mo
-----------------------------------------------
-=== The Extensions Provided
+=== The Functionality Provided
-Consul integration comes basically with 2 artifacts:
+Tamaya Consul provides two artifacts:
-* The +org.apache.tamaya.etcd.ConsulPropertySource+ is a +PropertySource+ with a default
- ordinal of 100 and the name 'consul', which is automatically registered.
-* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
- by accessing a +MutableConfiguration+ using the URI +config:consul+.
+* The +org.apache.tamaya.consul.ConsulPropertySource+ is a +PropertySource+ with a default
+ ordinal of 100 and the name 'consul'.
+* +org.apache.tamaya.consul.ConsulPropertySource+ is based on +org.apache.tamaya.consul.AbstractConsulPropertySource+,
+ which provides all required basic functionality to implement your own consul based property
+ sources.
Access of consul key/value pairs is through the normal Tamaya API.
=== The ConsulPropertySource
-The +ConsulPropertySource+ is automatically registered and allows the consul servers to be used to be configured. This
-enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
-in microservice containers to connect with the according consul cluster:
+The +ConsulPropertySource+ allows the consul servers to be used as configuration backends. It provides:
-* The property source reads the +tamaya.consul.urls+ system and environment property to evaluate possible consul servers
- (comma separated), which can be connected to. On failure the API just performs a Round-Robin through the list of
+* a Consul based property source implementation.
+* configurable caching of key/values accessed (Consul does not provide reading all values out).
+* configuring a optional key prefix for defining a namespace for Tamaya configuration within the consul key/value
+ store.
+* +ConsulPropertySource+ reads the +tamaya.consul.urls+ system and environment property to evaluate the consul servers
+ to be used (comma separated). The API just performs a Round-Robin through the list of
configured servers. Without any configuration +http://127.0.0.1:2400+ is used. If no connection to any consul
server can be established a warning will be logged, but deployment will not fail.
-* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped to prefixed
- context. This can be activated by setting the `-Dtamaya.consul.prefix=<PREFIX>` system property. E.g. when the prefix is
- set to `cluster-config.` a consul key of `host:known/all` is mapped to `cluster-config.host:known/all`.
+* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped with a prefix.
+ This allows to let all values stored in consul have their own namespace. E.g. the Tamaya key `a.b` is mapped
+ to `foo.a.b`, when the prefix is set to `foo.`. The prefix can be activated by setting the
+ `tamaya.consul.prefix` system or environment property.
+
+
+=== The AbstractConsulPropertySource
+
+The +AbstractConsulPropertySource+ provides all features from +ConsulPropertySource+ but does not define how the
+property source is exactly configured, so you have full control.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions/mod_etcd.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_etcd.adoc b/content/documentation/extensions/mod_etcd.adoc
index 3003a09..536ff41 100644
--- a/content/documentation/extensions/mod_etcd.adoc
+++ b/content/documentation/extensions/mod_etcd.adoc
@@ -12,7 +12,7 @@ Tamaya _Etcd_ is an extension module. Refer to the link:../extensions.html[exten
=== What functionality this module provides ?
-Tamaya _Etcd_ provides different artifacts which allows using link:https://github.com/coreos/etcd[etcd] as a
+Tamaya _Etcd_ provides artifacts, which allow using link:https://github.com/coreos/etcd[etcd] as a
configuration backend. Basically the module adds a read-only property source (+EtcdPropertySource+). If
the _tamaya-mutable-config_ extension is loaded it is alos possible to write configuration
changes to _etcd_ using +MutableConfiguration+.
@@ -20,7 +20,7 @@ changes to _etcd_ using +MutableConfiguration+.
=== Compatibility
-The module is based on Java 7, so it will not run on Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -38,155 +38,32 @@ your module:
-----------------------------------------------
-=== The Extensions Provided
+=== The Functionality Provided
Tamaya's _etcd_ integration provides basically the following artifacts:
-* The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint
- root. The accessor basically provides a simple Java API for communicating with the _etcd_ server. The
- accessor hereby allows reading of single properties, or whole subtrees. Also the basic non
- atomic write methods are implemented.
-* The +org.apache.tamaya.etcd.EtcdPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name
- 'etcd', which is automatically registered.
-* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the etcd cluster,
- by accessing a +MutableConfiguration+ using the URI +config:etcd+.
-
-=== The EtcdAccessor
-
-The accessor implements the basic read and write API for communicating with an _etcd_ server.
-Hereby the accessor also provides _etcd_ specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+
-returned. Hereby the concept of _etcd_ is used where keys starting with an '_' represent meta-configuration
-that will be hidden from the overall properties map, being only directly/explicitly accessible:
-
-[source, java]
------------------------------------------------
-public class EtcdAccessor {
-
- /**
- * Creates a new instance with the basic access url.
- * @param server server url, e.g. {@code http://127.0.0.1:4001}.
- * @throws MalformedURLException
- */
- public EtcdAccessor(String server) throws MalformedURLException;
-
- /**
- * Get the etcd server version.
- * @return the etcd server version, never null.
- */
- public String getVersion();
-
- /**
- * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd:
- * <pre>
- * key=value
- * _key.source=[etcd]http://127.0.0.1:4001
- * _key.createdIndex=12
- * _key.modifiedIndex=34 // optional
- * _key.ttl=300 // optional
- * _key.expiration=... // optional
- * </pre>
- * @param key the requested key
- * @return the mapped result, including meta-entries.
- */
- public Map<String,String> get(String key);
-
- /**
- * Creates/updates an entry in etcd without any ttl set.
- * The response is as follows:
- * <pre>
- * key=value
- * _key.source=[etcd]http://127.0.0.1:4001
- * _key.createdIndex=12
- * _key.modifiedIndex=34 // optional
- * _key.prevNode.createdIndex=12 // optional
- * _key.prevNode.modifiedIndex=34 // optional
- * </pre>
- * @param key the property key, not null
- * @param value the value to be set
- * @return the result map as described above.
- */
- public Map<String,String> set(String key, String value);
-
- /**
- * Creates/updates an entry in etcd. The response is as follows:
- * <pre>
- * key=value
- * _key.source=[etcd]http://127.0.0.1:4001
- * _key.createdIndex=12
- * _key.modifiedIndex=34 // optional
- * _key.ttl=300 // optional
- * _key.expiry=... // optional
- * _key.prevNode.createdIndex=12 // optional
- * _key.prevNode.modifiedIndex=34 // optional
- * _key.prevNode.ttl=300 // optional
- * _key.prevNode.expiration=... // optional
- * </pre>
- * @param key the property key, not null
- * @param value the value to be set
- * @param ttlSeconds the ttl in seconds (optional)
- * @return the result map as described above.
- */
- public Map<String,String> set(String key, String value, Integer ttlSeconds);
-
-
- /**
- * Deletes a given key. The response is as follows:
- * <pre>
- * _key.source=[etcd]http://127.0.0.1:4001
- * _key.createdIndex=12
- * _key.modifiedIndex=34
- * _key.ttl=300 // optional
- * _key.expiry=... // optional
- * _key.prevNode.createdIndex=12 // optional
- * _key.prevNode.modifiedIndex=34 // optional
- * _key.prevNode.ttl=300 // optional
- * _key.prevNode.expiration=... // optional
- * _key.prevNode.value=... // optional
- * </pre>
- * @param key the key to be deleted.
- * @return the response mpas as described above.
- */
- public Map<String,String> delete(String key);
-
-
- /**
- * Access regular Tamaya properties map as follows:
- * <pre>
- * key1=myvalue
- * _key1.source=[etcd]http://127.0.0.1:4001
- * _key1.createdIndex=12
- * _key1.modifiedIndex=34 // optional
- * _key1.ttl=300 // optional
- * _key1.expiration=... // optional
- *
- * key2=myvaluexxx
- * _key2.source=[etcd]http://127.0.0.1:4001
- * _key2.createdIndex=12
- *
- * key3=val3
- * _key3.source=[etcd]http://127.0.0.1:4001
- * _key3.createdIndex=12
- * _key3.modifiedIndex=2
- * </pre>
- */
- public Map<String,String> getProperties(String directory, boolean recursive);
-
-}
------------------------------------------------
+* The +org.apache.tamaya.etcd.EtcdPropertySource+ is a ready-to-use +PropertySource+ with a default ordinal of 100 and
+ the name 'etcd'.
+* The +org.apache.tamaya.etcd.AbstractEtcdPropertySource+ is a abstract base +PropertySource+ you can use to
+ implement your own etcd propertysource.
=== The EtcdPropertySource
-The +EtcdPropertySource+ is automatically registered and allows to configure the _etcd_ servers to be used. This
-enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
-in microservice containers to connect with the according etcd cluster:
+The +EtcdPropertySource+ is a ready-to-use property source implementation for etcd. For use you must simply register it
+with the Java `ServiceLoader` od include it in a +PropertySourceProvider+. It provides:
-* The property source reads the +tamaya.etcd.server.urls+ system and environment property to evaluate possible etcd servers
- (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
+* a etcd based property source implementation.
+* configurable caching of key/values.
+* configuring a dedicated etcd directory ID to be used.
+* The property source reads the +tamaya.etcd.server+ system or environment property to evaluate the etcd servers
+ (comma separated). The API hereby just performs a Round-Robin through the list of
configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd
server can be established a warning will be logged, but deployment will not fail.
-* Additionally also the accessor allows to configure the socket/connection timeouts by setting
- +tamaya.etcd.timeout+ in seconds either as system or environment property.
-* The +EtcdPropertySource+ finally also allows the values read from the _etcd_ cluster to be mapped to prefixed
- context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is
- set to `cluster-config.` a etcd key of `host:known/all` is mapped to `cluster-config.host:known/all`.
+* Additionally with +tamaya.etcd.timeout+ system or environment property you can configure the connection timeout
+ in seconds.
+
+=== The AbstractEtcdPropertySource
+
+The +AbstractEtcdPropertySource+ is the base class used by +EtcdPropertySource+. Use it to implement your own custom
+etcd property source.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/8dd2accd/content/documentation/extensions/mod_hazelcast.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_hazelcast.adoc b/content/documentation/extensions/mod_hazelcast.adoc
index 13487a9..c8cecca 100644
--- a/content/documentation/extensions/mod_hazelcast.adoc
+++ b/content/documentation/extensions/mod_hazelcast.adoc
@@ -23,7 +23,7 @@ defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension mod
=== Compatibility
-The module is based on Java 7, so it will not run on Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -56,50 +56,15 @@ Access of consul key/value pairs is through the normal Tamaya API.
=== The HazelcastPropertySource
The +HazelcastPropertySource+ is not automatically registered and provides different options how to integrate
-Tamaya with Hazelcast.
+Tamaya with Hazelcast. It provides:
-[source, java]
------------------------------------------------
-/**
- * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and
- * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}.
- */
-public HazelcastPropertySource();
-
-/**
- * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and the
- * given hazelcast instance.
- * @param hazelcastInstance the hazelcast instance, not null.
- */
-public HazelcastPropertySource(HazelcastInstance hazelcastInstance);
-
-/**
- * Creates a new instance, hereby using the given property source name and
- * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}.
- * @param name the property source name, not null.
- */
-public HazelcastPropertySource(String name);
-
-/**
- * Creates a new instance, hereby using the given property source name and
- * a creating a new hazelcast backend using the given Hazelcast {@link Config}.
- * @param config the hazelcast config, not null.
- * @param name the property source name, not null.
- */
-public HazelcastPropertySource(String name, Config config);
-
-/**
- * Creates a new instance, hereby using the given property source name and the
- * hazelcast instance.
- * @param name
- * @param hazelcastInstance
- */
-public HazelcastPropertySource(String name, HazelcastInstance hazelcastInstance);
------------------------------------------------
+* a Hazelcast based property source implementation.
+* configurable caching of key/values.
+* configuraing a dedicated Hazelcast map ID to be used.
To use hazelcast as a configuration backend, you simply create the corresponding Hazelcast instance
-and use it to initialize the Tamaya property source. Given that a hazelcast backedn configuration
-can be easily created asillustrated below:
+and use it to initialize the Tamaya property source. Given that a hazelcast backend configuration
+can be easily created as illustrated below:
[source, java]
-----------------------------------------------
@@ -110,10 +75,16 @@ HazelcastPropertySource ps = new HazelcastPropertySource(hazelcastInstance);
ps.setName("myHazelcast-config");
ps.setOrdinal(2000);
// Build your own configuration context
-ConfigurationContextBuilder b = ConfigurationProvider.createNewConfigurationContextBuilder();
+ConfigurationBuilder b = Configuration.createConfigurationBuilder();
b.addDefaultPropertyConverters().addDefaultPropertyFilter().addDefaultPropertySources();
// Add the hazelcast property source (as most significant)
b.addPropertySource(ps);
// build and use the configuration
Configuration config = b.build();
-----------------------------------------------
+
+
+=== The AbstractHazelcastPropertySource
+
+The +AbstractHazelcastPropertySource+ is the baseclass used by +HazelcastPropertySource+. Use it to implement your own
+Hazelcast based property source.
\ No newline at end of file
[4/8] incubator-tamaya-site git commit: TAMAYA-274 Updated
documentation. TAMAYA-355 Updated documentation. TAMAYA-353 Updated
documentation.
Posted by an...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_collections.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_collections.adoc
index 93cc4be,93cc4be..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_collections.adoc
+++ /dev/null
@@@ -1,245 -1,245 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Collection Support
--
--toc::[]
--
--[[Collections]]
--== Tamaya Collections Support (Extension Module)
--
--Tamaya _Collections_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--All configuration in Tamaya is expressed as simple key, value pairs. Nevertheless this concept allows similarly
--the modelling of collection typed values such as lists, sets, maps or simple collections of things. The Tamaya
--Collections extension adds this functionality to the Tamaya eco-system.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use Tamaya collection support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-collections</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Overview
--
--Tamaya Collections adds +PropertyConverter+ implementations that are able to access configuration data
--as _lists, maps_ or _sets_. By default this works out of the box as easy as accessing any other type of
--configuration data, e.g.
--
--[source, java]
-------------------------------------------------
--Configuration config = ConfigurationProvider.getConfiguration();
--
--// Without any content specification, a list of String is returned.
--List<String> simpleList = config.get("my.list.config.entry", List.class);
--
--// Using a TypeLiteral allows to use every convertible sub type supported by the system.
--List<Integer> intList = config.get("my.list.config.entry", new TypeLiteral<List<Integer>>(){});
-------------------------------------------------
--
--Configuration in that case, by default, is a simple comma-separated list of entries, e.g.
--
--[source, properties]
-------------------------------------------------
--my.list.config.entry=1,34454,23,344545,3445
-------------------------------------------------
--
--Additionally the module allows adding additional meta-entries, which allows to tweak some of the
--inner-workings, e.g.
--
--* using your own +PropertyConverter+ implementation for parsing entries.
--* specifying a custom separator to split the items (default is {{','}}.
--* specifying a custom separator to split key/value pairs when parsing map entries.
--* specifying the implementation type of the collection item to be returned.
--* specifying the implementation type of the collection to be returned.
--
--
--=== Supported Types
--
--This module currently supports the following types:
--
--* +java.util.Collection+
--* +java.util.List+
--* +java.util.ArrayList+
--* +java.util.LinkedList+
--* +java.util.Set+
--* +java.util.SortedSet+
--* +java.util.TreeSet+
--* +java.util.HashSet+
--* +java.util.Map+
--* +java.util.SortedMap+
--* +java.util.HashMap+
--* +java.util.TreeMap+
--
--Hereby the collection type is determined by the parameter type accessed, e.g.
--+config.get("mylist", ArrayList.class)+ will always return an +ArrayList+
--as result.
--
--NOTE: This means that depending on your use case you can access different
--collection types based on the same configuration values, as long as their is
--a +PropertyConverter+ that can convert the _raw configuration value_ to the
--required target type.
--
--
--==== Configuring the target implementation type
--
--Tamaya Collections allows you to configure the _default_ target collection type by adding the
--following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part
--+java.util.+ can be ommitted:
--
--[ source, properties]
-------------------------------------------------
--mylist=a,b,c
--_mylist.collection-type=LinkedList
-------------------------------------------------
--
--When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect,
--so you will still get an +ArrayList+ as a result. However when you call +config.get("mylist",
--List.class)+ you will get a +LinkedList+ as implementation type.
--
--This mechanism similarly applies to all kind of collections, so you can use it similarly to define the implementation
--type returned when accessing +List+, +Map+ or +Collection+.
--
--
--=== Collecting Configuration Entries instead of Overriding
--
--By default Tamaya applies always an overriding +CombinationPolicy+, where only the configuration entry for
--the most significant configuration entry is used. In case of collections (and maybe also other use cases),
--overriding is not always the mechanism of choice. E.g. when you want to have all entries added to your
--configuration to be *combined* to a new entry containing all values provided by any property sources.
--
--Therefore _Tamaya Collections_ also provides a more sophistiated +CombinationPolicy+ (automatically configured)
--that allows to adapt the way how configuration entries are combined. All you must do is declaring
--the mechanism to be applied by an according _meta-configuration_ parameter, e.g. for +my.list+ your config may
--look as follows:
--
--[source, properties]
-------------------------------------------------
--# from PropertSource 1
--my.list=1,2,3
--
--# from PropertSource 2, with higher precedence
--my.list=4,5,6
--
--# without any additional meta-info these entries would be combined to
--my.list=4,5,6
-------------------------------------------------
--
--With Tamaya Collections you can now configure the combination policy as follows:
--
--[source, properties]
-------------------------------------------------
--# use one of the default policies: override / collect
--_my.list.combination-policy=collect
--
--# or use your own custom CombinationPolicy to combine the values
--_my.list.combination-policy=com.mycomp.app.MyCombincationPolicy
-------------------------------------------------
--
--So declaring the +collect+ policy the resulting raw output of the entry looks as follows:
--
--[source, properties]
-------------------------------------------------
--# result when applying the collect policy:
--my.list=1,2,3,4,5,6
-------------------------------------------------
--
--The customizable policy mechanism of Tamaya Collections also honors the +item-separator+ meta-configuration
--parameter explained later in this document.
--
--
--=== Format of Collection Configuration
--
--By default collections are modelled as simple String values, that are tokenized into individual parts using a
--defined +item-separator+ (by default +','+). So a given configuration entry of +1,2,3+ is mapped to +"1","2","3".
--If the target context type is something different than String the smae conversion logic is used as when mapping
--configuration parameters directly to non-String target types (implemented as +PropertyConverter+ classes, manahed
--within the current +ConfigurationContext+. The procedure is identical for all collection types, including +Map+ types,
--with the difference that each token in the list is parsed once more for separating it into a +key+ and a +value+.
--The default separator for map entries hereby is +"::"+. Map keys, as of now, are always of type +String+, whereas
--for values the same logic is applied as for non-map collection types.
--
--[source, properties]
-------------------------------------------------
--# a list, using the default format
--list=1,2,3,4,5,6
--
--# a map, using the default format
--map=a::b, c::d
-------------------------------------------------
--
--
--==== Trimming of entries
--
--By default all tokens parsed are trimmed _before_ adding them to the final collection. In case of map entries this is
--also the case for key/value entries. So the following configuration results in the identical values for
--+list1,list2+ and +map1,map2+:
--
--[source, properties]
-------------------------------------------------
--# a list, using the default format
--list1=1,2,3,4,5,6
--list2=1, 2, 3, 4, 5, 6
--
--# a map, using the default format
--map1=a::b, c::d
--map2=a :: b, c :: d
-------------------------------------------------
--
--Nevertheless truncation can be controlled by the usage of brackets, e.g. the last list or map entry will have a single
--space character as value:
--
--[source, properties]
-------------------------------------------------
--# a list, with a ' ' value at the end
--list3=1, 2, 3, 4, 5, [ ]
--
--# a map, with a ' ' value for key '0'
--map3=1 :: a, 2 :: b, 0::[ ]
-------------------------------------------------
--
--Hereby +\[+ escapes the sequence.
--
--
--==== Customizing the format
--
--The item and entry separators (by default +','+ and +"::"+) can be customized by setting corresponding meta-data
--entries as follows, resulting in the same values as in the prevoius listing:
--
--[source, properties]
-------------------------------------------------
--# a list, with a ' ' value at the end
--list3=1__2__3__ 4__ 5__[ ]
--_list3.item-separator=__
--
--# a map, with a ' ' value for key '0'
--map3=1->a, 2->b, 0->[ ]
--_map3.map-entry-separator=->
-------------------------------------------------
--
--Of course these settings also can be combined:
--
--[source, properties]
-------------------------------------------------
--# a reformatted map
--redefined-map=0==none | 1==single | 2==any
--_redefined-map.map-entry-separator===
--_redefined-map.item-separator=|
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_consul.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_consul.adoc
index 96c0b98,96c0b98..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_consul.adoc
+++ /dev/null
@@@ -1,66 -1,66 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration with consul (Hashicorp)
--
--toc::[]
--
--
--[[Consul]]
--== Integration with consul (Extension Module)
--
--Tamaya _Consul_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Consul_ provides different artifacts which allows use of
--link:http://www.consul.io[Consul from Hashicorp] as configuration backend. Basically the
--module supports read-only integration (as a +ConsulonfigSource+ as well
--as a writing configuration changes back (based on Tamaya's +MutableConfiguration+ API
--defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension module.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _tamaya-consul_ you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-consul</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Extensions Provided
--
--Consul integration comes basically with 2 artifacts:
--
--* The +org.apache.tamaya.etcd.ConsulConfigSource+ is a +ConfigSource+ with a default
-- ordinal of 100 and the name 'consul', which is automatically registered.
--* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
-- by accessing a +MutableConfiguration+ using the URI +config:consul+.
--
--Access of consul key/value pairs is through the normal Tamaya API.
--
--
--=== The ConsulConfigSource
--
--The +ConsulConfigSource+ is automatically registered and allows the consul servers to be used to be configured. This
--enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
--in microservice containers to connect with the according consul cluster:
--
--* The config source reads the +tamaya.consul.urls+ system and environment property to evaluate possible consul servers
-- (comma separated), which can be connected to. On failure the API just performs a Round-Robin through the list of
-- configured servers. Without any configuration +http://127.0.0.1:2400+ is used. If no connection to any consul
-- server can be established a warning will be logged, but deployment will not fail.
--* The +ConsulConfigSource+ finally also allows the values read from the consul cluster to be mapped to prefixed
-- context. This can be activated by setting the `-Dtamaya.consul.prefix=<PREFIX>` system property. E.g. when the prefix is
-- set to `cluster-config.` a consul key of `host:known/all` is mapped to `cluster-config.host:known/all`.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_etcd.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_etcd.adoc
index dac6ab7,dac6ab7..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_etcd.adoc
+++ /dev/null
@@@ -1,192 -1,192 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration with etcd (Core OS)
--
--toc::[]
--
--
--[[Etcd]]
--== Integration with etcd (Extension Module)
--Tamaya _Etcd_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Etcd_ provides different artifacts which allows using link:https://github.com/coreos/etcd[etcd] as a
--configuration backend. Basically the module adds a read-only property source (+EtcdConfigSource+). If
--the _tamaya-mutable-config_ extension is loaded it is alos possible to write configuration
--changes to _etcd_ using +MutableConfiguration+.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _etcd_ as a configuration backend you only must add the corresponding dependency to
--your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-etcd</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Extensions Provided
--
--Tamaya's _etcd_ integration provides basically the following artifacts:
--
--* The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint
-- root. The accessor basically provides a simple Java API for communicating with the _etcd_ server. The
-- accessor hereby allows reading of single properties, or whole subtrees. Also the basic non
-- atomic write methods are implemented.
--* The +org.apache.tamaya.etcd.EtcdConfigSource+ is a +ConfigSource+ with a default ordinal of 100 and the name
-- 'etcd', which is automatically registered.
--* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the etcd cluster,
-- by accessing a +MutableConfiguration+ using the URI +config:etcd+.
--
--=== The EtcdAccessor
--
--The accessor implements the basic read and write API for communicating with an _etcd_ server.
--Hereby the accessor also provides _etcd_ specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+
--returned. Hereby the concept of _etcd_ is used where keys starting with an '_' represent meta-configuration
--that will be hidden from the overall properties map, being only directly/explicitly accessible:
--
--[source, java]
-------------------------------------------------
--public class EtcdAccessor {
--
-- /**
-- * Creates a new instance with the basic access url.
-- * @param server server url, e.g. {@code http://127.0.0.1:4001}.
-- * @throws MalformedURLException
-- */
-- public EtcdAccessor(String server) throws MalformedURLException;
--
-- /**
-- * Get the etcd server version.
-- * @return the etcd server version, never null.
-- */
-- public String getVersion();
--
-- /**
-- * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd:
-- * <pre>
-- * key=value
-- * _key.source=[etcd]http://127.0.0.1:4001
-- * _key.createdIndex=12
-- * _key.modifiedIndex=34 // optional
-- * _key.ttl=300 // optional
-- * _key.expiration=... // optional
-- * </pre>
-- * @param key the requested key
-- * @return the mapped result, including meta-entries.
-- */
-- public Map<String,String> get(String key);
--
-- /**
-- * Creates/updates an entry in etcd without any ttl set.
-- * The response is as follows:
-- * <pre>
-- * key=value
-- * _key.source=[etcd]http://127.0.0.1:4001
-- * _key.createdIndex=12
-- * _key.modifiedIndex=34 // optional
-- * _key.prevNode.createdIndex=12 // optional
-- * _key.prevNode.modifiedIndex=34 // optional
-- * </pre>
-- * @param key the property key, not null
-- * @param value the value to be set
-- * @return the result map as described above.
-- */
-- public Map<String,String> set(String key, String value);
--
-- /**
-- * Creates/updates an entry in etcd. The response is as follows:
-- * <pre>
-- * key=value
-- * _key.source=[etcd]http://127.0.0.1:4001
-- * _key.createdIndex=12
-- * _key.modifiedIndex=34 // optional
-- * _key.ttl=300 // optional
-- * _key.expiry=... // optional
-- * _key.prevNode.createdIndex=12 // optional
-- * _key.prevNode.modifiedIndex=34 // optional
-- * _key.prevNode.ttl=300 // optional
-- * _key.prevNode.expiration=... // optional
-- * </pre>
-- * @param key the property key, not null
-- * @param value the value to be set
-- * @param ttlSeconds the ttl in seconds (optional)
-- * @return the result map as described above.
-- */
-- public Map<String,String> set(String key, String value, Integer ttlSeconds);
--
--
-- /**
-- * Deletes a given key. The response is as follows:
-- * <pre>
-- * _key.source=[etcd]http://127.0.0.1:4001
-- * _key.createdIndex=12
-- * _key.modifiedIndex=34
-- * _key.ttl=300 // optional
-- * _key.expiry=... // optional
-- * _key.prevNode.createdIndex=12 // optional
-- * _key.prevNode.modifiedIndex=34 // optional
-- * _key.prevNode.ttl=300 // optional
-- * _key.prevNode.expiration=... // optional
-- * _key.prevNode.value=... // optional
-- * </pre>
-- * @param key the key to be deleted.
-- * @return the response mpas as described above.
-- */
-- public Map<String,String> delete(String key);
--
--
-- /**
-- * Access regular Tamaya properties map as follows:
-- * <pre>
-- * key1=myvalue
-- * _key1.source=[etcd]http://127.0.0.1:4001
-- * _key1.createdIndex=12
-- * _key1.modifiedIndex=34 // optional
-- * _key1.ttl=300 // optional
-- * _key1.expiration=... // optional
-- *
-- * key2=myvaluexxx
-- * _key2.source=[etcd]http://127.0.0.1:4001
-- * _key2.createdIndex=12
-- *
-- * key3=val3
-- * _key3.source=[etcd]http://127.0.0.1:4001
-- * _key3.createdIndex=12
-- * _key3.modifiedIndex=2
-- * </pre>
-- */
-- public Map<String,String> getProperties(String directory, boolean recursive);
--
--}
-------------------------------------------------
--
--
--=== The EtcdConfigSource
--
--The +EtcdConfigSource+ is automatically registered and allows to configure the _etcd_ servers to be used. This
--enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
--in microservice containers to connect with the according etcd cluster:
--
--* The property source reads the +tamaya.etcd.server.urls+ system and environment property to evaluate possible etcd servers
-- (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
-- configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd
-- server can be established a warning will be logged, but deployment will not fail.
--* Additionally also the accessor allows to configure the socket/connection timeouts by setting
-- +tamaya.etcd.timeout+ in seconds either as system or environment property.
--* The +EtcdConfigSource+ finally also allows the values read from the _etcd_ cluster to be mapped to prefixed
-- context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is
-- set to `cluster-config.` a etcd key of `host:known/all` is mapped to `cluster-config.host:known/all`.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_events.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_events.adoc
index 9061d13,9061d13..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_events.adoc
+++ /dev/null
@@@ -1,308 -1,308 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Events
--
--toc::[]
--
--
--[[Events]]
--== Tamaya Events (Extension Module)
--
--Tamaya _Events_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Events_ provides a mechanism to publish and subscribe to +ConfigEvent<T>+ instances.
--This module implements +ConfigChange+ or +ConfigSourceChange+ as possible payloads, but
--the module itself is not constraint to this payload types.
--These payload types describe detected changes of key/values of a +Config+ or a +ConfigSource+.
--The extension also provides a _Singleton accessor_ which allows to register/unregister
--listeners for changes and the period, when configuration should be scanned for
--any changes.
--
--Summarizing with the events module you can easily observe configuration changes, record the
--state of any configuration and compare configuration states to create and publish related
--change events.
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--=== Installation
--
--To benefit from configuration event support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-events</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Core Architecture
--
--The core of the module are the +ConfigEventListener+ and the +ConfigEvent+ interfaces,
--which defines an abstraction for event handling and observation:
--
--[source,java]
--.ConfigEvent
----------------------------------------------
--public interface ConfigEvent<T> {
--
-- Class<T> getResourceType();
-- T getResource();
-- String getVersion();
-- long getTimestamp();
--}
--
--@FunctionalInterface
--public interface ConfigEventListener {
--
-- void onConfigEvent(ConfigEvent<?> event);
--
--}
----------------------------------------------
--
--Hereby the payload _T_ can be basically of an arbitrary type as long as
--it implements the +ConfigEvent+ interface. The next sections
--give more details on the the event types provided by this extension
--and their usage.
--
--Also the technology to be used for publishing these event types is adaptable.
--In SE the module uses a simple in-memory implementation based on the
--Google _Guava_ library. But users can replace this mechanism as needed. For
--more details refer to the SPI section later in this guide.
--
--
--=== The ConfigEventManager Singleton
--
--Main entry point of the events module is the +ConfigEventManager+ singleton class, which provides static accessor
--methods to the extension's functionality:
--
--* _Adding/removing_ of +ConfigChangeListener+ instances, either globally or per event type.
--* _Firing configuration events_ synchronously or asyncronously (mostly called by framework code).
--* _Configuring the monitor_ that periodically checks for changes on the global +Configuration+ provided
-- by +ConfigurationProvider.getConfiguration()+.
--
--[source,java]
---------------------------------------------------------
--public final class ConfigEventManager {
--
-- private ConfigEventManager() {}
--
-- public static void addListener(ConfigEventListener l);
-- public static <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
-- public static void removeListener(ConfigEventListener l);
-- public static <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
-- public static <T extends ConfigEvent>
-- Collection<? extends ConfigEventListener> getListeners();
-- public static <T extends ConfigEvent>
-- Collection<? extends ConfigEventListener> getListeners(Class<T> type);
--
-- public static <T> void fireEvent(ConfigEvent<?> event);
-- public static <T> void fireEventAsynch(ConfigEvent<?> event);
--
-- public static void enableChangeMonitoring(boolean enable);
-- public static boolean isChangeMonitoring();
-- public long getChangeMonitoringPeriod();
-- public void setChangeMonitoringPeriod(long millis);
--
--}
---------------------------------------------------------
--
--
--=== Modelling configuration changes as events
--
--This module provides a serializable and thread-safe abstraction modelling a
--configuration change, which is anything of the following
--
--* additional, _new_ configuration entries
--* _removed_ configuration entries
--* _changes_ on existing entries
--
--
--A collection of changes
--
--* on a +Config+ is modelled by the +ConfigChange+ class
--* on a +ConfigSource+ is modelled by the +ConfigSourceChange+ class
--
--
--==== Configuration Changes
--
--A set of changes on a +Config+ is described by a +ConfigChange+
--as follows:
--
--[source,java]
---------------------------------------------------------
--public final class ConfigChange implements ConfigEvent<Config>, Serializable{
--
-- public static ConfigChange emptyChangeSet(Config configuration);
--
-- @Override
-- public Config getResource();
-- @Override
-- public Class<Config> getResourceType();
-- @Override
-- public String getVersion();
-- @Override
-- public long getTimestamp();
--
-- // Event specific methods
--
-- public Collection<PropertyChangeEvent> getChanges();
-- public int getRemovedSize();
-- public int getAddedSize();
-- public int getUpdatedSize();
--
-- public boolean isKeyAffected(String key);
-- public boolean isRemoved(String key);
-- public boolean isAdded(String key);
-- public boolean isUpdated(String key);
-- public boolean containsKey(String key);
-- public boolean isEmpty();
--}
--
---------------------------------------------------------
--
--New instances of +ConfignChange+ hereby can be created using a
--fluent +ConfigChangeBuilder+:
--
--[source,java]
---------------------------------------------------------
--Config config = ...;
--ConfigChange change = ConfigChangeBuilder.of(config)
-- .addChange("MyKey", "newValue")
-- .removeKeys("myRemovedKey").build();
---------------------------------------------------------
--
--Also it is possible to directly compare 2 instances of +Config+,
--which results in a +ConfigChange+ that
--reflects the differences between the two configurations passed:
--
--[source,java]
--Comparing 2 configurations
---------------------------------------------------------
--Config config = ...;
--Config changedConfig = ...;
--ConfigChange change = ConfigChangeBuilder.of(config)
-- .addChanges(changedConfig).build();
---------------------------------------------------------
--
--So a +ConfigChange+ describes all the changes detected on a +Config+.
--This allows you to publish instances of this class as events to all registered
--listeners (observer pattern).
--For listening to +ConfigChange+ events you must implement the
--+ConfigEventListener+ functional interface:
--
--[source,java]
--.Implementing a ConfigChangeListener
---------------------------------------------------------
--public final class MyConfigChangeListener implements ConfigEventListener<ConfigChange>{
--
-- private Config config = ConfigProvider.getConfig();
--
-- public void onConfigEvent(ConfigEvent<?> event){
-- if(event.getResourceType()==Config.class){
-- if(event.getConfiguration()==config){
-- // do something
-- }
-- }
-- }
--
--}
---------------------------------------------------------
--
--You can *register* your implementation as illustrated below:
--
--. Manually by calling +ConfigEventManager.addListener(new MyConfigChangeListener())+
--. Automatically by registering your listener using the +ServiceLoader+ under
-- +META-INF/services/org.apache.tamaya.events.ConfigEventListener+
--
--Registering programmatically also allows you to define additional constraint,
--to filter out all kind of events you are not interested in.
--
--NOTE: By default detection of configuration changes is not enabled. To enable it, call
--+ConfigEventManager.enableChangeMonitoring(true)+.
--
--
--=== ConfigSource Changes
--
--Beside that a whole +Config+ changes, also a +ConfigSource+ can change,
--e.g. by a configuration file edited on the fly. This is similarly to a
--+ConfigChange+ reflected by the classes +ConfigSourceChange,
--ConfigSourceChangeBuilder+.
--
--
--==== Monitoring of configuration changes
--
--The +ConfigEventManager+ supports *active monitoring of the current configuration* to trigger corresponding change
--events to listeners registered. *This feature is deactivated by default*, but can be enabled by calling
--+ConfigEventManager.enableChangeMonitoring(true);+. This feature avoids regularly polling your local +Config+ for
--any kind of changes. If a change has been encountered Tamaya identifies it and triggers corresponding
--+ConfigChange+ events automatically.
--
--
--=== Freezing Configs and ConfigSources
--
--+Config+ instances as well as +ConfigSources+ are explicitly not required to be serializable. To enable easy
--serialization of these types a +Config+'s *current state can be frozen* (e.g. for later comparison with a newly
--loaded version). Freezing hereby means
--
--* all key/values are read-out by calling the +getProperties()+ method.
--* a meta data entry is added of the form +_frozenAt=223273777652325677+, whichdefines the UTC timestamp in
-- milliseconds when this instance was frozen.
--* if not already defined an +_id+ property will be added to the +Config+ containing the
-- identifier of the configuration.
--
--In code freezing is a no-brainer:
--
--[source,java]
--.Freezing the current Config
----------------------------------------------------
--Config config = ConfigProvider.getConfig();
--Config frozenConfig = FrozenConfig.of(config);
----------------------------------------------------
--
--... and similarly for a +ConfigSource+:
--
--[source,java]
--.Freezing a ConfigSource
----------------------------------------------------
--ConfigSource configSource = ...;
--ConfigSource frozenSource = FrozenConfigSource.of(configSource);
----------------------------------------------------
--
--
--
--=== SPIs
--
--This component also defines SPIs, which allows to adapt the implementation of the main +ConfigEventManager+
--singleton. This enables, for example, using external eventing systems, such as CDI, instead of the default provided
--simple SE based implementation. By default implementations must be registered using the current +ServiceContext+
--active (by default using the Java +ServiceLoader+ mechanism).
--
--[source,java]
--.SPI: ConfigEventSpi
----------------------------------------------------
--public interface ConfigEventManagerSpi {
--
-- <T> void addListener(ConfigEventListener l);
-- <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType);
-- void removeListener(ConfigEventListener l);
-- <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType);
-- Collection<? extends ConfigEventListener> getListeners();
-- Collection<? extends ConfigEventListener> getListeners(Class<? extends ConfigEvent> eventType);
--
-- void fireEvent(ConfigEvent<?> event);
-- void fireEventAsynch(ConfigEvent<?> event);
--
-- long getChangeMonitoringPeriod();
-- void setChangeMonitoringPeriod(long millis);
-- boolean isChangeMonitorActive();
-- void enableChangeMonitor(boolean enable);
--}
----------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_features.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_features.adoc
index 454cf48,454cf48..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_features.adoc
+++ /dev/null
@@@ -1,87 -1,87 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Features Check
--
--toc::[]
--
--
--[[Features]]
--== Tamaya Features Check (Extension Module)
--Tamaya _Features_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Features_ provides a simple +Features+ singleton that allows to check
--which Tamaya Extensions are currently on the classpath.
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use Tamaya _Features_ you only must add the corresponding dependency to
--your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-features</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Functionality Provided
--
--Main artifact is the +Features+ singleton, which provides various static methods
--to check, which Tamaya extensions are currently loaded.
--
--[source, java]
-------------------------------------------------
--public final class Features {
--
-- private Features(){}
--
-- public static boolean eventsAvailable();
-- public static boolean formatsAvailable();
-- public static boolean tamayaCoreAvailable();
-- public static boolean injectionAvailable();
-- public static boolean injectionCDIAvailable();
-- public static boolean mutableConfigAvailable();
-- public static boolean optionalAvailable();
-- public static boolean resolverAvailable();
-- public static boolean resourcesAvailable();
-- public static boolean spiSupportAvailable();
-- public static boolean filterSupportAvailable();
-- public static boolean springAvailable();
-- public static boolean jndiAvailable();
--
-- public static boolean extSpringCoreAvailable();
-- public static boolean extJndiAvailable();
-- public static boolean extOSGIAvailable();
--
-- public static boolean checkClassIsLoadable(String classname);
--}
-------------------------------------------------
--
--* +eventsAvailable();+ checks for the link:mod_events.html[_tamaya_events_] module.
--* +formatsAvailable();+ checks for the link:mod_formats.html[_tamaya_formats_] module.
--* +tamayaCoreAvailable();+ checks if the link:core.html[_Tamaya core_] implementation is loaded.
--* +injectionAvailable();+ checks for the link:mod_injection.html[_tamaya_injection_] SE module.
--* +injectionCDIAvailable();+ checks for the link:mod_cdi.html[_tamaya CDI_] modules.
--* +mutableConfigAvailable();+ checks for the link:mod_mutableconfig.html[_tamaya_mutableconfig_] module.
--* +optionalAvailable();+ checks for the link:mod_optional.html[_tamaya_optional_] module.
--* +resolverAvailable();+ checks for the link:mod_resolver.html[_tamaya_resolver_] module.
--* +resourcesAvailable();+ checks for the link:mod_reources.html[_tamaya_resources_] module.
--* +spiSupportAvailable();+ checks for the link:mod_spisupport.html[_tamaya_spisupport_] module.
--* +filterSupportAvailable();+ checks for the link:mod_filter.html[_tamaya_filter_] module.
--* +springAvailable();+ checks for the link:mod_spring.html[_tamaya_spring_] module.
--* +jndiAvailable();+ checks for the link:mod_jndi.html[_tamaya_jndi_] module.
--* +extJndiAvailable();+ checks if creation of a new `InitialContext` is successful.
--* +extSpringCoreAvailable();+ checks if Spring Core is on the classpath.
--* +extOSGIAvailable();+ checks the OSGI framework is on the classpath.
--* Finally +checkClassIsLoaded(String)+ tries to load a class. If it fails, `false` is returned.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_filter.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_filter.adoc
index 8de64d8,8de64d8..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_filter.adoc
+++ /dev/null
@@@ -1,117 -1,117 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: User Filtering
--
--toc::[]
--
--
--[[Filter]]
--== User Filtering (Extension Module)
--
--Tamaya _Filter_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Filter_ provides a simple singleton accessor that allows to explicitly add +Filter+ instances
--active on the current thread only. This can be very useful in many scenarios, especially within
--Java EE web filters or similar. Additionally this module adds
--standard filters that hide metadata entries when the full configuration map is accessed. When keys are accessed
--explicitily no filtering is applied and everything is visible.
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To benefit from filter support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-filter</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Extensions Provided
--
--Tamaya Filter comes basically with 3 artifacts:
--
--* The +org.apache.tamaya.filter.ConfigurationFilter+ provides several static methods to register +Filter+
--instances on the current thread:
--
--[source, java]
-------------------------------------------------
--public final class ConfigurationFilter implements Filter{
--
-- ...
--
-- /**
-- * Seactivates metadata filtering also on global map access for this thread.
-- * @see #clearFilters()
-- * @param active true,to enable metadata filtering (default).
-- */
-- public static void setFilterMetadata(boolean active);
--
-- /**
-- * Access the filtering configuration that is used for filtering single property values accessed.
-- * @return the filtering config, never null.
-- */
-- public static FilterContext getSingleFilterContext();
--
-- /**
-- * Access the filtering configuration that is used for filtering configuration properties accessed as full
-- * map.
-- * @return the filtering config, never null.
-- */
-- public static FilterContext getMapFilters();
--
-- /**
-- * Removes all programmable filters active on the current thread.
-- */
-- public static void clearFilters();
--
-- ...
--
--}
-------------------------------------------------
--
--For using regular expression when filtering configuration keys a corresponding implementation of a +PropertyFilter+
--is part of this module, So you can add a customized filter as follows:
--
--[source, java]
-------------------------------------------------
--try {
-- ConfigurationFilter.getMapFilters().addFilter(new myFilter());
--
-- // do your code with filtering active
--}
--finally {
-- // cleanup
-- ConfigurationFilter.clearFilters();
--}
-------------------------------------------------
--
--
--The +FilterChain+ is a simple compound structure combining multiple filters into one new (chained) filter:
--
--[source, java]
-------------------------------------------------
--public final class FilterChain implements Filter {
--
-- public void addFilter(Filter filter);
-- public void addFilter(int pos, Filter filter);
-- public Filter removeFilter(int pos);
-- public void clearFilters();
-- public void setFilters(Filter... filters);
-- public void setFilters(Collection<Filter> filters);
-- public List<Filter> getFilters();
--
--}
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_formats.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_formats.adoc
index fa7b1a5,fa7b1a5..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_formats.adoc
+++ /dev/null
@@@ -1,290 -1,290 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Formats
--
--toc::[]
--
--
--[[Formats]]
--== Tamaya Formats (Extension Module)
--
--Tamaya _Formats_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Formats_ provides an abstraction for configuration formats provding the following benefits:
--
--* Parsing of resources in can be implemented separately from interpreting the different aspects/parts parsed. As an
-- example a file format can define different sections. Depending on the company specific semantics of the sections
-- a different set of +ConfigSource+ instances must be created.
--* Similarly the configuration abstraction can also be used as an interface for integrating Tamaya with alternate
-- frameworks that provide logic for reading configuration files, such as Apache commons.configuration.
--
--=== Compatibility
--
--The module is based on Java 7, so it can be used with Java 7 and beyond.
--
--=== Installation
--
--To use the formats module you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-formats</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Basic Concept
--
--Formats should be reusable, meaning you should have to write a format parser only once and then be able to map the data read into whatever
--data structure (in our cases: property sources). So it is useful to separate concerns into
--
--* an arbitrary configuration format (textual or binary)
--* a parser (+ConfigurationFormat+) that transfers a given format into an intermediate
-- representation (+ConfigurationData+).
--* an optional customization, implemented by a _factory method pattern_ to adapt the mapping of +ConfigurationData+ read
-- to a collection of +ConfigSources+ (they can have different ordinal semantics).
--
--
--==== ConfigurationData
--
--Configuration formats can be very different. Some are simple key/value pairs, whereas other also consist of multiple sections (e.g. ini-files) or
--hierarchical data (e.g. yaml, xml). This is solved in Tamaya by mapping the configuration read into a normalized intermediary format called
--+ConfigurationData+:
--
--[source,java]
--.ConfigurationData
---------------------------------------------------------
--public final class ConfigurationData {
--
-- public ConfigurationFormat getFormat();
-- public String getResource();
--
-- public Set<String> getSectionNames();
-- public Map<String,String> getSection(String name);
--
-- public boolean hasDefaultProperties();
-- public Map<String,String> getDefaultProperties();
-- public Map<String,String> getCombinedProperties();
--
-- public boolean isEmpty();
--}
---------------------------------------------------------
--
--In detail the data read from a file is organized into _sections_ as follows:
--
--* with +getResource()+ and +getFormat()+ the underlying resource and the format that read this data can be accessed.
--* properties can be owned by
-- ** named sections
-- ** an (unnamed) default section
--* each section section contains a map of properties. Hereby the same key can be part of the default section and multiple
-- named sections, depending on the configuration format.
--* The method +getSectionNames()+ returns a set of all section names.
--* With +getSection(String name)+ a named section can be accessed.
--* With +getDefaultSection()+ the 'default' section can be accessed. This is a convenience method.
--* With +getCombinedProperties()+ a flattened entry map can be accessed built up (by default) out of
-- ** all entries from the default section, without any changes.
-- ** all entries from named sections, where the key for each entry is prefix with the section name and a '::' separator.
--* The configuration format used determines the mapping of configuration data read into this structure. The format
-- implementation can as well provide alternate implementations of how the data read should be mapped into the
-- combined properties map.
--
--
--==== ConfigurationFormat
--
--A ConfigurationFormat is basically an abstraction that reads a configuration resource (modelled by an InputStream) and
--creates a corresponding +ConfigurationData+ instance.
--
--[source,java]
---------------------------------------------------------
--public interface ConfigurationFormat {
--
-- String getName();
-- boolean accepts(URL url);
-- ConfigurationData readConfiguration(String resource, InputStream inputStream);
--}
---------------------------------------------------------
--
--=== Creating a default ConfigSource for a ConfigurationFormat
--
--The module defines a singleton +ConfigurationFormats+ which provides
--an easy to use API for creating +ConfigurationData+ and +ConfigSources+
--using abstract +ConfigurationFormat+ implementations:
--
--[source,java]
---------------------------------------------------------
--public final class ConfigurationFormats {
--
-- public static List<ConfigurationFormat> getFormats();
-- public static List<ConfigurationFormat> getFormats(String... formatNames);
-- public static List<ConfigurationFormat> getFormats(final URL url);
--
-- public static ConfigurationData readConfigurationData(final URL url)
-- throws IOException;
-- public static ConfigurationData readConfigurationData(URL url, ConfigurationFormat... formats)
-- throws IOException;
-- public static ConfigurationData readConfigurationData(URL url, Collection<ConfigurationFormat> formats)
-- throws IOException;
-- public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, ConfigurationFormat... formats);
-- public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, Collection<ConfigurationFormat> formats);
-- public static ConfigurationData readConfigurationData(String resource, InputStream inputStream,
-- ConfigurationFormat... formats)
-- throws IOException;
-- public static ConfigurationData readConfigurationData(String resource, InputStream inputStream,
-- Collection<ConfigurationFormat> formats)
-- throws IOException;
--
-- public static ConfigSource createConfigSource(URL url, ConfigurationFormat... formats)
-- throws IOException;
-- public static ConfigSource createConfigSource(URL url, Collection<ConfigurationFormat> formats)
-- throws IOException;
-- public static ConfigSource createConfigSource(String resource, InputStream inputStream,
-- ConfigurationFormat... formats);
-- public static ConfigSource createConfigSource(String resource, InputStream inputStream,
-- Collection<ConfigurationFormat> formats);
--}
---------------------------------------------------------
--
--* +getFormats()+ returns all registered formats.
--* +getFormats(String...)+ allows to access all formats with a given name.
--* +getFormats(URL url)+ allows to access all formats that declare that can optionally read an input from
-- a given `URL`.
--* +readConfigurationData(...)+ reads data from an input and creates a corresponding +ConfigurationData+,
-- either trying all known formats that declare its compatibility with the given input or the formats
-- passed explicitly.
--* +createConfigSource(...)+ allows to create a +ConfigSource+ reading a given input and the formats
-- to be used or known. Hereby a default property mapping is applied.
--
--So creating a +ConfigSource+ from a resource is basically a one liner:
--
--[source,java]
---------------------------------------------------------
--URL url = ...;
--ConfigSource configSource = ConfigurationFormats.createConfigSource(url);
--
--// constraining the formats to be used (assumption: json and yaml extensions are loaded)
--ConfigSource configSource = ConfigurationFormats.createConfigSource(
-- url,
-- ConfigurationFormats.getFormats("json", "yaml"));
---------------------------------------------------------
--
--
--=== Customize how ConfigurationData maps to ConfigSource
--
--For for the conversion of +ConfigurationData+ into a +ConfigSource+ different approaches can be useful:
--
--. The +ConfigurationFormat+ that reads the data can provides all properties read either as sectioned properties
-- or/and as default properties. The most simple cases is, where all properties have been added as 'default'
-- properties. In this case the default properties can be used as the property sources properties without any change.
--. If the format did also add section based properties, the combined properties returned can be used, hereby
-- replacing the '::' separator with a '.' separator.
--. In all other cases a custom mapping is useful, which can be acomplished by using the +MappedConfigurationDataConfigSource+
-- and overriding the +Map<String,String> populateData(ConfigurationData data)+ method.
--
--In most cases the usage of a +MappedConfigurationDataConfigSource+, is a good choice to start. This class
--provides a convenient default mapping and also allows to customized the mapping easily:
--
--[source,java]
---------------------------------------------------------
--ConfigurationData data = ...;
--MappedConfigurationDataConfigSource ps =
-- new MappedConfigurationDataConfigSource(data){
-- protected Map<String, String> populateData(ConfigurationData data) {
-- ...
-- }
-- };
---------------------------------------------------------
--
--Nevertheless, depending on the context, where a configuration source was read (classloader, time, source etc.) the
--resulting properties can have different semnatics, especially different priorities. Also section
--names may be mapped into different ordinals instead of using them as key prefixes (e.g. imagine configuration formats
--with a 'default', 'main', and 'overrides' sections). For such more complex or custom cases no simple mapping
--can be defined. Consequently the functionality mapping the normalized +ConfigurationData+ read to the
--appropriate collection of +ConfigSource+ instances must be implemented.
--
--For this scenario the +BaseFormatConfigSourceProvider+ can be used, defining the following mapping
--function that mus be implemented:
--
--[source,java]
---------------------------------------------------------
--/**
-- * Method to create a {@link org.apache.tamaya.spi.ConfigSource} based on the given entries read.
-- *
-- * @param data the configuration data, not null.
-- * @return the {@link org.apache.tamaya.spi.ConfigSource} instance ready to be registered.
-- */
--protected abstract Collection<ConfigSource> getConfigSources(ConfigurationData data);
---------------------------------------------------------
--
--When using Java 8 these mappings can be asily passed as parameters to the +createConfigSource+
--methods.
--
--
--=== Predefined formats
--
--The _formats_ module ships with 3 predefined formats:
--
--* `.ini` files, commonly known from Microsoft based systems, registered as `ini`.
--* `.properties` files, as defined by `java.util.Properties`, registered as `properties`.
--* `.xml` properties files, as defined by `java.util.Properties`, registered as `xml-properties`.
--
--
--==== ini Config File Mapping
--
--This module implements the ini file format with the class
--+org.apache.tamaya.format.formats.IniConfigurationFormat+.
--
--The default mapping is bext illustrated by a small example, so consider the
--following `.ini` file:
--
--[source,listing]
---------------------------------------------------------
--a=valA
--a.b=valB
--
--[section1]
--aa=sectionValA
--aa.b.c=SectionValC
--
--[section2]
--a=val2Section2
---------------------------------------------------------
--
--This file content by default is mapped to the following Tamaya properties:
--
--[source,listing]
---------------------------------------------------------
--a=valA
--a.b=valB
--section1::valA=sectionValA
--section1::a.b.c=SectionValC
--section2::a=val2Section2
---------------------------------------------------------
--
--Summarizing
--
--* entries without a section are mapped to the _default_ section.
--* entries with a section are mapped to a corresponding section, hereby everything between
-- the brackets is used as section name (trimmed).
--* section names are separated using a double colon (`::`).
--
--+ConfigurationData+ allows to access all the different parts:
--
--* the _default_ properties (a, a.b)
--* the section +section1+, with properties +aa, aa.b.c+
--* the section +section2+, with properties +a+
--
--
--==== XML Property and ordinary Property Files
--
--This module also ships with +ConfigurationFormat+ implementations that reuse the parsing
--functionality provided with +java.util.Properties+:
--
--* `org.apache.tamaya.format.formats.PropertiesFormat` uses `Properties.read(InputStream)`.
--* `org.apache.tamaya.format.formats.PropertiesXmlFormat` uses `Properties.readFromXml(InputStream)`.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_functions.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_functions.adoc
index bd52219,bd52219..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_functions.adoc
+++ /dev/null
@@@ -1,136 -1,136 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Functions
--
--toc::[]
--
--[[Functions]]
--== Tamaya Functions (Extension Module)
--
--Tamaya _Functions_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Functions_ provides several functional extensions using the +UnaryOperator<Config>,Function<Config, T>+ extension
--points. Most functional extension are accessible from the +ConfigurationFunctions+ singleton. Since the JSR API
--does not provide any functional extension points it is recommended to adapt the +Config+ instance into .+FunctionalConfig+.
--Then, when importing the functional methods statically they can very easily applied, e.g.
--
--[source,java]
---------------------------------------------------------------------
--import static org.apache.tamaya.functions.ConfigurationFunctions.*;
--
--FunctionalConfig fc = FunctionalConfig.of(ConfigProvider.getConfig());
--Set<String> sections = fc.with(areas("a", false).with(transitiveAreas());
---------------------------------------------------------------------
--
--The expression above returns all fully qualified section names that are child sections of the root section 'a'.
--So given the entries +a.b.entry1, a.b.entry2, a.a.entry3, a.b.c.entry4+ the reult would be +a, a.a, a.b, a.b.c+.
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--=== Installation
--
--For using the functionality shown in this document you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-functions</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== FunctionalConfig
--
--The +FunctionalConfig+ actually adds the functional extension points +with+ and +query+ to .+Config+ instance, which
--allow to chain expressions as seen in the introductionary snippet:
--
--[source, java]
-------------------------------------------------
--public interface FunctionalConfig extends Config, ConfigContextSupplier {
--
-- /**
-- * Enriches a {@link Config} instance with functional access points.
-- * @param config the config, not null
-- * @return a functional config instance.
-- */
-- static FunctionalConfig of(Config config){
-- ...
-- }
--
-- default FunctionalConfig with(UnaryOperator<Config> operator);
-- default <T> T query(Function<Config, T> query);
--}
-------------------------------------------------
--
--
--=== The Provided Functions
--
--==== Functions on +ConfigurationFunctions+
--
--The following sections explain the provided functions defined by +ConfigurationFunctions+ singleton.
--
--* *UnaryOperator<Config> filter(PropertyMatcher matcher)* creates a +UnaryOperator<Config>+ that creates a +Configuration+
-- containing only keys that are selected by the given _matcher predicate_. The +PropertyMatcher+ hereby allows to evaluate not only
-- the _key_, but also the _value_.
--* *UnaryOperator<Config> map(KeyMapper keyMapper)* creates a +UnaryOperator<Config>+ that maps the keys as defined
-- by the given _keyMapper_.
--* *UnaryOperator<Config> section(String section)* creates a +UnaryOperator<Config>+ that creates a +Configuration+ containing only
-- entries that are direct or indirect members of the given section.
--* *UnaryOperator<Config> section(String areaKey, boolean stripKeys)* creates a +UnaryOperator<Config>+ that creates a +Configuration+
-- containing only entries that are direct or indirect members of the given section. Hereby _stripKeys_ allows to determine
-- if the returned entries should be relative to the search criteria {{stripKeys=true}} or absolute keys.
--* *isKeyInSection(String section, String sectionKey)* allows to easily determine if a given _key_ is a direct or indirect member
-- of a given section.
--* *boolean isKeyInSections(String key, String... sectionKeys)* allows to easily determine if one key of given
-- _key_ is a direct or indirect member of at least one of the given _sectionKeys_.
--* *Function<Config,Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that
-- also have parameters present).
--* *Function<Config,Set<String>> transitiveSections()* allows to query all the contained fully qualified section names,
-- including the transitive closure of sections.
--* *Function<Config,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
-- qualified section names that are selected by the given _predicate_.
--* *Function<Config,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
-- qualified section names that are selected by the given _predicate_, including the transitive closure of sections
-- identified.
--* *UnaryOperator<Config> sectionsRecursive(String... sectionKeys)* provides a +UnaryOperator<Config>+ that filters all sections identified
-- by the given _sectionKeys_ and its child sections.
--* *UnaryOperator<Config> sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +UnaryOperator<Config>+
-- that filters all sections identified by the given _sectionKeys_ and its child sections. _stripKeys_ allows to
-- determine if the resulting configuration should be relative to the selected areas ({{stripKeys=true}}) or
-- absolute (filtering only).
--* *Function<Config,String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+
-- representation.
--
--
--==== Functions on +ConfigSourceFunctions+
--
--The following sections explain the provided functions defined by +ConfigSourceFunctions+ singleton.
--
--* *ConfigSource addMetaData(ConfigSource propertySource, Map<String,String> metaData)* Creates a new +ConfigSource+
-- with the given metadata added.
--* *boolean isKeyInSection(String key, String sectionKey)* Checks if the given _key_ is a direct or indirect member of
-- one of the given _sectionKey_.
--* *boolean isKeyInSections(String key, String... sectionKeys)* Checks if the given _key_ is a direct or indirect member of
-- one of one of the given _sectionKeys_.
--* *Set<String> sections(Map<String, String> properties)* Extracts the sections from the given properties.
--* *Set<String> transitiveSections(Map<String, String> properties)* Extracts the transitive sections from the given
-- properties.
--* *Set<String> sections(Map<String, String> properties, final Predicate<String> predicate)* Extracts the sections
-- from the given properties, also filtering with the given predicate.
--* *Set<String> transitiveSections(Map<String, String> properties, Predicate<String> predicate)* Extracts the transitive
-- sections from the given properties, also filtering with the given predicate.
--* *Map<String,String> sectionsRecursive(Map<String, String> properties, String... sectionKeys)* Creates w +ConfigSource+
-- only containing the sections that a direct or indirect children of the given _sectionKeys_.
--* *Map<String,String> sectionRecursive(Map<String, String> properties, boolean stripKeys, String... sectionKeys)* Creates w +ConfigSource+
-- only containing the sections that a direct or indirect children of the given _sectionKeys_. With _stripKeys_ one can
-- select of the returned values should be relative to its selection of be fully qualified.
--* *String stripSectionKeys(String key, String... sectionKeys)* This function strips away the matching section key as given
-- in _sectionKeys_ from a given _key_.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_hazelcast.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_hazelcast.adoc
index e17aad6,e17aad6..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_hazelcast.adoc
+++ /dev/null
@@@ -1,118 -1,118 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration with Hazelcast
--
--toc::[]
--
--
--[[Consul]]
--== Integration with Hazelcast (Extension Module)
--
--Tamaya _Hazelcast_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Hazelcast_ provides a property source which uses
--link:http://www.hazelcast.org[Hazelcast] as configuration backend. Hereby the
--module supports read-only integration (as a +HazelcastConfigSource+ as well
--as a writing configuration changes back (based on Tamaya's +MutableConfiguration+ API
--defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension module.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _tamaya-hazelcast_ you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-hazelcast</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Extensions Provided
--
--Hazelcast integration comes basically with 2 artifacts:
--
--* The +org.apache.tamaya.hazelcast.HazelcastConfigSource+ is a +ConfigSource+. The property source is not automatically
-- registered. Either register it using the _ServiceLoader_ yourself or implement
-- and register a corresponding `ConfigSourceProvider`.
--* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
-- by accessing a +MutableConfiguration+ using the URI +config:hazelcast+.
--
--Access of consul key/value pairs is through the normal Tamaya API.
--
--
--=== The HazelcastConfigSource
--
--The +HazelcastConfigSource+ is not automatically registered and provides different options how to integrate
--Tamaya with Hazelcast.
--
--[source, java]
-------------------------------------------------
--/**
-- * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and
-- * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}.
-- */
--public HazelcastConfigSource();
--
--/**
-- * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and the
-- * given hazelcast instance.
-- * @param hazelcastInstance the hazelcast instance, not null.
-- */
--public HazelcastConfigSource(HazelcastInstance hazelcastInstance);
--
--/**
-- * Creates a new instance, hereby using the given property source name and
-- * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}.
-- * @param name the property source name, not null.
-- */
--public HazelcastConfigSource(String name);
--
--/**
-- * Creates a new instance, hereby using the given property source name and
-- * a creating a new hazelcast backend using the given Hazelcast {@link Config}.
-- * @param config the hazelcast config, not null.
-- * @param name the property source name, not null.
-- */
--public HazelcastConfigSource(String name, Config config);
--
--/**
-- * Creates a new instance, hereby using the given property source name and the
-- * hazelcast instance.
-- * @param name
-- * @param hazelcastInstance
-- */
--public HazelcastConfigSource(String name, HazelcastInstance hazelcastInstance);
-------------------------------------------------
--
--To use hazelcast as a configuration backend, you simply create the corresponding Hazelcast instance
--and use it to initialize the Tamaya property source. Given that a hazelcast backedn configuration
--can be easily created asillustrated below:
--
--[source, java]
-------------------------------------------------
--// define config settings
--HazelcastInstance hazelcastInstance = Hazelcast.newInstance(hazelcastConfig);
--HazelcastConfigSource cs = new HazelcastConfigSource(hazelcastInstance);
--cs.setName("myHazelcast-config");
--cs.setOrdinal(2000);
--// Build your own configuration
--ConfigBuilder b = ConfigProviderResolver.getInstance().getBuilder();
--b.addDiscoveredConverters().addDefaultSources().addDiscoveredSources();
--// Add the hazelcast property source (as most significant)
--b.awithSource(cs);
--// build and use the configuration
--Config config = b.build();
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_injection.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_injection.adoc
index 831e098,831e098..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_injection.adoc
+++ /dev/null
@@@ -1,481 -1,481 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Injection
--
--toc::[]
--
--
--[[Injection]]
--== Tamaya Injection (Extension Module)
--
--Tamaya _Injection_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Injection_ provides functionality for injecting configured values into beans, or creating configuration
--template instances.
--
--Inversion of Control (aka IoC/Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate
--code. In Java there are different frameworks available that all provide IoC mechanisms. Unfortunately IoC is not a
--built-in language feature. So for a portable solution that works also in Java SE Tamaya itself has to provide the
--according injection services. This module adds this functionality to Tamaya.
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--=== Installation
--
--The basic injection API is defined by the configuration JSRßs API. Nevertheless Tamaya's adds some
--useful extensions. These extensions are deployed as optional API artifact:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-injection-api</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--To use injection with Java SE you must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-injection</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--Similarly there are other injection implementations available, targetig platforms such as
--
--* link:mod_spring.html[Spring, Spring Boot]
--* link:mod_CDI.html[Java EE/CDI]
--
--
--=== Core Concepts
--
--Basically you annotate fields or methods in your beans with +@ConfigProperty+ to enable configuration injection. Tamaya
--additionally defines further annotations that allo you to define additional aspects such as default values, custom
--converters etc. The following example illustrates the basic functionality:
--code snippet:
--
--[source,java]
--.Annotated Example Class
----------------------------------------------
--package foo.bar;
--
--public class ConfiguredClass {
--
-- // resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty
-- private String testProperty;
--
-- // Trying to resolve mutiple keys, with a default value, if none could be resolved
-- @ConfigProperty(key="a.b.c.key1", defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
-- @ConfigFaööbackKeys({"a.b.legacyKey",area1.key2"})
-- String value1;
--
-- // Typical case
-- @ConfigProperty(key="a.b.c.key2")
-- private int value2;
--
-- // resolved by default as foo.bar.ConfiguredClass.accessUrl
-- // Using a (default) String -> URL converter
-- @ConfigProperty(defaultValue="http://127.0.0.1:8080/res/api/v1/info.json")
-- private URL accessUrl;
--
-- // Config injection disabled for this property
-- @NoConfig
-- private Integer int1;
--
-- // Overriding the String -> BigDecimal converter with a custom implementation.
-- @ConfigProperty(key="BD")
-- @WithConverter(MyBigDecimalRoundingAdapter.class)
-- private BigDecimal bigNumber;
--
-- ...
--}
----------------------------------------------
--
--
--When configuring data or configuration classes it is also possible to auto-inject the fields identified. For activating
--this feature a class must be annotated with +@ConfigAutoDetect+:
--
--[source, java]
--.An autoinjected bean class
----------------------------------------------
--package a.b;
--
--@ConfigAutoDetect
--public final class Tenant {
-- private int id;
-- private String name;
-- private String description;
-- @NoConfig // prevents auto detection for this field
-- private String id2;
--
-- public int getId(){
-- return id;
-- }
-- public String getName(){
-- return name;
-- }
-- public String getDescription(){
-- return description;
-- }
--}
----------------------------------------------
--
--These examples do not show all possibilities provided. Configuring instance of these
--class using Tamaya is very simple: Just pass the instance to Tamaya to let
--Tamaya inject the configuration:
--
--[source,java]
--.Configuring the +ConfiguredClass+ Instance
----------------------------------------------
--ConfiguredClass classInstance = new ConfiguredClass();
--ConfigurationInjector.configure(configuredClass);
--
--Tenant tenant = new Tenant();
--ConfigurationInjector.configure(tenant);
----------------------------------------------
--
--NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used
--with CDI, Spring or within an OSGI container. For further details refer also to the corresponding integration module's
--documentation.
--
--
--==== The ConfigurationInjector
--
--The +ConfigurationInjector+ interface provides methods that allow any kind of instances to be configured
--by passing the instances to +T ConfigurationInjector.getInstance().configure(T);+. The classes passed
--hereby must not be annotated with +@ConfigProperty+ for being configurable.
--
--
--==== Accessing Supplier instances
--
--In many cases you want to create a supplier that simply creates instances that are correctly configured as defined
--by the current context. This can be done using +Suppliers+:
--
--[source, java]
----------------------------------------------
--Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
-- new Supplier<Tenant>(){
-- public Tenant get(){
-- return new Tenant();
-- }
--});
----------------------------------------------
--
--With Java 8 it's even more simple:
--
--[source, java]
----------------------------------------------
--Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
-- Tenant::new);
----------------------------------------------
--
--Hereby this annotation can be used in multiple ways and combined with other annotations such as
--+@WithLoadPolicy+, +@WithConverter+.
--
--
--==== Minimal Example
--
--To illustrate the mechanism below the most simple variant of a configured class is given:
--
--[source,java]
--.Most simple configured class
----------------------------------------------
--pubic class ConfiguredItem{
-- @Config
-- private String aValue;
--}
----------------------------------------------
--
--When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+,
--the following is happening:
--
--* The current valid +Config+ is evaluated by calling +Config cfg = ConfigProvider.getConfig();+
--* The current property value (String) is evaluated by calling +cfg.getValue("aValue", Type.class);+
-- for each possible key (mutliple keys are possible).
--* if not successful, an error is thrown
--* On success, since no type conversion is involved, the value is injected.
--
--
--=== The Annotations in detail
--
--==== Using `@ConfigProperty`
--
--This is the main JSR annotation targeting a field in a class for configuration injection.
--
--
--===== Evaluating of _configuration keys_
--
--By default Tamaya tries to determine configuration for each property of an instance
--passed, using the following resolution policy:
--
--* Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the
-- following keys:
--
--[source, listing]
----------------------------------------------
--a.b.MyClass.myField
--a.b.MyClass.my-field
--MyClass.myField
--MyClass.my-field
--myField
--my-field
----------------------------------------------
--
--
--This behaviour can be adapted, e.g. by using the `@ConfigDefaultSections` annotation on the
--declaring type:
--
----------------------------------------------
--@ConfigDefaultSections("a.b.c", "deprecated")
--pubic class MyClass{
-- @ConfigProperty
-- private String myField;
--}
----------------------------------------------
--
--This will result in a modified lookup chain as illustrated below:
--
--[source, listing]
----------------------------------------------
--a.b.c.myField
--a.b.c.my-field
--deprecated.myField
--deprecated.my-field
----------------------------------------------
--
--This helps to reduce redundancy when referring to you configuration keys. Additionally
--it is also possible to define absolute key entries, e.g.
--
----------------------------------------------
--@ConfigDefaultSections("a.b.c")
--pubic class MyClass{
-- @ConfigProperty("myField" /* relative */)
-- @ConfigFallbackKeys("[absolute.key]")
-- private String myField;
--}
----------------------------------------------
--
--This will result in a lookup chain as illustrated below:
--
--[source, listing]
----------------------------------------------
--a.b.c.myField
--absolute.key # default sections are ignored
----------------------------------------------
--
--
--===== Using defaults
--
--In the next example we explicitly define the _default_ property value:
--[source,java]
----------------------------------------------
--pubic class ConfiguredItem{
--
-- @ConfigProperty(key="aValue", defaultValue="${env:java.version}")
-- @ConfigFallbackKeys({"a.b.value","a.b.deprecated.value"})
-- private String aValue;
--}
----------------------------------------------
--
--
--==== Automatically inject all items using `@ConfigAutoInject`
--
--Using `@ConfigAutoDetect` allows you to automatically select all properties found for
--configuration injection:
--
--[source,java]
----------------------------------------------
--@ConfigAutoDetect
--pubic class ConfiguredItem{
--
-- private transient int sum;
--
-- private String a;
-- private String b;
-- Private String c;
--}
----------------------------------------------
--
--Adding the `@NoConfig` annotation prevents a field or method to be auto-detected from
--configuration. This is especially useful, if a type is annotated as @ConfigAutoDetect with auto-confiuration
--turned on as follows:
--
--[source,java]
----------------------------------------------
--@NoConfig
--private transient int sum;
----------------------------------------------
--
--In this case the fields +a,b,c+ are configured, whereas the field +sum+ is ignored regarding
--configuration.
--
--
--==== Adding custom property converters using `@WithConverter`
--
--The @WithConverter annotation allows you to define a class of type +Converter+, to be applied
--on a property configured to convert the String value to the expected injected type. This can be used for
--various use cases, e.g. adding custom formats, config models, decryption.
--
--[source,java]
----------------------------------------------
--
--pubic class ConfiguredItem{
--
-- @WithConverter(MyPropertyConverter.class)
-- @ConfigProperty
-- private String a;
--
--}
----------------------------------------------
--
--
--==== Inject a `DynamicValue`
--
--Within this example we evaluate a dynamic value. This mechanism allows you to listen for configuration changes and to
--commit new values exactly, when convenient for you.
--
--[source,java]
----------------------------------------------
--pubic class ConfiguredItem{
--
-- @ConfigProperty(key="aValue", defaultValue="${env:java.version}")
-- private DynamicValue aValue;
--}
----------------------------------------------
--
--The +DynamicValue+ provides you the following functionality:
--
--[source,java]
----------------------------------------------
--public interface DynamicValue<T> {
--
-- T get();
-- T getNewValue();
-- T evaluateValue();
-- T commitAndGet();
-- void commit();
-- void discard();
-- boolean updateValue();
--
-- void setUpdatePolicy(UpdatePolicy updatePolicy);
-- UpdatePolicy getUpdatePolicy();
-- void addListener(PropertyChangeListener l);
-- void removeListener(PropertyChangeListener l);
--
-- boolean isPresent();
-- T orElse(T other);
-- // Enabled with Java 8
-- // T orElseGet(ConfiguredItemSupplier<? extends T> other);
-- // <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X;
--
--}
--
--public enum UpdatePolicy{
-- IMMEDIATE,
-- EXPLCIT,
-- NEVER,
-- LOG_AND_DISCARD
--}
----------------------------------------------
--
--//Summarizing +DynamicValue+ looks somehow similar to the new +Optional+ class added with Java 8. It provides
--//a wrapper class around a configured instance. Additionally this class provides functionality that gives
--//active control, to manage a configured value based on a ++LoadingPolicy+:
--//
--//* +IMMEDEATE+ means that when the configuration system detects a change on the underlying value, the new value
--// is automatically applied without any further notice.
--//* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+ property. if +getNewValue()+
--// returns a non null value, the new value can be applied by calling +commit()+. You can always access the newest value,
--// hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible ti ignore a change by calling
--// +discard()+.
--//* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded.
--//* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.
--
--Summarizing a +DynamicValue+ allows you
--
--* to reload actively updates of configured values.
--* update implicitly or explicitly all changes on the value.
--* add listeners that observe changes of a certain value.
--
--Dynamic values also allow on-the-fly reevaluation of the value by calling +evaluateValue()+. Hereby the value of the
--instance is not changed.
--
--
--===== The LoadPolicy enum
--
--The +LoadPolicy+ enum defines different configuration loading behaviour
--to be applied:
--
--[source,java]
----------------------------------------------
--@Deprecated
--public enum LoadPolicy {
-- /**
-- * The configuration keys is evaluated once, when the owning component is loaded/configured, but never updated later.
-- */
-- INITIAL,
-- /**
-- * The configuration keys is evaluated exactly once on its first access/use lazily, but never updated later.
-- * @see DynamicValue#get()
-- * @see DynamicValue#commitAndGet()
-- */
-- LAZY,
-- /**
-- * The configuration value is evaluated every time it is accessed.
-- */
-- ALWAYS
--}
----------------------------------------------
--
--This enum type currently is used only internally, so avoid using it as of
--now in your code is recommended.
--
--
--=== Configuration Events
--
--Similar to CDI Tamaya publishes Configuration events, when instances were configured. It depends on the effective
--event backend in use, if and how events are published:
--
--* when you have the CDI extension active events are published using the default CDI event mechanism.
--* in all other scenarios events are delegated to the +tamaya-events+ module, if available,
--* if no event delegation is available no events are published.
--
--The event published is very simple:
--
--[source,java]
----------------------------------------------
--public interface ConfiguredType {
-- Class getType();
-- String getName();
-- Collection<ConfiguredField> getConfiguredFields();
-- Collection<ConfiguredMethod> getConfiguredMethods();
-- void configure(Object instance, Configuration config);
--}
--
--public interface ConfiguredField {
-- Class<?> getType();
-- Collection<String> getConfiguredKeys();
-- String getName();
-- String getSignature();
-- Field getAnnotatedField();
-- void configure(Object instance, Configuration config);
--}
--
--public interface ConfiguredMethod {
-- Collection<String> getConfiguredKeys();
-- Class<?>[] getParameterTypes();
-- Method getAnnotatedMethod();
-- String getName();
-- String getSignature();
-- void configure(Object instance, Configuration config);
--}
------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_jndi.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_jndi.adoc
index a167e9e,a167e9e..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_jndi.adoc
+++ /dev/null
@@@ -1,68 -1,68 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Integration with JNDI
--
--toc::[]
--
--
--[[JNDI]]
--== Integration with JNDI (Extension Module)
--Tamaya _JNDI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _JNDI_ provides a simple +ConfigySource+ that reads values from a
--JNDI context.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _jndi_ as a configuration backend you only must add the corresponding dependency to
--your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-jndi</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The Functionality Provided
--
--Main artifact is the +JNDIConfigSource+ class, which implements a
--property source based on a JNDI context:
--
--[source, java]
-------------------------------------------------
--public class JNDIPropertySource extends BasePropertySource {
--
-- public JNDIPropertySource(String name, Context context);
-- public JNDIPropertySource(String name) throws NamingException;
-- public JNDIPropertySource() throws NamingException;
--
-- public void setScannable(boolean scannable);
--
-- [...]
--}
-------------------------------------------------
--
--By default the property source is _non scannable_, so a call the `getProperties()`
--will return an empty map instance. After calling `setScannable(true);` a call to
--`getProperties()` will return a String representation of the JNDI tree. Hereby
--leaves of the tree are converted using `String.valueOf(leaveObject)`.
--
--This module automatically registers an instance of +JNDIConfigSource+ with a
--default ordinal of +200+.
--
--You can extend this class or manually instantiate it, e.g. as part of a
--+ConfigSourceProvider+. If no `Context` is passed explicitly, a new
--+InitialContext+ is created, without any environment parameters set.
[6/8] incubator-tamaya-site git commit: TAMAYA-274 Some minor
additions. TAMAYA-353 Some minor additions.
Posted by an...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_injection.adoc b/content/documentation/extensions/mod_injection.adoc
index 97508db..3074a5d 100644
--- a/content/documentation/extensions/mod_injection.adoc
+++ b/content/documentation/extensions/mod_injection.adoc
@@ -134,10 +134,10 @@ Tamaya inject the configuration (or throw a +ConfigException+, if this is not po
.Configuring the +ConfiguredClass+ Instance
--------------------------------------------
ConfiguredClass classInstance = new ConfiguredClass();
-ConfigurationInjector.configure(configuredClass);
+ConfigurationInjector.getInstance().configure(configuredClass);
Tenant tenant = new Tenant();
-ConfigurationInjector.configure(tenant);
+ConfigurationInjector.getInstance().configure(tenant);
--------------------------------------------
NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used
@@ -194,7 +194,7 @@ pubic class ConfiguredItem{
When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+,
the following is happening:
-* The current valid +Configuration+ is evaluated by calling +Configuration cfg = ConfigurationProvider.getConfiguration();+
+* The current valid +Configuration+ is evaluated by calling +Configuration cfg = Configuration.current();+
* The current property value (String) is evaluated by calling +cfg.get("aValue");+ for each possible key (mutliple
keys are possible).
* if not successful, an error is thrown (+ConfigException+)
@@ -385,32 +385,31 @@ public interface DynamicValue<T> {
boolean isPresent();
T orElse(T other);
- // Enabled with Java 8
- // T orElseGet(ConfiguredItemSupplier<? extends T> other);
- // <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X;
+ T orElseGet(ConfiguredItemSupplier<? extends T> other);
+ <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X;
}
public enum UpdatePolicy{
IMMEDIATE,
- EXPLCIT,
+ EXPLICIT,
NEVER,
LOG_AND_DISCARD
}
--------------------------------------------
-//Summarizing +DynamicValue+ looks somehow similar to the new +Optional+ class added with Java 8. It provides
-//a wrapper class around a configured instance. Additionally this class provides functionality that gives
-//active control, to manage a configured value based on a ++LoadingPolicy+:
-//
-//* +IMMEDEATE+ means that when the configuration system detects a change on the underlying value, the new value
-// is automatically applied without any further notice.
-//* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+ property. if +getNewValue()+
-// returns a non null value, the new value can be applied by calling +commit()+. You can always access the newest value,
-// hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible ti ignore a change by calling
-// +discard()+.
-//* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded.
-//* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.
+Summarizing +DynamicValue+ looks somehow similar to the new +Optional+ class added with Java 8. It provides
+a wrapper class around a configured instance. Additionally this class provides functionality that gives
+active control, to manage a configured value based on a ++LoadingPolicy+:
+
+* +IMMEDIATE+ means that when the configuration system detects a change on the underlying value, the new value
+ is automatically applied without any further notice.
+* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+ property. if +getNewValue()+
+ returns a non null value, the new value can be applied by calling +commit()+. You can always access the newest value,
+ hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible ti ignore a change by calling
+ +discard()+.
+* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded.
+* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.
Summarizing a +DynamicValue+ allows you
@@ -422,35 +421,6 @@ Dynamic values also allow on-the-fly reevaluation of the value by calling +evalu
instance is not changed.
-===== The Loading policy enum
-
-The +LoadPolicy+ enum defines different configuration loading behaviour
-to be applied:
-
-[source,java]
---------------------------------------------
-@Deprecated
-public enum LoadPolicy {
- /**
- * The configuration keys is evaluated once, when the owning component is loaded/configured, but never updated later.
- */
- INITIAL,
- /**
- * The configuration keys is evaluated exactly once on its first access/use lazily, but never updated later.
- * @see DynamicValue#get()
- * @see DynamicValue#commitAndGet()
- */
- LAZY,
- /**
- * The configuration value is evaluated every time it is accessed.
- */
- ALWAYS
-}
---------------------------------------------
-
-This enum type currently is used only internally, so avoid using it as of
-now in your code is recommended.
-
=== Configuration Events
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_jndi.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_jndi.adoc b/content/documentation/extensions/mod_jndi.adoc
index c3f12f8..74b98bc 100644
--- a/content/documentation/extensions/mod_jndi.adoc
+++ b/content/documentation/extensions/mod_jndi.adoc
@@ -18,7 +18,7 @@ JNDI context.
=== Compatibility
-The module is based on Java 7, so it will not run on Java 7 and beyond.
+The module is based on Java 8.
=== Installation
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_jodatime.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_jodatime.adoc b/content/documentation/extensions/mod_jodatime.adoc
index a49fa7b..13d5035 100644
--- a/content/documentation/extensions/mod_jodatime.adoc
+++ b/content/documentation/extensions/mod_jodatime.adoc
@@ -38,7 +38,7 @@ Joda-Time based values directly from a given configuration.
[source,java]
-----------------------------------------------
-Configuration configuration = ConfigurationProvider.getConfiguration();
+Configuration configuration = Configuration.current();
DateTime pit = configuration.get("pointInTime", DateTime.class)
-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_json.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_json.adoc b/content/documentation/extensions/mod_json.adoc
index d22ad2f..ee2323c 100644
--- a/content/documentation/extensions/mod_json.adoc
+++ b/content/documentation/extensions/mod_json.adoc
@@ -39,7 +39,7 @@ This extension uses SPI defined by the +tamaya.formats+ extension module.
=== Compatibility
-The module is based on Java 7, so it will run on Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -65,7 +65,7 @@ used:
[source, java]
-----------------------------------------------
-ConfigurationData dataRead = ConfigurationFormats.readConfig(
+ConfigurationData dataRead = ConfigurationFormats.getInstance().readConfig(
getClassLoader().getResource("myFileConfig.json"), new JSONFormat()));
-----------------------------------------------
@@ -75,6 +75,6 @@ registers the _json_ format automatically using the `ServiceContext`):
[source, java]
-----------------------------------------------
-PropertySource ps = ConfigurationFormats.createPropertySource(
+PropertySource ps = ConfigurationFormats.getInstance().createPropertySource(
getClassLoader().getResource("myFileConfig.json"));
-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_metamodel.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_metamodel.adoc b/content/documentation/extensions/mod_metamodel.adoc
index d1dec94..3cec143 100644
--- a/content/documentation/extensions/mod_metamodel.adoc
+++ b/content/documentation/extensions/mod_metamodel.adoc
@@ -71,7 +71,7 @@ as the system's _default_ configuration (accessible from `ConfigurationProvider.
=== Compatibility
-The module is based on Java 7, so it will not run on Java 7 and beyond.
+The module is based on Java 8.
=== Installation
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_microprofile.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_microprofile.adoc b/content/documentation/extensions/mod_microprofile.adoc
index b6d8bb0..c9cfe3e 100644
--- a/content/documentation/extensions/mod_microprofile.adoc
+++ b/content/documentation/extensions/mod_microprofile.adoc
@@ -25,7 +25,7 @@ Tamaya _Microprofile_ currently provides full integration for the Microprofile C
=== Compatibility
-Both modules are based on Java 8, so they will run on Java 8 and beyond. The implemented Microprofile API is currently
+Both modules are based on Java 8. The implemented Microprofile API is currently
version 1.1.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_mutable_config.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_mutable_config.adoc b/content/documentation/extensions/mod_mutable_config.adoc
index 237572c..4a61426 100644
--- a/content/documentation/extensions/mod_mutable_config.adoc
+++ b/content/documentation/extensions/mod_mutable_config.adoc
@@ -21,7 +21,7 @@ functionality.
=== Compatibility
-The module is based on Java 7, so it can be used with Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -42,7 +42,7 @@ To benefit from configuration mutability support you only must add the correspon
==== Accessing MutableConfiguration
-The core of the module is the +MutableConfigurationProvider+ singleton, which provides access to +MutableConfiguration+
+The core of the module is the +MutableConfiguration+ interface, which provides access to +MutableConfiguration+
instance, which extends +Configuration+. This interface adds additional methods to add/update or remove property values.
Hereby each +MutableConfiguration+ manages a transaction like context, which includes
a UUID that identifes a change.
@@ -56,8 +56,7 @@ finally changes written back to the backend:
[source,java]
.Accessing and changing configuration
--------------------------------------------
-MutableConfiguration config = MutableConfigurationProvider
- .createMutableConfiguration();
+MutableConfiguration config = MutableConfiguration.create();
config.put("newKey", "newValue")
.put("anotherKey", "updatedValue")
.remove("valueNotValid")
@@ -71,8 +70,7 @@ We can also pass any +Configuration+ to render it into a mutable instance, e.g.
.Explicitly passing the backing configuration
--------------------------------------------
Configuration config = ...;
-MutableConfiguration config = MutableConfigurationProvider
- .createMutableConfiguration(config);
+MutableConfiguration config = MutableConfiguration.create(config);
--------------------------------------------
NOTE: If a configuration does not contain any +MutablePropertySource+ instances,
@@ -85,38 +83,26 @@ We will show in the following sections more details on the options provided...
[source, java]
---------------------------------------------
-public final class MutableConfigurationProvider {
-
- private MutableConfigurationProvider(){}
-
- public static MutableConfiguration createMutableConfiguration();
- public static MutableConfiguration createMutableConfiguration(
- ChangePropagationPolicy changePropgationPolicy);
- public static MutableConfiguration createMutableConfiguration(Configuration configuration);
- public static MutableConfiguration createMutableConfiguration(
- Configuration configuration,
- ChangePropagationPolicy changePropgationPolicy);
-
- [...]
-}
----------------------------------------------
-
-As we have not yet shown it, +MutableConfiguration+ is defined as follows:
-
-[source, java]
----------------------------------------------
public interface MutableConfiguration extends Configuration {
void store();
-
ConfigChangeRequest getConfigChangeRequest();
ChangePropagationPolicy getChangePropagationPolicy();
-
MutableConfiguration put(String key, String value);
MutableConfiguration putAll(Map<String, String> properties);
MutableConfiguration remove(Collection<String> keys);
MutableConfiguration remove(String... keys);
+ public static MutableConfiguration create();
+ public static MutableConfiguration create(ClassLoader classLoader);
+ public static MutableConfiguration create(ChangePropagationPolicy changePropgationPolicy);
+ public static MutableConfiguration create(ChangePropagationPolicy changePropgationPolicy,
+ ClassLoader classLoader);
+ public static MutableConfiguration create(Configuration configuration);
+ public static MutableConfiguration create(Configuration configuration,
+ ChangePropagationPolicy changePropgationPolicy);
+
+ [...]
}
---------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_optional.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_optional.adoc b/content/documentation/extensions/mod_optional.adoc
index 0b7d948..cc3e58b 100644
--- a/content/documentation/extensions/mod_optional.adoc
+++ b/content/documentation/extensions/mod_optional.adoc
@@ -24,7 +24,7 @@ Additionally an +EvaluationPolicy+ lets you define the precedence of configured
=== Compatibility
-The module is based on Java 7, so it will not run on Java 7 and beyond.
+The module is based on Java 8.
=== Installation
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_resolver.adoc b/content/documentation/extensions/mod_resolver.adoc
index ad95d14..1bf6b86 100644
--- a/content/documentation/extensions/mod_resolver.adoc
+++ b/content/documentation/extensions/mod_resolver.adoc
@@ -21,7 +21,7 @@ cycles to loop endlessly.
=== Compatibility
-The module is based on Java 7, so it can be used with Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -71,6 +71,25 @@ Currently the module defines the following resolvers:
|=======
+=== Explicit Expression Resolution
+
+The resolvers registered are normall running implicitly, when corresponding placeholders are used in configuration
+values. Additionally the expression resolution functionality can also used explcitly:
+
+[source,java]
+---------------
+public final class Resolver {
+
+ public static Resolver getInstance();
+ public static Resolver getInstance(ClassLoader classLoader);
+
+ public String evaluateExpression(String key, String value);
+ public String evaluateExpression(String key, String value, ClassLoader classLoader);
+ public String evaluateExpression(String value);
+ public String evaluateExpression(String value, boolean maskNotFound);
+}
+---------------
+
=== SPI: Implementing your own Resolvers
The module also provides a small but powerful SPI for adding your own resolver implementations. Basically the
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_resources.adoc b/content/documentation/extensions/mod_resources.adoc
index 2e06053..5ee5657 100644
--- a/content/documentation/extensions/mod_resources.adoc
+++ b/content/documentation/extensions/mod_resources.adoc
@@ -17,7 +17,7 @@ descriptive ant-styled resource patterns.
=== Compatibility
-The module is based on Java 7, so it can be used with Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -47,10 +47,12 @@ ResourceResolver resolver = ConfigResources.getResourceResolver();
[source,java]
-----------------------------------------------
public interface ResourceResolver {
+
+ static ResourceResolver getInstance();
+ static ResourceResolver getInstance(ClassLoader classLoader);
+
Collection<URL> getResources(Collection<String> expressions) {...}
Collection<URL> getResources(String... expressions) {...}
- Collection<URL> getResources(ClassLoader classLoader, String... expressions){...}
- Collection<URL> getResources(ClassLoader classLoader, Collection<String> expressions);
}
-----------------------------------------------
@@ -114,7 +116,7 @@ public class PathBasedPropertySourceProvider implements PropertySourceProvider {
@Override
public Collection<PropertySource> getPropertySources() {
List<PropertySource> propertySources = new ArrayList<>();
- Collection<URL> resources = ConfigResources.getResourceResolver().getResources("META-INF/cfg/**/*.properties");
+ Collection<URL> resources = ResourceResolver.getInstance().getResources("META-INF/cfg/**/*.properties");
for(URL url:resources){
Properties props = new Properties();
try(InputStream is = url.openStream()){
@@ -159,9 +161,6 @@ public class PathBasedPropertySourceProvider implements PropertySourceProvider {
=== SPI
-The +ResourceResolver+ that is returned by the +ConfigResources+ singleton is determined by the
-current +ServiceContext+, by default you can replace the default implementation by registering an
+The +ResourceResolver+ that is returned is determined by the
+current +ServiceContext+. You can replace the default implementation by registering an
alternate implementation with an overriding +@Priority+ annotation added using the +ServiceLoader+.
-
-Additionally a +BaseResourceResolver+ class can be used to reduce the amount of code to be written
-on your own.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_server.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_server.adoc b/content/documentation/extensions/mod_server.adoc
index 52081b6..2d38221 100644
--- a/content/documentation/extensions/mod_server.adoc
+++ b/content/documentation/extensions/mod_server.adoc
@@ -114,12 +114,12 @@ The server module formats the configuration returned by default in the following
"sun.jnu.encoding": "Cp1252",
"sun.management.compiler": "HotSpot 64-Bit Tiered Compilers",
"sun.os.patch.level": "",
- "_class": "org.apache.tamaya.functions.FilteredConfiguration",
- "_info.filter": "java.v,sun",
- "_info.format": "application/json",
- "_info.timestamp": "1441463200571",
- "_timestamp": "1441463200571",
- "_type": "Configuration"
+ "[META]class": "org.apache.tamaya.functions.FilteredConfiguration",
+ "[META]info.filter": "java.v,sun",
+ "[META]info.format": "application/json",
+ "[META]info.timestamp": "1441463200571",
+ "[META]timestamp": "1441463200571",
+ "[META]type": "Configuration"
}
-----------------------------------------------
@@ -187,12 +187,12 @@ Configuration:
sun.jnu.encoding: Cp1252,
sun.management.compiler: HotSpot 64-Bit Tiered Compilers,
sun.os.patch.level: ,
- _class: org.apache.tamaya.functions.FilteredConfiguration,
- _info.filter: java.v,sun,
- _info.format: text/plain,
- _info.timestamp: 1441463082020,
- _timestamp: 1441463082021,
- _type: Configuration
+ [META]class: org.apache.tamaya.functions.FilteredConfiguration,
+ [META]info.filter: java.v,sun,
+ [META]info.format: text/plain,
+ [META]info.timestamp: 1441463082020,
+ [META]timestamp: 1441463082021,
+ [META]type: Configuration
-----------------------------------------------
@@ -227,12 +227,12 @@ Configuration:
sun.jnu.encoding: Cp1252,
sun.management.compiler: HotSpot 64-Bit Tiered Compilers,
sun.os.patch.level: ,
- _class: org.apache.tamaya.functions.FilteredConfiguration,
- _info.filter: java.v,sun,
- _info.format: text/html,
- _info.timestamp: 1441463459653,
- _timestamp: 1441463459654,
- _type: Configuration
+ [META]class: org.apache.tamaya.functions.FilteredConfiguration,
+ [META]info.filter: java.v,sun,
+ [META]info.format: text/html,
+ [META]info.timestamp: 1441463459653,
+ [META]timestamp: 1441463459654,
+ [META]type: Configuration
</pre>
</body>
</html>
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_usagetracker.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_usagetracker.adoc b/content/documentation/extensions/mod_usagetracker.adoc
index e0bd8c7..4cd0579 100644
--- a/content/documentation/extensions/mod_usagetracker.adoc
+++ b/content/documentation/extensions/mod_usagetracker.adoc
@@ -20,7 +20,7 @@ VM.
=== Compatibility
-The module is based on Java 7, so it can be used with Java 7 and beyond.
+The module is based on Java 8.
=== Installation
@@ -93,16 +93,19 @@ singleton for configuration statistics is defined as follows:
[source,java]
-----------------------------------------------------------
-public final class ConfigUsageStats{
- public static Set<String> getIgnoredUsagePackages();
- public static void addIgnoredUsagePackages(String... packageName);
- public static void enableUsageTracking(boolean enabled);
- public static Usage getUsage(String key);
- public static Collection<Usage> getUsages();
- public static void clearUsageStats();
- public static Usage getUsageAllProperties();
- public static boolean isUsageTrackingEnabled();
- public static String getUsageInfo();
+public final class ConfigUsage{
+ public static ConfigUsage getInstance();
+ public static ConfigUsage getInstance(ClassLoader classLoader);
+
+ public Set<String> getIgnoredUsagePackages();
+ public void addIgnoredUsagePackages(String... packageName);
+ public void enableUsageTracking(boolean enabled);
+ public Usage getUsage(String key);
+ public Collection<Usage> getUsages();
+ public void clearUsageStats();
+ public Usage getUsageAllProperties();
+ public boolean isUsageTrackingEnabled();
+ public String getUsageInfo();
}
-----------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_validation.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_validation.adoc b/content/documentation/extensions/mod_validation.adoc
index 5b239cb..897bb56 100644
--- a/content/documentation/extensions/mod_validation.adoc
+++ b/content/documentation/extensions/mod_validation.adoc
@@ -20,7 +20,7 @@ defined in a Tamaya Metaconfiguration XML file.
=== Compatibility
-The module is based on Java 7, so it will run on Java 7 and beyond.
+The module is based on Java 8.
=== Installation
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_vertx.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_vertx.adoc b/content/documentation/extensions/mod_vertx.adoc
index eef576b..906367d 100644
--- a/content/documentation/extensions/mod_vertx.adoc
+++ b/content/documentation/extensions/mod_vertx.adoc
@@ -22,7 +22,7 @@ Tamaya _Vertx_ provides configuration services that can be used in a Vertx envir
=== Compatibility
-The module requires Java 8, so it will not run on Java 7.
+The module requires Java 8.
=== Installation
@@ -62,7 +62,7 @@ public abstract class AbstractConfiguredVerticle extends AbstractVerticle{
public Configuration getConfiguration(){
if(this.configuration==null){
- this.configuration = ConfigurationProvider.getConfiguration();
+ this.configuration = Configuration.current();
}
return this.configuration;
}
@@ -73,7 +73,7 @@ public abstract class AbstractConfiguredVerticle extends AbstractVerticle{
}
protected void configure(){
- ConfigurationInjection.getConfigurationInjector().configure(this, getConfiguration());
+ ConfigurationInjector.getInstance().configure(this, getConfiguration());
}
protected final String getConfigProperty(String key);
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_yaml.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_yaml.adoc b/content/documentation/extensions/mod_yaml.adoc
index ceef59a..da76eba 100644
--- a/content/documentation/extensions/mod_yaml.adoc
+++ b/content/documentation/extensions/mod_yaml.adoc
@@ -20,7 +20,7 @@ use intendation for expressing hierarchy, which makes yaml configuration files v
=== Compatibility
-The YAML module is based on Java 7, so it will run on Java 7 and beyond.
+The YAML module is based on Java 8.
=== Installation
@@ -45,7 +45,7 @@ For reading YAML based onfiguration most easily a +YAMLFormat+ can be provided:
[source, java]
-----------------------------------------------
-PropertySource ps = ConfigurationFormats.createPropertySource(
+PropertySource ps = ConfigurationFormats.getInstance().createPropertySource(
getClassLoader().getResource("myFileConfig.yaml"), new YAMLFormat()));
-----------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/quickstart.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/quickstart.adoc b/content/documentation/quickstart.adoc
index e396bcc..edd6757 100644
--- a/content/documentation/quickstart.adoc
+++ b/content/documentation/quickstart.adoc
@@ -4,11 +4,9 @@
== Apache Tamaya: Quickstart
-The fastest way to start with Tamaya is just using the _Core_ implementation,
-implementing the **API** in a minimalistic way. For that add the following
-Maven dependency to your project:
-
-=== Adding the Tamaya Dependency
+The fastest way to start with Tamaya is just using the _Core_ module, which
+provides a simple configuration API. To start add the folloeing
+dependency to your project:
[source,xml,subs="verbatim,attributes"]
----
@@ -29,34 +27,30 @@ to provide the default values when accessing the configuration:
Configuration config = Configuration.current();
String aTextValue = config.getOrDefault("my.value.key", "N/A");
-int aNumericValue = config.getOrDefault("my.numValueKey", Integer.class, 15 /* default */);
+int aNumericValue = config.getOrDefault("my.numValueKey", Integer.class, 15);
BigDecimal bdValue = config.getOrDefault("my.BD.value", BigDecimal.class, BigDecimal.valueOf(120));
+List<URL> urls = config.get("servers.url", new TypeLiteral<List<URL>>());
----
-With Java 8 you can, of course, also use +Optional+, e.g.
+Of course, you can also use +Optional+ values:
[source,java]
----
-Configuration config = Configuration.current();
-
String aTextValue = config.getOptional("my.value.key", String.class).orElse("N/A");
----
=== Add/define your configuration data
-As seen you can immedeatly start working with your configuration backend, without adding any kind of
-default configuration. Nevertheless the _core_ implementation also comes with a _default_ mechanism,
-where you can store your configuration as +.properties+ in your classpath:
+As seen you can start working with your configuration backend, without adding any kind of
+default configuration. Nevertheless Tamaya also comes with a _default_ mechanism:
+simply store your configuration into +META-INF/javaconfiguration.properties+ in your classpath!
-[source]
-----
-META-INF/javaconfiguration.properties
-----
Additionally also system properties are taken into account, hereby overriding the _default_ properties.
Overall Tamaya by default defines the following configuration model per default (most significant first):
. System Properties
+. Environment Properties
. `META-INF/javaconfiguration.properties`
@@ -64,7 +58,7 @@ Overall Tamaya by default defines the following configuration model per default
=== Multiple configuration files
-By default you can provide multiple `javaconfig.properties` files, e.g. as part
+By default you can provide multiple `javaconfiguration.properties` files, e.g. as part
of multiple jars loaded into your system. The system creates one
`PropertySource` for each file found on the classpath. All `PropertySource`
instances created are ordered by their precedence.
@@ -83,7 +77,7 @@ calculated as follows:
NOTE: Since evaluation of the `tamaya.ordinal` is always done first, it is possible to change
the ordinal value by adding a corresponding configuration entry to a property source.
-Tamaya Core uses the following default ordinals:
+Tamaya's Core PropertySources uses the following default ordinals:
[width=70]
[cols="3,1", option="headers"]
@@ -140,7 +134,7 @@ This module also provides a `Resolver` singleton:
[source,java]
----
String myExpression = ...;
-String resolved = Resolver.evaluateExpression(myExpression);
+String resolved = Resolver.getInstance().evaluateExpression(myExpression);
----
@@ -162,7 +156,7 @@ description, e.g.
[source,xml,subs="verbatim,attributes"]
----
-Collection<URL> urls = ResourceResolver.getResources("META-INF/cfg/**/*.properties");
+Collection<URL> urls = Resolver.getInstance().getResources("META-INF/cfg/**/*.properties");
----
For further details refer to the module documentation.
@@ -196,7 +190,7 @@ public class MyType {
}
MyType type = new MyType();
-ConfigurationInjector.configure(type);
+ConfigurationInjector.getInstance().configure(type);
----
Or the same as template:
@@ -208,7 +202,7 @@ public interface MyTypeTemplate {
public String getName();
}
-MyTypeTemplate type = ConfigurationInjector.createTemplate(MyTypeTemplate.class);
+MyTypeTemplate type = ConfigurationInjector.getInstance().createTemplate(MyTypeTemplate.class);
----
Currently the following resolvers are available:
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/spisupport.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/spisupport.adoc b/content/documentation/spisupport.adoc
index 1f727e4..82c4cec 100644
--- a/content/documentation/spisupport.adoc
+++ b/content/documentation/spisupport.adoc
@@ -9,39 +9,38 @@ toc::[]
[[SPISupport]]
== Tamaya SPI Support
-Tamaya _SPI Support_ is a core module only depending on the API. It implements lots of API and SPI related
-artifacts in a portable way. Tamaya's core module reuses this functionality to build up a fully fledged
-Tamaya API implementatation.
+Tamaya _SPI Support_ is a module only depending on the API. It implements lots of API and SPI related
+artifacts in a portable way. Tamaya's core module completes this functionality to implement the
+full Tamaya API. This module can be reused also with alternate implementations of the Tamaya API.
+
=== What functionality this module provide?
-Tamaya _SPI Support_ provides a few helpful base classes that can be used to implement aspects of Tamaya:
+Tamaya _SPI Support_ provides several base classes that can be used to implement the Tamaya Configuration API:
-* +BasePropertySource+ provides an abstract *base class* for implementation of your own PropertySources.
+* +BasePropertySource+ provides an abstract *base class* for implementation of your own `PropertySource`.
* +DefaultConfiguration+ provides you with a simple implementation of the +Configuration+ interface based on a
+ConfigurationContext+ provided. This is also very useful for mocking configuration during test execution, but
not only constraint to that use case.
-* +DefaultConfigurationContext+ provides you with a working implementation of the +ConfigurationContext+.
-* Numerous *converters*, including an +EnumConverter+,that is a converter implementation that can automatically select the currect enumeration values based
- on a configured entry.
+* +DefaultConfigurationContext+ provides an implementation of the +ConfigurationContext+ API.
* +MapPropertySource+ implements a property source based on +java.util.Map+.
* +PriorityServiceComparator+ compares arbitrary services based on their +@Priority+ annotations (also handling the
case, where no such annotation is present).
* +PropertiesResourcePropertySource+ is an implementation of a +PropertySource+ based on a +Properties+ instance,
loadable from any +URL+.
+ +PropertyConverterManager+ is a useful service class, when implementing instances of +ConfigurationContext+.
- It manages registered instances of +PropertyConverter+ and provides easy to use type conversion logic.
-+ +PropertyFiltering+ provides another helpful class that manages +PropertyFilter+ instances and provides an
- easy to use high level API.
+ It manages registered instances of +PropertyConverter+ and provides easy to use type conversion logic based on
+ the registered converters.
++ +PropertyFiltering+ provides a similar class, which manages +PropertyFilter+ instances and provides an
+ easy to use high level filtering API.
+ +PropertySourceComparator+ provides an implementation that compares +PropertySources+ based on their +getOrdinal()+
- values and their class names.
+ values and their class names. It is used to establish the default loading (significance) of property sources.
+ The default configuration implementation also allows to replace the raw value evaluation
logic using a +ConfigValueEvaluator+, similar to Tamaya's core implementation.
NOTE: It is highly recommended that you also read the link:../core.html[documentation] of Tamaya's
- core implementation, since this describes the abstrations in use in more
- detail. This module allows to reuse Tamaya's implementation artifacts but
- still allows alternate implementations of the core API to be used.
+ core implementation, since this describes the abstractions in use in more
+ detail.
=== Compatibility