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>+. -- --
