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:48 UTC
[2/8] incubator-tamaya-site git commit: TAMAYA-274 Updated
documentation. TAMAYA-355 Updated documentation. TAMAYA-353 Updated
documentation.
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>+.
--
--