You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by po...@apache.org on 2016/12/18 22:39:47 UTC
[03/10] incubator-tamaya-site git commit: TAMAYA-178: Fix menu
structure
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_resolver.adoc b/content/extensions/mod_resolver.adoc
deleted file mode 100644
index 366c97e..0000000
--- a/content/extensions/mod_resolver.adoc
+++ /dev/null
@@ -1,126 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Resolver
-
-[[Core]]
-== Tamaya Resolver (Extension Module)
-
-=== Overview
-
-Tamaya Resolver is an extension module. Refer to the
-// @todo Fix the link to the modules documentation
-link:modules.html[extensions documentation]
-for further details about modules.
-
-Tamaya Resolver provides a dynamic resolution mechanism, which 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 7, so it can be used with Java 7 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 +PropertyFilter+ that is automatically called, whenever a value
-is accessed.
-
-=== Available Resolvers
-
-Currently the module defined 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 an easy but powerful 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 yhou should be fine with
-the default implementation in place.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_resources.adoc b/content/extensions/mod_resources.adoc
deleted file mode 100644
index 3081149..0000000
--- a/content/extensions/mod_resources.adoc
+++ /dev/null
@@ -1,155 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Resources
-
-[[Core]]
-== Tamaya Resources (Extension Module)
-=== Overview
-
-Tamaya Resources is an extension module. Refer to the
-// @todo Fix the link to the modules page
-link:modules.html[extensions documentation] for further details
-about modules.
-
-Tamaya Resources defines some additional tools to locate resources in your classpath or file system based on descriptive
-ant-styled resource patterns. 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>
------------------------------------------------
-
-
-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.
-
-=== Valid Expression 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 PathBasedPropertySourceProvider implements PropertySourceProvider {
-
- @Override
- public Collection<PropertySource> getPropertySources() {
- List<PropertySource> propertySources = new ArrayList<>();
- Collection<URL> resources = Resources.getResourceResolver().getResources("META-INF/cfg/**/*.properties");
- for(URL url:resources){
- Properties props = new Properties();
- try(InputStream is = url.openStream()){
- props.load(is);
- propertySources.add(new PropertiesBasedPropertySource(url.toString(), props));
- }
- catch(Exception e){
- e.printStackTrace();
- }
- }
-
- return propertySources;
- }
-
- private final static class PropertiesBasedPropertySource implements PropertySource {
- private String name;
- private Map<String,String> properties = new HashMap<>();
-
- public PropertiesBasedPropertySource(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/ede865e4/content/extensions/mod_server.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_server.adoc b/content/extensions/mod_server.adoc
deleted file mode 100644
index 025da45..0000000
--- a/content/extensions/mod_server.adoc
+++ /dev/null
@@ -1,366 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Configuration Server
-
-toc::[]
-
-
-[[Remote]]
-== Tamaya Configuration Server (Extension Module)
-=== Overview
-
-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 7, so it will not run on Java 7 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 onfiguration ist to start the internal server:
-
-[source, java]
------------------------------------------------
-Server server = org.apache.tamaya.server.ConfigServer.createServer();
-server.start(port);
------------------------------------------------
-
-This will start a simple server instance that serves the following URL patterns:
-
-* +GET /config+ provides access to the full configuration tree.
-* +GET /config/filtered/${path}+ let you filter the configuration returned using regular expression (comma separated).
- E.g. +/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 tis parameter explicitly. The value is the expected MIME type to be
- returned. By default the service supports the following types (refer to the SPI section later in this document for
- options to adapt this):
- ** text/html
- ** text/plain
- ** application/xml
- ** text/json
-
-* +scope,scopeId+ allows to use a server-side preconfigured filter/combination policy to be applied for
- evaluating the entries to be returned. Hereby the +scopeId+ paramter allows to address a certain scope.
- As an example think of a scope +?scope=CLIENT&scopeId=client1+ to be passed as request parameters. This
- tells the server module to lookup a configured scope named 'CLIENT' and access a +ConfigOperator+ for the
- given scopeId 'client1'. The returned operator then can filter and combine any kind of entries to the
- required client configuration (for client1). Refer to the scopes section for more details.
-
-
-=== Using the Configuration Servlets
-
-Additionally to the fully built-in solution, it is also possible to integrate the Tamaya server module with a standard
-Java EE servlet container. Tamaya provides 2 servlet implementations:
-
-* the servlet +org.apache.tamaya.server.FilteredConfigServlet+ can be used to register access to configurations
- that also support filtering of the keys. The URL looks like
-
-----------------------------------------------------------
-http(s)://HOST/SERVLET_CONTEXT/PATHS?params
-
-where
- HOST = host name incl port, e.g. 127.0.0.2:234
- SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered
- PATHS = A comma separated number of key paths to be filtered for being returned, e.g.
- java,sun,client
- params = the optional parameters (scope, scopeId and format)
-----------------------------------------------------------
-
-* the servlet +org.apache.tamaya.server.FullConfigServlet+ can be used to register access to configurations
- that alwyas returns all items known. The URL looks like
-
-----------------------------------------------------------
-http(s)://HOST/SERVLET_CONTEXT?params
-
-where
- HOST = host name incl port, e.g. 127.0.0.2:234
- SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered
- params = the optional parameters (scope, scopeId and format)
-----------------------------------------------------------
-
-==== Formatting used by Default
-
-The server module formats the configuration returned by default in thw 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": "",
- "{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"
-}
------------------------------------------------
-
-
-.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="{meta}class">org.apache.tamaya.functions.FilteredConfiguration</entry>
- <entry key="{meta}info.filter">java.v,sun</entry>
- <entry key="{meta}info.format">application/xml</entry>
- <entry key="{meta}info.timestamp">1441463383687</entry>
- <entry key="{meta}timestamp">1441463383687</entry>
- <entry key="{meta}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: ,
- {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
------------------------------------------------
-
-
-.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: ,
- {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>
------------------------------------------------
-
-=== SPI
-
-==== Scopes
-
-As mentioned earlier in this document scopes can be used to define the exact configuration tree to be returned, e.g.
-as a result of combining multiple sub trees. Following an example of the code to be written to return a configuration
-that combines common client default entries with client specific entries:
-
-[source, java]
------------------------------------------------
-public class ClientScopeProvider implements ScopeProvider{
-
- /**
- * Access the unique scope name.
- * @return the unique scope name.
- */
- public String getScopeType(){
- return "CLIENT";
- }
-
- @Override
- public ConfigOperator getScope(String scopeId) {
- return c ->
- ConfigurationFunctions.combine("Scoped Config CLIENT="+scopeId,
- c.with(ConfigurationFunctions.sectionRecursive(true, "client.default")),
- c.with(ConfigurationFunctions.sectionRecursive(true, "client." + scopeId))
- );
- }
-}
------------------------------------------------
-
-This class can be registered using the +ServiceContext+ in place. By default the +ServiceLoader+ is used, so you will
-have to add the following to +META-INF/services/org.apache.tamaya.server.spi.ScopeProvider+:
-
-[source, listing]
------------------------------------------------
-my.full.packagename.ClientScopeProvider
------------------------------------------------
-
-==== Adapting the Way Configuration is Derived
-
-Finally the effective readong and configuration handling logic can also be replaced or improved. This can be
-done by registering your own implementation of the interface +ConfigProviderService+:
-
-[source, java]
-------------------------------------------------
-public interface ConfigProviderService {
- String getConfigurationWithPath(String path, String format, String scope, String scopeId, HttpServletRequest request);
- String getConfiguration(String format, String scope, String scopeId, HttpServletRequest request);
- void updateConfiguration(String payload, HttpServletRequest request);
- void deleteConfiguration(String paths, HttpServletRequest request);
-}
-------------------------------------------------
-
-By default the +ServiceContextManager+ uses the +java.util.ServiceLoader+ for component loading, so to replace the
-default server code you must register a higher +@Priority+ implementation.
-
-
-==== Replacing the Built-In Server
-
-We have seen earlier that starting a configuration server is pretty easy:
-
-[source, java]
------------------------------------------------
-Server server = org.apache.tamaya.server.ConfigServer.createServer();
-server.start(port);
------------------------------------------------
-
-Nevertheless one may want to replace the used implementation of +Server+. This can be done easily by simply
-registering an overriding implementation if the corresponding interface:
-
-[source, java]
------------------------------------------------
-public interface Server {
- void start(int port);
- boolean isStarted();
- void stop();
- void destroy();
-}
------------------------------------------------
-
-==== The ScopeManager Singleton
-
-Finally whe implementing your own server, you might also benefit from the +ScopeManager+ singleton. Basically this
-class loads all registered +ScopeProvider+ and manages the configured scope instances:
-
-[source, java]
------------------------------------------------
-public final class ScopeManager {
- ...
-
- private ScopeManager(){}
-
- /**
- * Get the scope given its name.
- * @param scopeId the scope name
- * @return the scope matching
- * @throws ConfigException, if nos such scope is defined.
- */
- public static ConfigOperator getScope(String scopeId, String target);
-
- /**
- * Get the defined scope names.
- * @return the defined scope names, never null.
- */
- public static Set<String> getScopes();
-
-}
------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_spi-support.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_spi-support.adoc b/content/extensions/mod_spi-support.adoc
deleted file mode 100644
index 7aca208..0000000
--- a/content/extensions/mod_spi-support.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Classloader Isolation Support
-
-toc::[]
-
-
-[[SPISupport]]
-== Tamaya SPI Support (Extension Module)
-=== Overview
-
-The Tamaya SPI support module provides a few helpful base classes that can be used to implement some of the often
-used SPI parts in Tamaya:
-
-* +BasePropertySource+ provides an abstract base class for implementation of your own PropertySources.
-* +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+.
-* +EnumConverter+ is a converter implementation that can automatically select the currect enumeration values based
- on a configured entry.
-* +MapPropertySource+ implements a static 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,
- lodable from any +URL+.
-+ +PropertyConverterManager+ is a service class very useful, 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.
-+ +PropertySourceComparator+ provides an implementation that compares +PropertySources+ based on their +getOrdinal()+
- values and their class names.
-
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from Tamaya CDI integration you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-spisupport</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-The component will not register any components but only providing 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 similarly.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_spring.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_spring.adoc b/content/extensions/mod_spring.adoc
deleted file mode 100644
index 3960dc1..0000000
--- a/content/extensions/mod_spring.adoc
+++ /dev/null
@@ -1,134 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Spring Integration
-
-toc::[]
-
-
-[[Remote]]
-== Tamaya Spring Integration (Extension Module)
-=== Overview
-
-Apache Tamaya currently provides two implementations also full integration for Spring:
-
-* 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 full fledged Tamaya configuration capabilities to Spring.
-
-
-=== Compatibility
-
-Both modules are based on Java 7, so they will run on Java 7 and beyond. The extension shown here works similarly
-with Spring Framework as well as Spring Boot.
-
-
-=== Installation
-
-To benefit from Tamaya Spring integration you only must one of 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.
-
-[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>
---------------------------------------------------------
-
-NOTE: Of course you can also use the newer +@ComponentScan+ annotation as described by the Spring documentation.
-
-
-Similarly if you dont want to use component scanning you can configure things using plain old XML. Simply add the
-following lines somewhere into one of your application context configuration 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
-
-Done so enables you to use Tamaya as a backend for property resolution, e.g. +propertyValue+ as illustrated below
-is resolved from the current Tamaya configuration.
-
-[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]
---------------------------------------------------------
-**
- * Created by Anatole on 25.09.2015.
- */
-@ConfigDefaultSections
-public class ConfiguredSpringBean {
-
- private String message;
-
- @Autowired
- private Environment env;
-
- @Config("java.version")
- private String javaVersion;
-
- @Config
- @ConfigDefault("23")
- private int testNumber;
-
- public String getJavaVersion(){
- return javaVersion;
- }
-
- public int getTestNumber(){
- return testNumber;
- }
-
- public Environment getEnv(){
- return env;
- }
-
- public void setMessage(String message){
- this.message = message;
- }
-
- public String getMessage() {
- return message;
- }
-}
---------------------------------------------------------
-
-Summarizing you get all the nice features of Tamaya out of the box running with your Spring code.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_yaml.adoc
----------------------------------------------------------------------
diff --git a/content/extensions/mod_yaml.adoc b/content/extensions/mod_yaml.adoc
deleted file mode 100644
index b7e53cb..0000000
--- a/content/extensions/mod_yaml.adoc
+++ /dev/null
@@ -1,112 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya -- Extension: Builder
-
-toc::[]
-
-
-[[BuilderCore]]
-== Tamaya YAML (Extension Module)
-=== Overview
-
-The Tamaya YAML module 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 7, so it will run on Java 7 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-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]
------------------------------------------------
-ConfigurationData dataRead = ConfigurationFormats.readConfig(
- 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/ede865e4/content/quickstart.adoc
----------------------------------------------------------------------
diff --git a/content/quickstart.adoc b/content/quickstart.adoc
deleted file mode 100644
index 14ab438..0000000
--- a/content/quickstart.adoc
+++ /dev/null
@@ -1,189 +0,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 **API** in small, minimalistic way. For that add the following
-Maven dependency to your project:
-
-
-[source,xml,subs="verbatim,attributes"]
-----
-<dependency>
- <groupId>{tamaya_mvn_group_id}</groupId>
- <artifactId>tamaya-core</artifactId>
- <version>{tamaya_version}</version>
-</dependency>
-----
-
-Given that you can add your configuration properties to the following locations 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
-. `META-INF/javaconfiguration.properties`
-
-There many modules that extend the capabilities of Tamaya.
-These modules doe not depend on core, so alternative
-implementations of the Tamaya API should work similarly.
-
-
-=== 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 internally creates one
-`PropertySource` for each file found on the classpath. All `PropertySource`
-instances created are ordered by their ordinal value (an int).
-
-Tamaya Core defines the following default ordinals (used, if no custom ordinal is defined):
-
-[width=70]
-[cols="3,1", option="headers"]
-|===
-| Source | Ordinal
-| System Properties | 400
-| Environment Variables | 300
-| Java Configuration Properties | 100
-|===
-
-That means that the value of a configuration variable `x` overhanded via `-Dx=yes` has
-a higher precedence then the entry for configuration variable `x` specified in a `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 Tamaya ordinal for property files
-tamaya.ordinal=123
-----
-
-This assigns an ordinal of 123 to each entry in that configuration resource.
-
-=== Using additional features of Tamaya
-
-There many modules that extend the capabilities of
-Tamaya. 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 (or available soon):
-
-==== 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>
-----
-
-// @todo Auf Modulliste verweisen f�r vollst�ndigen �berblick
-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 {
- @ConfiguredProperty("name")
- 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 {
- @ConfiguredProperty("name")
- 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/ede865e4/content/source.adoc
----------------------------------------------------------------------
diff --git a/content/source.adoc b/content/source.adoc
deleted file mode 100644
index 441bec8..0000000
--- a/content/source.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-:sectnums: yes
-
-= Apache Tamaya: Sources
-
-== Source Code Repositories
-
-The current source code can be found at:
-
- - http://git-wip-us.apache.org/repos/asf/incubator-tamaya.git (read-only)
- - https://git-wip-us.apache.org/repos/asf/incubator-tamaya.git
-
-Alternatively there is also a GitHub read-only mirror at
-https://github.com/apache/incubator-tamaya[https://github.com/apache/incubator-tamaya^].
-
-The GitHub mirror also provides the project as downloadable zip archive.
-
-== Contributions
-
-If you like to contribute to Apache Tamaya please also refer also to our
-<<devguide.adoc#contributing-workflow,section on contributing to Apache Tamaya>>.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/usecases.adoc
----------------------------------------------------------------------
diff --git a/content/usecases.adoc b/content/usecases.adoc
deleted file mode 100644
index 0d0d4e0..0000000
--- a/content/usecases.adoc
+++ /dev/null
@@ -1,488 +0,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]
-------------------------------------------------------------
-Configuration config = Configuration.current();
-------------------------------------------------------------
-
-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 Configuration 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 Property Source SPI
-
-Users expect that implementing an additional configuration property 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.
-
-
-=== Scannable Properties
-
-If possible configuration should be scannable, meaning it should be possible to evaluate the keys available.
-The corresponding capabilities should be accessible by a +isScannable()+ method.
-
-
-=== 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
-+Configuration.configure+ static method:
-
-[source, java]
-.Configuring a POJO
-----------------------------------------------------
-MyPojo instance = new MyPojo();
-Configuration.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.
-
-The following annotations must be present at least:
-
-* *@ConfiguredProperty* 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.
-* *@DefaultValue* (optional) defines a 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 +@ConfiguredProperty+ 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.
-* *@WithPropertyAdapter* 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 {
-
- @ConfiguredProperty("myCurrency")
- @DefaultValue("CHF")
- String getCurrency();
-
- @ConfiguredProperty("myCurrencyRate")
- Long getCurrencyRate();
-
- @ConfigChange
- default configChanged(ConfigChange event){
- ...
- }
-
-}
-----------------------------------------------------
-
-Templates can be accessed by calling the +Configuration.current(Class)+ method:
-
-[source, java]
-.Accessing a type safe Configuration Template
-----------------------------------------------------
-MyConfig config = Configuration.current(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>+.
-
-[[RequirementsNonFunctional]]
-=== Non Functional Requirements
-THe following non-functional requirements must be met:
-
-* tbd
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/templates/menu.thyme
----------------------------------------------------------------------
diff --git a/templates/menu.thyme b/templates/menu.thyme
index 036d68c..eea628e 100644
--- a/templates/menu.thyme
+++ b/templates/menu.thyme
@@ -19,15 +19,29 @@
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Home</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'quickstart.html'">Quickstart</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Documentation</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'/apidocs/index.html'">API</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Development</a></li>
- <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'index.html'">Releases</a></li>
<li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'about.html'">About</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 class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/usecases.html'">Use Cases and Requirements</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/quickstart.html'">Quickstart</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/api.html'">API</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/core.html'">Core</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'documentation/extensions.html'">Extension Guide</a></li>
+ <li class="divider"></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'apidocs/index.html'">Javadoc ${tamaya_version} (external)</a></li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Development <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'development/source.html'">Sources</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'development/community.html'">Community</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'devguide.html'">Development Guide</a></li>
+ <li><a th:with="rootpath=(${content.rootpath != null} ? ${content.rootpath} : '')" th:href="${rootpath}+'release-guide.html'">Release Guide</a></li>
+ </ul>
+ </li>
+<!-- Example:
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Dropdown <b class="caret"></b></a>
<ul class="dropdown-menu">
@@ -41,6 +55,8 @@
</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>
</ul>
</div><!--/.nav-collapse -->
</div>