http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_resources.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_resources.adoc b/content/extensions/mod_resources.adoc new file mode 100644 index 0000000..c5f07f7 --- /dev/null +++ b/content/extensions/mod_resources.adoc @@ -0,0 +1,173 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + += Apache Tamaya -- Extension: Resources + +// include::temp-properties-files-for-site/attributes.adoc[] +:jbake-type: page +:jbake-status: published + +[[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_development}</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/3d91bad5/content/extensions/mod_server.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_server.adoc b/content/extensions/mod_server.adoc new file mode 100644 index 0000000..5238aca --- /dev/null +++ b/content/extensions/mod_server.adoc @@ -0,0 +1,382 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + += Apache Tamaya -- Extension: Configuration Server +:jbake-type: page +:jbake-status: published + +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>{tamayaVersion}</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/3d91bad5/content/extensions/mod_spi-support.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_spi-support.adoc b/content/extensions/mod_spi-support.adoc new file mode 100644 index 0000000..0e7892f --- /dev/null +++ b/content/extensions/mod_spi-support.adoc @@ -0,0 +1,73 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + += Apache Tamaya -- Extension: Classloader Isolation Support +:jbake-type: page +:jbake-status: published + +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 not 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>{tamayaVersion}</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/3d91bad5/content/extensions/mod_spring.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_spring.adoc b/content/extensions/mod_spring.adoc new file mode 100644 index 0000000..17bd96a --- /dev/null +++ b/content/extensions/mod_spring.adoc @@ -0,0 +1,150 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + += Apache Tamaya -- Extension: Spring Integration +:jbake-type: page +:jbake-status: published + +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 not 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>{tamayaVersion}</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/3d91bad5/content/extensions/mod_yaml.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_yaml.adoc b/content/extensions/mod_yaml.adoc new file mode 100644 index 0000000..e931129 --- /dev/null +++ b/content/extensions/mod_yaml.adoc @@ -0,0 +1,127 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + += Apache Tamaya -- Extension: Builder +:jbake-type: page +:jbake-status: published + +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 not 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>{tamayaVersion}</version> +</dependency> +----------------------------------------------- + + +=== 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/3d91bad5/content/highleveldesign.adoc ---------------------------------------------------------------------- diff --git a/content/highleveldesign.adoc b/content/highleveldesign.adoc new file mode 100644 index 0000000..f58957f --- /dev/null +++ b/content/highleveldesign.adoc @@ -0,0 +1,167 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//include::temp-properties-files-for-site/attributes.adoc[] +:jbake-type: page +:jbake-status: published + + +== The Tamaya High Level Design + +Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required +that build the base of all the other mechanisms: + +The *API* (package +org.apache.tamaya+) provides + +* A simple but complete SE *API* for accessing key/value based _Configuration_: + ** +Configuration+ hereby models configuration, the main interface of Tamaya, providing key/value pairs as raw + (String-based) key/value pairs, allowing also access to typed values. + ** +ConfigurationProvider+ provides the static entry point for accessing configuration. + +The *SPI* (package +org.apache.tamaya.spi+) provides: + ** A simple minimalistic model for configuration data, called _PropertySource_. + ** Several extension points for adding additional configuration property sources or adapting the internal workings + of the overall system. + ** A +ServiceContext / ServiceContextManager+ that controls the loading of the components in Tamaya. This allows to + adapt the behaviour depending on the runtime environment in use, e.g. a Java standalone application, an OSGI + container or a Java EE application server. + +Tamaya *Modules* finally allow to add additional functionality to customize your configuration solution with the +functionality you want. E.g. modules are providing features such as + +* Configuration _injection_ +* _Dynamic placeholders_ and resolution mechanism for configuration values +* Abstractions for reusable _configuration formats_ +* Dynamic configuration updates and change events +* Support for OSGI/Java EE Classloading +* A configuration server/client +* and more... + + +== How Tamaya organizes Configuration +=== Overview + +All the mentioned artifacts are used to organize configuration in a higly flexible and extendable way. Hereby the ++PropertySource+ is the key artifact. In general Tamaya organizes Configuration as follows: + +image::../images/CoreDesign.png[] + +Key abstraction hereby is the +ConfigurationContext+, which basically + +* an ordered chain of +PropertySource+ instances. This chain is used to evaluate raw configuration values. +* a set of +PropertyFilter+ instances that filter the raw values evaluated from the property source chain. +* a set of +PropertyConverter+ that convert String values into typed values when needed. + +In most standalone use cases only one +ConfigurationContext+ will be active at a time. But in more complex scenarios, +such as Java EE also multiple contexts could be active that are active depending on the current runtime context +(e.g. attached to the corresponding classloader(s)). These aspects are basically handled by the ++ConfigurationProvider+ and its corresponding SPIs. + +=== Loading the current _ConfigurationContext_ + +The +ConfigurationContext+ is the core of Tamaya. It manages all configuration sources and additional components +required to evaluate a concrete configuration value: + +* Tamaya loads all available +PropertySource+ instances. Hereby +PropertySource+ instances can be + ** Directly registered (using the mechanism defined by the current +ServiceContext+ implementation, by default + the Java +ServiceLoader+. + ** Provided by a registered instance of +PropertySourceProvider+. +* All loaded property sources are _ordered based on each ordinal_, returned from +PropertySource.getOrdinal()+ as + an ordered chain of PropertySources, building up the ordered chain of +PropertySource+ instances used for raw + configuration value evaluation. +* Tamaya loads all available +PropertyFilter+ instances. Hereby +PropertyFilter+ instances can be registered + by default using the Java +ServiceLoader+ API. The +PropertyFilter+ instances loaded are ordered based on the + +@Priority+ annotations found on each filter. If no priority annotation is present, +0+ is assumed. +* Tamaya loads all available +PropertyConverter+ instances. Hereby +PropertyConverter+ instances can be registered + by default using the Java +ServiceLoader+ API. The +PropertyConverter+ instances loaded are ordered based on the + +@Priority+ annotations found on each filter. If no priority annotation is present, +0+ is assumed. It is + possible to register multiple converters for the same target type. + +=== Evaluating raw property values +When evaluating a concrete configuration value for a given key, Tamaya iterates through this chain of registered +PropertySources. Hereby the final value, by default, is determined by the last non-null value returned from a ++PropertySource+. + +Since the ladder may not always be appropriate, e.g. when values should be combined instead of overridden, a +instance of +PropertyValueCombinationPolicy+ can be registered, which allows to add more detailed behaviour how values +are combined. + +Access to the complete configuration +Map+ is performing the same resolution and combination algorithm, but for all +key/value pairs available. + +=== Filtering the raw properties: +Each raw configuration value evaluated is filtered by the ordered filter chain, as long as there are any changes +applied by any of the filters called. This ensures that also transitive replacements by filters are possible. +If, after a configurable number of evaluation loops still values are changes during each loop, the filtering +process is aborted, since a non-resolvable circular filter issue is assumed. + +The output is the final configuration value as type +String+. + +=== Applying type conversion: +Finally, if the required target type, does not match +Java.ui.lang.String+, all registered +PropertyConverter+ +instances targeting the corresponding target type are asked to convert the given (String-based) configuration +entry to the required (non String) target type. + +Hereby the first _non-null_ value returned by a +PropertyConverter+ is used as the final typed configuration value and +returned to the caller. + +=== Advanced Features +Basically the bahaviour of Tamaya can be customized using the following mechanisms. Basically configuration can be +provided using the following mechanism: + +* Registering additional (default) +PropertySource+ instances. Depending on their _ordinal value_ they + will override or extend existing configuration. +* Registering additional (default) +PropertySourceProvider+ instances.that can provide multiple +PropertySource+ + instances. + +Additionally Tamaya provides hooks for further adapting the internal workings: + +* Adapting the way how multiple entries with the same key are combined (+PropertyValueCombinationPolicy+). This + may be useful, if overriding is not the way how entries of the same key should be combined. An example, where + such an alternate scenario is useful are list entries, that combine all entries encountered to a collecting + list entry. +* Adding additional support for new target types configurable by registering additional +PropertyConverter+ + instances. This can be used for adding support for new types as well as for adding support for additional + formats. +* Complex extensions may adapt the complete +ConfigurationContext+, using the +ConfigurationContextBuilder+ and + reapply the changed instance using +ConfigurationProvider.setConfigurationContext(ConfigurationContext)+. + This is one example how to react on dynamic changes detected on configuration files read. +* Registering additional +PropertyFilter+ instances, that filter the configuration values extracted. +* Registering an alternate +ServiceContext+ to support alternate runtime containers, e.g. a CDI container. +* A combination of all above. + +Additionally instances of +ConfigOperator, ConfigQuery+ can be provided that provide additional functionality +that should not be globally visible. It is recommended to provide them from a singleton accessor, hereby hiding +the effective implementation classes. + +== Component Loading + +As mentioned the component loading of Tamaya can be adapted. By default the JDK +ServiceLoader+ API is used to determine +a +ServiceContext+ implementation that should control +Tamaya's overall component loading. If not found, a default implementation is registered, which relies on the +Java +hava.util.ServiceLoader+ mechanism. This behaviour can be changed by implementing your own version +of the +ServiceContext+ interface, annotating it with a +@Priority+ annotation and registering it using the ++java.util.ServiceLoader+ mechanism. + +== Compatibility + +The Tamaya API is compatible with Java 7 and beyond. + +== Further Documentation + +Being here we recommend to have a look at the more detailed documentation of Tamaya's link:API.html[API and SPI], +and of its current available link:extensions.html[modules]. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/history.adoc ---------------------------------------------------------------------- diff --git a/content/history.adoc b/content/history.adoc new file mode 100644 index 0000000..bb09f0b --- /dev/null +++ b/content/history.adoc @@ -0,0 +1,48 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// . +// http://www.apache.org/licenses/LICENSE-2.0 +// . +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//:source-highlighter: coderay + +//include::temp-properties-files-for-site/attributes.adoc[] +:jbake-type: page +:jbake-status: published +:linkattrs: true + +== Apache Tamaya: Release History + +Overview off all released versions of Apache Tamaya. + +[width="70"] +[cols="2,3,3,3", options="headers", frame="all"] +|=== +| Version +| Release date +| Release Notes +| Download + +| 0.2-incubating +| 06.04.2016 +| http://www.apache.org/dist/incubator/tamaya/0.2-incubating/ReleaseNotes-0.2-incubating.html[Release Notes for 0.2 incubating^] +| http://www.apache.org/dist/incubator/tamaya/0.2-incubating/[Download of 0.2 incubating^] + + +| 0.1-incubating +| 22.08.2015 +| http://www.apache.org/dist/incubator/tamaya/0.1-incubating/ReleaseNotes-0.1-incubating.html[Release Notes for 0.1 incubating^] +| http://www.apache.org/dist/incubator/tamaya/0.1-incubating/[Download of 0.1 incubating^] + +|=== http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/quickstart.adoc ---------------------------------------------------------------------- diff --git a/content/quickstart.adoc b/content/quickstart.adoc new file mode 100644 index 0000000..4567c7b --- /dev/null +++ b/content/quickstart.adoc @@ -0,0 +1,208 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// . +// http://www.apache.org/licenses/LICENSE-2.0 +// . +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//include::temp-properties-files-for-site/attributes.adoc[] +: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_released}</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_development}</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_development}</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/3d91bad5/content/release-guide.adoc ---------------------------------------------------------------------- diff --git a/content/release-guide.adoc b/content/release-guide.adoc new file mode 100644 index 0000000..9c74090 --- /dev/null +++ b/content/release-guide.adoc @@ -0,0 +1,276 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// . +// http://www.apache.org/licenses/LICENSE-2.0 +// . +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//include::temp-properties-files-for-site/attributes.adoc[] +:jbake-type: page +:jbake-status: published + +:sectnums: yes + += Apache Tamaya: Release Guide + +Performing a release requires several steps. This document describes each step, so everybody in the committer's +team should be able to perform the release procedure. + + +== Tell the others you would proceed with the release procedure + +[listing,text] +---- +first steps for the next release + +Hi @ all, + +If there are no objections, I'll start with the first steps for +the next release (review, documentation,...). +It would be great to start with the release procedure next week. + +Best regards, +[name] +---- + +== Check everything is ready + +* Check the jenkins builds. +* Ensure all JIRA-tickets targeting the release are resolved. If not, get in contact with the ticket + owner/assignee to check + ** if the ticket can be postponed for the next release + ** how long it takes to resolve it and if one can help. + + +== Prepare the release + +* Create release notes and commit them to `tamaya/readme/` (format `ReleaseNotes-[version].html`) +* Create a release branch in git and switch to this branch: + + +=== Using the Release Plugin + +For performing the release you can use the maven release plugin: + +[listing,text] +---- +$ git checkout -b vote-tamaya-[release version] +$ export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m" +$ mvn release:prepare -DdryRun=true -DperformRelease=true +# optionally pass GPG params for signing with: -Darguments="-Dgpg.keyname=1336D3E6 -Dgpg.passphrase=XXXXXX" +# copy prepared workspace (to continue faster if an upload fails in the next step) +---- + +* If something fails you may switch to the master branch, fix whatever is needed and rebase your release branch to + accommodate the latest changes done. +* On success you can check the release packages from `dist/target`. +* If everything looks good you can proceed with the release: + +[listing,text] +---- +$ export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m" +$ mvn release:prepare -DperformRelease=true +$ mvn release:perform -DperformRelease=true +---- + +=== Preparing the release without the Release Plugin + +The release plugin is great, but in some cases it breaks even, when release:prepare -DdryRun=true was successful. +Preparing the release vote without the release plugin is stright forward: + +* As described checkout a release branch of the current head +* Then us maven and git commands to prepare the release: + +[listing,text] +---- +$ git checkout -b vote-tamaya-[release version] +$ export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m" +$ mvn versions:set versions:commit -DnewVersion=[release version] -DperformRelease=true +# build the release locally and sign it with your certs +$ mvn clean install -DperformRelease=true -Dgpg.keyname=1336D3E6 -Dgpg.passphrase=XXXXXX +---- + +* Check if everything is in place and correct, when finished you can tag and deploy the release... + +[listing,text] +---- +$ mvn deploy -DperformRelease=true -Dgpg.keyname=1336D3E6 -Dgpg.passphrase=XXXXXX +---- + +* check the created commits including user-name and email +* login to https://repository.apache.org/[^] and go to "Staging Repositories" +* check the contents of the newly created tamaya staging repository +* _close_ the repository to let Nexus do its validations +* On success: +* push the release-branch to the git repo + +[listing,text] +---- +$ git add -A +$ git commit -m "Release Prepare: Set release version." +$ git tag vote01-[release-version] +$ git push --tags +---- + +Finally open the next development version: + +[listing,text] +---- +# example: newVersion=0.3-incubating-SNAPSHOT +$ mvn version:set versions:commit -DnewVersion=[development-version] +$ git add -A +$ git commit -m "Release Prepare: Open new development version." +---- + + + +* Add the distribution artifacts to the dev repositories: + +[listing,text] +---- +$ svn co https://dist.apache.org/repos/dist/dev/incubator/tamaya/ +$ mkdir [version] +$ set RELEASE_HOME='pwd'/[version] +$ cd PROJECT_ROOT +$ cp DISCLAIMER $RELEASE_HOME +$ cp NOTICE $RELEASE_HOME +$ cp LICENCE $RELEASE_HOME +$ cp rat.txt $RELEASE_HOME +# Copy everything from +# $STAGING_REPO/distribution/0.2-incubating/tamaya-distribution-[version]-distribution-* into $RELEASE_HOME +$ svn add [version] +$ svn commit --username <apacheId> +---- + +* Check contents on https://dist.apache.org/repos/dist/dev/incubator/tamaya/[version] + + +== Start the vote + +[listing,text] +---- +[VOTE] Release of Apache Tamaya [version] + +Hi, + +I was running the needed tasks to get the [version] release of Apache Tamaya out. +The artifacts are deployed to Nexus [1] (and [2]) and releases [4]. + +The tag is available at [3] and will renamed once the vote passed. + +Please take a look at the artifacts and vote! + +Please note: +This vote is a "majority approval" with a minimum of three +1 votes (see [5]). + +------------------------------------------------ +[ ] +1 for community members who have reviewed the bits +[ ] +0 +[ ] -1 for fatal flaws that should cause these bits not to be released, and why.............. +------------------------------------------------ + +Thanks, +[name] + +[1] https://repository.apache.org/content/repositories/... +[2] https://repository.apache.org/content/repositories/org/apache/tamaya/tamaya-distribution/[version]/tamaya-[version]-source-release.zip + https://repository.apache.org/content/repositories/org/apache/tamaya/tamaya-distribution/[version]/tamaya-[version]-bin-release.zip +[3] https://git1-us-west.apache.org/repos/asf?p=incubator-tamaya.git;a=commit;h=2910da468fce16210e6dd77d8ba23ddbdd434efe +[4] https://dist.apache.org/repos/dist/dev/incubator/tamaya/[release-version] +[5] http://www.apache.org/foundation/voting.html#ReleaseVotes +---- + +* Announce the Vote + ** Create a short link to the release at http://s.apache.org (format Tamaya_[version]) + ** Tweet about the vote via _@TamayaConf_ + +* After 72 hours close the vote write a reult email, e.g. + +[listing,text] +---- +[Result] (was: Re: [VOTE] Release of Apache Tamaya [version]) + +Thank you for voting! + +X binding +1 votes (pmc): +[list] + +Y non-binding +1 votes: +[list] + +Z -1 votes +[list] +---- + +* After the vote on the PPMC has been finished and is successful, repeat the voting process on the + incubator mailing list. + + +== Perform the release + +If the binding majority approved the vote on both lists continue: + +* Login to https://repository.apache.org/ and _release_ the repository +* Rename the vote branch: + +[listing,text] +---- +$ git branch -m vote01-tamaya-[release-version] tamaya-[release-version] +---- + +* Add a release tag: + +---- +$ git tag -a tamaya-[release-version] +---- + +* Merge master with the new prepared version: + +[listing,text] +---- +$ git checkout master +$ git merge tamaya-[release-version] +$ git push origin tamaya-[release-version] +$ git push origin master +---- + +* Close the release and corresponding tickets at JIRA + +* Wait some minutes and check http://repo2.maven.org/maven2/org/apache/tamaya[^] + +* Upload the distribution Artifacts + +[listing,text] +---- +$ svn co https://dist.apache.org/repos/dist/release/incubator/tamaya/ +$ mkdir [version] +# add and commit the artifacts (*source-release.zip, *bin-release.zip + asc, md5, sha1) +# use the artifacts from: +# http://repo1.maven.org/maven2/org/apache/tamaya/tamaya-distribution/[version]/ +---- + + +== Updating the Tamaya Project Site + +Basically the new site should be directly deployable, just execute + +[listing,text] +---- +$ mvn site site:deploy +---- + + +== Announce the new version + +Announce the new version on @TamayaConf and other social media channels. +Also drop a short mail on the amiling list. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/source.adoc ---------------------------------------------------------------------- diff --git a/content/source.adoc b/content/source.adoc new file mode 100644 index 0000000..e6334d4 --- /dev/null +++ b/content/source.adoc @@ -0,0 +1,41 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// . +// http://www.apache.org/licenses/LICENSE-2.0 +// . +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//include::temp-properties-files-for-site/attributes.adoc[] +: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/3d91bad5/content/start.md ---------------------------------------------------------------------- diff --git a/content/start.md b/content/start.md new file mode 100644 index 0000000..0909d7f --- /dev/null +++ b/content/start.md @@ -0,0 +1,57 @@ +title = About Apache Tamaya +type = page +status = published +~~~~~~ + +About Apache Tamaya +------------------- + +Apache Tamaya (incubating) provides a flexible and powerful +configuration solution +for Java developers using Java SE as well as for more complex +usage scenarios like cloud or Java EE. It provides a modern +type-safe property based Configuration API combined with a +powerful environment model and a flexible SPI. + +Features +-------- + +* Unified Configuration API +* Pluggable Configuration Backends +* Enforceable Configuration Policies +* Configuration Validation and Documentation +* Seemless Enterprise Integration + +Documentation +------------- + +* [Use Cases and Requirements](usecases.html) +* [High Level Design](highleveldesign.html) +* [API](api.html) +* [Core](core.html) +* [Extensions](extensions.html) + +--- + +Quickstart +---------- + +Using Apache Tamaya is simple: + +1. Add `org.apache.tamaya:tamaya-core:TBDreleased_version` to your dependencies. +2. Add your config to `META-INF/javaconfiguration.properties` +3. Access your configuration by `ConfigurationProvider.getConfiguration()` and use it. +4. Look at the [extension modules](extensions.html) to customize your setup! +5. Enjoy! + + +Rationale +--------- + +Configuration is one of the most prominent cross-cutting concerns similar to logging. Most of us already have been +writing similar code again and again in each of our projects. Sometimes in a similar way but mostly always slightly +different, but certainly with high coupling to your configuration backends. Given your code is reused or integrated +some how, or deployed by some customers, struggling starts: not supported backends, different policies, missing +combination and validation mechanisms and so on. Tamaya solves all this by defining a common API and backend SPI. +Your code is decoupled from the configuration backend. There is no difference if your code is deployed on your dev box +or in a clustered Docker environment in production, it stays the same!
