Return-Path: X-Original-To: apmail-tamaya-commits-archive@minotaur.apache.org Delivered-To: apmail-tamaya-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 4F7811738B for ; Tue, 3 Mar 2015 12:00:59 +0000 (UTC) Received: (qmail 68743 invoked by uid 500); 3 Mar 2015 12:00:59 -0000 Delivered-To: apmail-tamaya-commits-archive@tamaya.apache.org Received: (qmail 68723 invoked by uid 500); 3 Mar 2015 12:00:59 -0000 Mailing-List: contact commits-help@tamaya.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@tamaya.incubator.apache.org Delivered-To: mailing list commits@tamaya.incubator.apache.org Received: (qmail 68714 invoked by uid 99); 3 Mar 2015 12:00:58 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 03 Mar 2015 12:00:58 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED,T_RP_MATCHES_RCVD X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO mail.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with SMTP; Tue, 03 Mar 2015 12:00:54 +0000 Received: (qmail 68388 invoked by uid 99); 3 Mar 2015 12:00:34 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 03 Mar 2015 12:00:34 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id ABD2BE07F3; Tue, 3 Mar 2015 12:00:34 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: anatole@apache.org To: commits@tamaya.incubator.apache.org Message-Id: <4b13709590374de18d1b8d11372e804e@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: incubator-tamaya git commit: Updated docs. Date: Tue, 3 Mar 2015 12:00:34 +0000 (UTC) X-Virus-Checked: Checked by ClamAV on apache.org Repository: incubator-tamaya Updated Branches: refs/heads/master 483b6d431 -> a375f26f2 Updated docs. Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/a375f26f Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/a375f26f Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/a375f26f Branch: refs/heads/master Commit: a375f26f238c3a8ebe0f72edb0913d3241d9e170 Parents: 483b6d4 Author: anatole Authored: Tue Mar 3 12:59:57 2015 +0100 Committer: anatole Committed: Tue Mar 3 13:00:21 2015 +0100 ---------------------------------------------------------------------- docs/API.adoc | 146 ++++++++++++++++++++++++--- docs/Core.adoc | 117 +++++++++++++++------ docs/TamayaDocumentation.adoc | 133 ------------------------ docs/index.adoc | 158 +++++++++++++++++++++++++++++ docs/injection.adoc | 201 +++++++++++++++++++++++++++++++++++++ docs/modules.adoc | 41 ++++++++ docs/modules/injection.adoc | 201 ------------------------------------- docs/modules/modules.adoc | 20 ---- docs/usecases.adoc | 59 +++++++++++ 9 files changed, 679 insertions(+), 397 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a375f26f/docs/API.adoc ---------------------------------------------------------------------- diff --git a/docs/API.adoc b/docs/API.adoc index 0f0d32a..286a198 100644 --- a/docs/API.adoc +++ b/docs/API.adoc @@ -18,12 +18,27 @@ Apache Tamaya -- API :icons: :encoding: UTF-8 :numbered: - +// 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. ''' <<< --> add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg[] +image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[] toc::[] @@ -49,6 +64,7 @@ under the License. ----------------------------------------------------------- :numbered: + [[API]] == The Tamaya API === Overview @@ -92,11 +108,13 @@ This is also reflected in the main parts of the API, which is quite small: * +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +ServiceContext+ mechanism. + === Compatibility The Tamaya API basically is compatible with Java 7 and Java 8. Java 8 additionally introduces additional methods hereby leveraging the newly added Java 8 +Optional+ features and _default_ methods. + [[APIKeyValues]] === Key/Value Pairs @@ -126,6 +144,7 @@ val = props.getProperty("a.b.c.1"); ... -------------------------------------------- + ==== Why Using Strings Only There are good reason to keep of non String-values as core storage representation of configuration. Mostly @@ -158,12 +177,14 @@ Nevertheless most of these advantages can be mitigated easily, hereby still keep * String s also can be used as references pointing to other locations and formats, where configuration is accessible. + [[API Configuration]] === Configuration +Configuration+ is the main API provided by Tamaya. It allows reading of single property values or the whole property map, but also supports type safe access. + ==== Configuration (Java 7) The minimal API defined for Java version earlier than Java 8 looks as follows: @@ -363,6 +384,7 @@ The class +ConfigException+ models the base *runtime* exception used by the conf [[SPI]] == SPI + [[PropertySource]] === Interface PropertySource @@ -493,6 +515,7 @@ public interface PropertyValueCombinationPolicy{ } -------------------------------------------- + [[ConfigurationContext]] ==== The Configuration Context @@ -577,6 +600,7 @@ One of the most important SPI in Tamaya if the +ConfigurationProviderSpi+ interf * to provide access to the right +Configuration/ConfigurationContext+ based on the current runtime context. * Performing changes as set with the current +ConfigurationContextBuilder+. + [[ServiceContext]] ==== The ServiceContext @@ -585,19 +609,117 @@ The +ServiceContext+ hereby defines access methods to obtain components, whereas +ServiceContextManager+ singleton: [source,java] - .Accessing the +ServiceContext+ - -------------------------------------------- - ServiceContext serviceContext = ServiceContextManager.getServiceContext(); +.Accessing the +ServiceContext+ +-------------------------------------------- +ServiceContext serviceContext = ServiceContextManager.getServiceContext(); - public interface ServiceContext{ - int ordinal(); - T getService(Class serviceType); - List getServices(Class serviceType); - } - -------------------------------------------- +public interface ServiceContext{ + int ordinal(); + T getService(Class serviceType); + List getServices(Class serviceType); +} +-------------------------------------------- With the +ServiceContext+ a component can be accessed in two different ways: . access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally the most significant instance is returned only. -. access all items given its type. This will return (by default) all instances loaded a \ No newline at end of file +. access all items given its type. This will return (by default) all instances loadedable from the current + runtime context, ordered by priority, hereby the most significant components added first. + + +## Examples +### Accessing Configuration + +_Configuration_ is obtained from the ConfigurationProvider singleton: + +[source,java] +.Accessing +Configuration+ +-------------------------------------------- +Configuration config = ConfigurationProvider.getConfiguration(); +-------------------------------------------- + +Many users in a SE context will probably only work with _Configuration_, since it offers all functionality +needed for basic configuration with a very lean memory and runtime footprint. In Java 7 access to the keys is +very similar to *Map*, whereas in Java 8 additionally usage of _Optional_ is supported: + +[source,java] +-------------------------------------------- +Configuration config = ConfigurationProvider.getConfiguration(); +String myKey = config.get("myKey"); // may return null +int myLimit = config.getInt("all.size.limit").getAsInt(); // Never returns null +-------------------------------------------- + +In Java 8 the following would be possible as well: + +[source,java] +-------------------------------------------- +int myLimit = config.getOptionalInt("all.size.limit").getAsInt(); // OptionalInt +Class targetClass = config.get("myClass", Class.class); // Optional, returns never null +-------------------------------------------- + + +### Environment and System Properties + +By default environment and system properties are provided automatically as part of the default _Configuration_. The +environment properties hereby are prefixed with _env._. So we can access the current _PROMPT_ environment variable +as follows: + +[source,java] +-------------------------------------------- +String prompt = ConfigurationProvider.getConfiguration().get("env.PROMPT"); +-------------------------------------------- + +Similary the system properties are directly applied to the _Configuration_. So if we pass the following system +property to our JVM: + +[source,java] +-------------------------------------------- +java ... -Duse.my.system.answer=yes +-------------------------------------------- + +we can access it as follows: + +[source,java] +-------------------------------------------- +boolean useMySystem = ConfigurationProvider.getBoolean("use.my.system.answer"); +-------------------------------------------- + + +### Adding a Custom Configuration + +Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the +Tamaya core module you just have to perform the following steps: + +. Define a PropertySource as follows: + +[source,java] +-------------------------------------------- + public class MyPropertySource extends PropertiesFilePropertySource{ + + public MyPropertySource(){ + super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties")); + } + } +-------------------------------------------- + +. Register the new PropertySource using the ServiceLoader by adding the following file: + +[source,listing] +-------------------------------------------- +META-INF/services/org.apache.tamaya.spi.PropertySource +-------------------------------------------- + +And adding there the entry for the new PropertySource: + +[source,listing] +-------------------------------------------- +comp.mapackage.MyPropertySource +-------------------------------------------- + + +[[APIImpl]] +== API Implementation + +The API is implemented by the Tamaya _Core_module. Refer to the link:Core.html[Core documentation] for +further details. http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a375f26f/docs/Core.adoc ---------------------------------------------------------------------- diff --git a/docs/Core.adoc b/docs/Core.adoc index 6671ae6..3bb82e4 100644 --- a/docs/Core.adoc +++ b/docs/Core.adoc @@ -1,3 +1,23 @@ +Apache Tamaya -- Core +===================== +:name: Tamaya +:rootpackage: org.apache.tamaya.core +:title: Apache Tamaya Core +:revnumber: 0.1.1 +:revremark: Incubator +:revdate: March 2015 +:longversion: {revnumber} ({revremark}) {revdate} +:authorinitials: ATR +:author: Anatole Tresch +:email: +:source-highlighter: coderay +:website: http://tamaya.incubator.apache.org/ +:iconsdir: {imagesdir}/icons +:toc: +:toc-placement: manual +:icons: +:encoding: UTF-8 +:numbered: // 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 @@ -14,36 +34,38 @@ // KIND, either express or implied. See the License for the // specific language governing permissions and limitations // under the License. +''' + +<<< +image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[] + +toc::[] + +<<< +:numbered!: <<< [[Core]] == Tamaya Core === Overview -Tamaya Core provides an implementation of the Tamaya Configuration API and adds additional functionality and -building blocks for supporting SPI implementations. +Tamaya Core provides an implementation of the link:API.html[Tamaya Configuration API] and adds additional functionality +and building blocks for supporting SPI implementations. Tamaya Core contains the following artifacts: -* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder+ ConfigurationProvider+ -* A +ServiceLoader+ based +ServiceContext+ implementation. -* A PropertyConverterManager+ that loads and stores references to all the rconfigured +PropertyConverter+ instances. -* Default PropertySources for environment data. - -All minimally required components are implemented and registered, so basically the RI is a complete configuration -solution. Nevertheless it is also very minimalistic: - -. It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and +* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder+ ConfigurationProviderSpi+ +* A +java.util.ServiceLoader+ based +ServiceContext+ implementation. Hereby it implements component priorization based + on the +@Priority+ annotations. +* A PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances +hereby providing type conversion for all important types. +* A simple default configuration setup using the current classpath and an optional staging variable. +* It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and registers them in the global +ConfigurationContext+ -. It provides a +ConfigurationContextBuilder+ and allows changing the current +ConfigurationContext+. -. It provides +PropertyConverter+ instances for the most commonly used types. -. It implements component priorization based on the +@Priority+ annotations. -. It provides default +PropertySource+ implementations for - .. Environment Properties - .. System Properties - .. PropertySources based on +Properties+. +* It provides a +ConfigurationContextBuilder+ and allows changing the current +ConfigurationContext+. -The overall size of the library is very small. Nevertheless it is flexible enough to be extended with additional -features as needed, such as +The overall size of the library is very small. All required components are implemented and registered, so basically the +Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible +enough to be extended/accommodated with additional features as needed, such as * placeholder and resolution mechanisms * dynamic resource path lookup, e.g. with ant styled patterns @@ -56,13 +78,14 @@ features as needed, such as * remote configuration * and more -For details about the extension modules available and their functionality refer to the extension user guide. +For details about the extension modules available and their functionality refer to the link:modules.html[extension user guide]. [[CorePropertyConverters]] === Default PropertyConverters in Core -As said the _Core_ module delivers several default +PropertyConverter+ instances out of the box: +As mentioned the Core module delivers several default +PropertyConverter+ instances out of the box. Find below the +listing of converters automatically registered with the Core module: [width="100%",frame="1",options="header",grid="all"] |======= @@ -92,18 +115,19 @@ As said the _Core_ module delivers several default +PropertyConverter+ instances === Registering PropertyConverters -Additional +PropertyConverters+ can be implemented easily. It is recommended to register then using the +ServiceLoader+, -menaing you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified +Additional +PropertyConverters+ can be implemented easily. It is recommended to register then using the +java.util.ServiceLoader+, +meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified class names of the converters to be registered (one line per each). -Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters programmatically, Note -hereby that implementations can be read-only thus not allowing adding additional converters programmatically. +Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters programmatically. + +NOTE: API Implementations can be read-only thus not allowing adding additional converters programmatically. -[[ComponentPriorization]] +[[ComponentLoadingAndPriorization]] === Component Loading and Priorization -Tamaya Core in general loads all components using the +ServiceLoader+ mechanism. This means that new components +Tamaya Core in general loads all components using the +java.util.ServiceLoader+ mechanism. This means that new components must be registered by adding a file under +META-INF/service/+ containing the fully qualified implementation class names of the components to be registered (one line per each). The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of components. Tamaya @@ -132,12 +156,32 @@ due to several reasons: whatever may be appropriate. +[[CorePropertySources]] +== Configuration Setup in Core -NOTE: TODO Discuss the defaults provided by core! +Tamaya Core provides a minimal, but already powerful configuration setting, that allows you to configure SE +applications already easily. Basically you can provide configuration properties using the following formats and +locations (from weakest to strongest): +. Read environment properties and add them prefixed with +env.+ +. Read all files found in +META-INF/cfg/defaults.properties+ +. Read all files found in +META-INF/cfg/${tamaya.stage}/defaults.properties+ +. Read all files found in +META-INF/cfg/config.properties+ +. Read all files found in +META-INF/cfg/${tamaya.stage}/config.properties+ +. Read current system properties. -[[CorePropertySources]] -=== Default PropertySources in Core +Hereby +tamaya.stage+ can be set by setting an according environment property, or by applying (overriding any environment +property) a corresponding system property: + +[source, listing] +----------------------------------------- +-Dtamaya.stage=test +----------------------------------------- + +If not set the staging locations will be ignored. + + +=== Overview of Registered Default Property Sources and Providers The Tamaya Core implementation provides a couple of default +PropertySource+ implementations, which are automatically registered. They are all in the package +org.apache.tamaya.core.propertysource+: @@ -155,6 +199,7 @@ registered. They are all in the package +org.apache.tamaya.core.propertysource+: There is also a class +DefaultOrdinal+, which defines several default ordinals. Beside the ordinals for system and environment properties above, there may additional default ordinals defined in the future. + === Abstract Class PropertiesFilePropertySource The abstract class +PropertiesFilePropertySource+ can be used for implementing a +PropertySource+ based on a +URL+ @@ -212,3 +257,13 @@ the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, or d With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also a default +PropertySourceProvider+ present that loads all .properties files found at +META-INF/javaconfiguration.properties+. + + +[[Extensions]] +== Adding Extensions + +The Core module only implements the link:API.html[API]. Many users require/wish additional functionality from a +configuration system. Fortunately there are numerous extensions available, that add different functionality. +Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath. + +For detailed information on the extensions available refer to the link:modules.html[extensions documentation]. http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a375f26f/docs/TamayaDocumentation.adoc ---------------------------------------------------------------------- diff --git a/docs/TamayaDocumentation.adoc b/docs/TamayaDocumentation.adoc deleted file mode 100644 index eb767c5..0000000 --- a/docs/TamayaDocumentation.adoc +++ /dev/null @@ -1,133 +0,0 @@ -Apache Tamaya -- Documentation -============================== -:name: Tamaya -:rootpackage: org.apache.tamaya -:title: Apache Tamaya -:revnumber: 0.1-SNAPSHOT -:revremark: Incubator -:revdate: November 2014 -:longversion: {revnumber} ({revremark}) {revdate} -:authorinitials: ATR -:author: Anatole Tresch, Anatole Tresch -:email: -:source-highlighter: coderay -:website: http://tamaya.incubator.apache.org/ -:iconsdir: {imagesdir}/icons -:toc: -:toc-placement: manual -:icons: -:encoding: UTF-8 -:numbered: - -''' - -<<< - --> add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg[] - -toc::[] - -<<< -:numbered!: ------------------------------------------------------------ -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. ------------------------------------------------------------ - -:numbered: - -<<< - -== Introduction -This document describes the Tamaya Configuration System. It provides an overview of the different building blocks and -links you to more detailed documentations. - -=== Working Group -This work is being conducted as part of a community lead joint effort under the Apache Software Foundation. This -specification is the result of the collaborative work of the members of the Tamaya Users Group and the community at -large. - -=== Goals -Configuration is a key feature in all kind of programming languages. Basically configuration is the parametrization of -well defined aspects of a software product without having to recompile/rebuild the code. Summarizing configuration -can affect basically every part of a system, which renders configuration to a real cross-cutting concern, usable in -many facets. - -==== Targets -Tamaya targets to support all general configuration aspects in a system, e.g. - -* application configuration -** plugins -** modules -** components -* Container configuration, e.g. of Java EE enabling portability and dynamic provisioning -* Configuration of CDI (interceptors, decorators and alternatives) -* Configuration of Bean Validation, JSF, web applications etc. -* Configuration of instances within Java SE, e.g. by passing instances to a method that injects configured values, - and by providing accessors to evaluate current configuration values. This can be used explicitly or transparently - by client code. - -Since configuration is implemented and applied in various ways Tamaya will allow you to use - -* multiple configuration locations, including remote locations -* multiple configuration formats, including custom formats -* multiple configuration loading mechanisms, including custom mechanisms. By default reading the classpath, files und - URIs are supported by default. -* type conversion -* configuration filtering and property adapters -* configuration of collections - -=== Required Java version -The full API is based on Java SE 8.0 language features, whereas a compatible PI is similarly available for Java SE 7. - -=== How is Tamaya organized -The Tamaya project consists of the following parts: - -* The *API* is a complete SE based configuration API, that provides the absolute minimum of functionality needed. - It is modelled in a minimal, but expendable way. It should be easily implemented within a few kb, so it is also - possible to use it witin Java ME. The main features supported by the minimal API are: - ** Reading configuration as String/String key/value pairs - ** Reading configuration as type safe values, including transparent conversion. - ** Extending configuration using operators and queries. - ** An SPI providing abstractions for component lifecycle, property sources, peroperty source providers, configuration - context and property filters. -* The "core* part implements the API. Basically with the core part and the API you are ready to go, but you may - add additional extensions that provide additional features that are very useful. -* Extensions are additional libraries that you can add to your project setup. Most important features implemented - by modules are - ** Dynamic resolution of configured values. - ** Pattern based resource location - ** Configuration injection and configuration template support - ** Support for additional configuration formats - ** Prepared configuration metamodels - ** Integration with other frameworks as configuration consumer or producer. -* Finally the *documentation* module provides comprehensive documentation on all features provided. - -=== Further Information -==== Use Cases -The use cases collected can be found link:usecases/usecases.adoc[here]. - -==== Requirements -The requirements collected can be found link:requirements/requirements.adoc[here]. - -==== Modules -Detailed documentation on the available modules can be found link:modules/modules.adoc[here]. - -==== Examples -A comprehensive set of examples can be found link:examples/examples.adoc[here]. - - http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a375f26f/docs/index.adoc ---------------------------------------------------------------------- diff --git a/docs/index.adoc b/docs/index.adoc new file mode 100644 index 0000000..de1e98d --- /dev/null +++ b/docs/index.adoc @@ -0,0 +1,158 @@ +Apache Tamaya -- Documentation +============================== +:name: Tamaya +:rootpackage: org.apache.tamaya +:title: Apache Tamaya +:revnumber: 0.1-SNAPSHOT +:revremark: Incubator +:revdate: November 2014 +:longversion: {revnumber} ({revremark}) {revdate} +:authorinitials: ATR +:author: Anatole Tresch +:email: +:source-highlighter: coderay +:website: http://tamaya.incubator.apache.org/ +:iconsdir: {imagesdir}/icons +:toc: +:toc-placement: manual +:icons: +:encoding: UTF-8 +:numbered: +// 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. +''' + +<<< + +image::http://tamaya.incubator.apache.org/resources/images/logos/logo_wood.png[] + +toc::[] + +<<< +:numbered!: +----------------------------------------------------------- +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. +----------------------------------------------------------- + +:numbered: + +<<< + +== Introduction +This documentation describes the Tamaya Configuration System. It provides an overview of the different building blocks and +links you to more detailed documentations. + + +=== Working Group +This work is being conducted as part of a community lead joint effort under the Apache Software Foundation. This +specification is the result of the collaborative work of the members of the Tamaya Users Group and the community at +large. + + +=== Goals +Configuration is a key feature in all kind of programming languages. Basically configuration is the parametrization of +well defined aspects of a software product without having to recompile/rebuild the code. Summarizing configuration +can affect basically every part of a system, which renders configuration to a real cross-cutting concern, usable in +many facets. + + +==== Targets +Tamaya targets to support all general configuration aspects in a system, e.g. + +* application configuration + ** plugins + ** modules + ** components +* Container configuration, e.g. of Java EE enabling portability and dynamic provisioning +* Configuration of CDI (interceptors, decorators and alternatives) +* Configuration of Bean Validation, JSF, web applications etc. +* Configuration of instances within Java SE, e.g. by passing instances to a method that injects configured values, + and by providing accessors to evaluate current configuration values. This can be used explicitly or transparently + by client code. + +Since configuration is implemented and applied in various ways Tamaya will allow you to use + +* multiple configuration locations, including remote locations +* multiple configuration formats, including custom formats +* multiple configuration loading mechanisms, including custom mechanisms. By default reading the classpath, files und + URIs are supported by default. +* type conversion +* configuration filtering and property adapters +* configuration of collections + + +=== Required Java version +The full API is based on Java SE 8.0 language features, whereas a compatible implementation of API and Core +is similarly available for Java SE 7 as well. + + +== Overview +=== How is Tamaya organized + +The Tamaya project consists of the following parts: + +* The link:API.html[API] is a complete SE based configuration API, that provides the minimum of functionality needed. + It is modelled in a extensible way and only requires a few kb. The main features supported by the link:API.html[] are: + ** Reading configuration as String/String key/value pairs + ** Reading configuration as type safe values, including type conversion. + ** Extending configuration using operators and queries. + ** An SPI providing abstractions for component lifecycle, property sources, property source providers, configuration + context and property filters. +* The link:Core.html[Core] implements the link:API.html[API]. Basically with the core part (and the API) you are ready to go, but you may + add additional extensions that provide more features that are very useful. +* Extensions are additional libraries that you can add to your project setup. Most important features are: + ** Dynamic resolution of configured values. + ** Pattern based resource location + ** Configuration injection and configuration template support + ** Support for additional configuration formats + ** Collection Support + ** Prepared configuration metamodels + ** Integration with other frameworks as configuration consumer or producer. +* Finally the *documentation* module provides comprehensive documentation on all features provided. + +== Further Information + +* There is a small document discussing link:usecases.html[Use Cases] and +* a document discussing link:requirements.html[Requirements]. + +== Detailed Documentation + +* link:API.html[Tamaya API Documentation] and link:../javadoc/api/index.html[API Javadoc] +* link:Core.html[Tamaya Core Documentation] and link:../javadoc/core/index.html[Core Javadoc] +* link:modules.html[Tamaya Modules Documentation] and link:../javadoc/modules/index.html[Extensions Javadoc] + + +== Examples + +* A comprehensive set of examples can be found link:../examples.html[here]. + + http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a375f26f/docs/injection.adoc ---------------------------------------------------------------------- diff --git a/docs/injection.adoc b/docs/injection.adoc new file mode 100644 index 0000000..2522fdd --- /dev/null +++ b/docs/injection.adoc @@ -0,0 +1,201 @@ +Apache Tamaya -- Injection Module +================================= +:name: Tamaya +:rootpackage: org.apache.tamaya.inject +:title: Apache Tamaya Injection +:revnumber: 0.1-SNAPSHOT +:revremark: Incubator +:revdate: November 2014 +:longversion: {revnumber} ({revremark}) {revdate} +:authorinitials: ATR +:author: Anatole Tresch +:email: +:source-highlighter: coderay +:website: http://tamaya.incubator.apache.org/ +:iconsdir: {imagesdir}/icons +:toc: +:toc-placement: manual +:icons: +:encoding: UTF-8 +:numbered: + +// 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. +<<< +[[Injection]] +== The Tamaya Injection API +=== Overview + +Inversion of Control (aka IoC/the Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate +code. In Java there are different frameworks available that all provide IoC mechanisms. Unfortunately IoC is not a +built-in language feature. So for a portable solution that works also in Java SE Tamaya itself has to provide the +according injection services. This module adds this functionality to Tamaya. As an example refer to the following +code snippet: + +[source,java] +.Annotated Example Class +-------------------------------------------- +package foo.bar; + +public class ConfiguredClass{ + + // resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty + private String testProperty; + + @ConfiguredProperty(keys={"a.b.c.key1","a.b.legacyKey",area1.key2"}) + @DefaultValue("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.") + String value1; + + // Using a (default) String -> Integer converter + @ConfiguredProperty(keys="a.b.c.key2") + private int value2; + + // resolved by default as foo.bar.ConfiguredClass.accessUrl + // Using a (default) String -> URL converter + @DefaultValue("http://127.0.0.1:8080/res/api/v1/info.json") + private URL accessUrl; + + // Config injection disabled for this property + @NoConfig + private Integer int1; + + // Overriding the String -> BigDecimal converter with a custom implementation. + @ConfiguredProperty(keys="BD") + @WithAdapter(MyBigDecimalRoundingAdapter.class) + private BigDecimal bigNumber; + + ... +} +-------------------------------------------- + +The class does not show all (but most) possibilities provided. Configuring an instance of the +class using Tamaya is very simple. The only thing is to pass the instance to Tamaya to let +Tamaya inject the configuration (or throw a +ConfigException+, if this is not possible): + +[source,java] +.Configuring the +ConfiguredClass+ Instance +-------------------------------------------- +ConfiguredClass classInstance = new ConfiguredClass(); +ConfigurationInjector.configure(configuredClass); +-------------------------------------------- + +==== The Annotations in detail + +The +ConfigurationInjector+ interface provides methods that allow any kind of instances to be configured +by passing the instances to +T ConfigurationInjector.getInstance().configure(T);+. The classes passed +hereby must not be annotated with +@ConfiguredProperty+ for being configurable. By default Tamaya +tries to determine configuration for each property of an instance passed, using the following resolution policy: + +Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the following keys: +[source, listing] +-------------------------------------------- +a.b.MyClass.myField +a.b.MyClass.my-field +MyClass.myField +MyClass.my-field +myField +my-field +-------------------------------------------- + +So given the following properties: + +[source, properties] +-------------------------------------------- +a.b.Tenant.id=1234 +Tenant.description=Any kind of tenant. +name= +-------------------------------------------- + +The following bean can be configured as follows: + +[source, java] +-------------------------------------------- +package a.b; + +public final class Tenant{ + private int id; + private String name; + private String description; + + public int getId(){ + return id; + } + public String getName(){ + return name; + } + public String getDescription(){ + return description; + } +} + +Tenant tenant = ConfigurationInjector.getInstance().configure(new Tenant()); +-------------------------------------------- + +In many cases you want to create a supplier that simply creates instances that are correctly configured as defined +by the current context. This can be done using +Suppliers+: + +[source, java] +-------------------------------------------- +Supplier configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(Tenant::new); +-------------------------------------------- + + + +Hereby this annotation can be +used in multiple ways and combined with other annotations such as +@DefaultValue+, ++@WithLoadPolicy+, +@WithConfig+, +@WithConfigOperator+, +@WithPropertyAdapter+. + +To illustrate the mechanism below the most simple variant of a configured class is given: + +[source,java] +.Most simple configured class +-------------------------------------------- +pubic class ConfiguredItem{ + @ConfiguredProperty + private String aValue; +} +-------------------------------------------- + +When this class is configured, e.g. by passing it to +Configuration.configure(Object)+, +the following is happening: + +* The current valid +Configuration+ is evaluated by calling +Configuration cfg = Configuration.of();+ +* The current property value (String) is evaluated by calling +cfg.get("aValue");+ +* if not successful, an error is thrown (+ConfigException+) +* On success, since no type conversion is involved, the value is injected. +* The configured bean is registered as a weak change listener in the config system's underlying + configuration, so future config changes can be propagated (controllable by applying the + +@WithLoadPolicy+ annotation). + +In the next example we explicitly define the property value: +[source,java] +-------------------------------------------- +pubic class ConfiguredItem{ + + @ConfiguredProperty + @ConfiguredProperty("a.b.value") + @configuredProperty("a.b.deprecated.value") + @DefaultValue("${env:java.version}") + private String aValue; +} +-------------------------------------------- + +Within this example we evaluate multiple possible keys. Evaluation is aborted if a key could be successfully +resolved. Hereby the ordering of the annotations define the ordering of resolution, so in the example above +resolution equals to +"aValue", "a.b.value", "a.b.deprecated.value"+. If no value could be read +from the configuration, it uses the value from the +@DefaultValue+ annotation. Interesting here +is that this value is not static, it is evaluated by calling +Configuration.evaluateValue(Configuration, String)+. http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a375f26f/docs/modules.adoc ---------------------------------------------------------------------- diff --git a/docs/modules.adoc b/docs/modules.adoc new file mode 100644 index 0000000..383939d --- /dev/null +++ b/docs/modules.adoc @@ -0,0 +1,41 @@ +Apache Tamaya -- Extension Modules +================================== +:name: Tamaya +:rootpackage: org.apache.tamaya +:title: Apache Tamaya Extension Modules +:revnumber: 0.1-SNAPSHOT +:revremark: Incubator +:revdate: March 2015 +:longversion: {revnumber} ({revremark}) {revdate} +:authorinitials: ATR +:author: Anatole Tresch +:email: +:source-highlighter: coderay +:website: http://tamaya.incubator.apache.org/ +:toc: +:toc-placement: manual +:icons: +:encoding: UTF-8 +:numbered: +// 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. +toc::[] + + +== Module Overview + +tbd. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a375f26f/docs/modules/injection.adoc ---------------------------------------------------------------------- diff --git a/docs/modules/injection.adoc b/docs/modules/injection.adoc deleted file mode 100644 index 2522fdd..0000000 --- a/docs/modules/injection.adoc +++ /dev/null @@ -1,201 +0,0 @@ -Apache Tamaya -- Injection Module -================================= -:name: Tamaya -:rootpackage: org.apache.tamaya.inject -:title: Apache Tamaya Injection -:revnumber: 0.1-SNAPSHOT -:revremark: Incubator -:revdate: November 2014 -:longversion: {revnumber} ({revremark}) {revdate} -:authorinitials: ATR -:author: Anatole Tresch -:email: -:source-highlighter: coderay -:website: http://tamaya.incubator.apache.org/ -:iconsdir: {imagesdir}/icons -:toc: -:toc-placement: manual -:icons: -:encoding: UTF-8 -:numbered: - -// 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. -<<< -[[Injection]] -== The Tamaya Injection API -=== Overview - -Inversion of Control (aka IoC/the Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate -code. In Java there are different frameworks available that all provide IoC mechanisms. Unfortunately IoC is not a -built-in language feature. So for a portable solution that works also in Java SE Tamaya itself has to provide the -according injection services. This module adds this functionality to Tamaya. As an example refer to the following -code snippet: - -[source,java] -.Annotated Example Class --------------------------------------------- -package foo.bar; - -public class ConfiguredClass{ - - // resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty - private String testProperty; - - @ConfiguredProperty(keys={"a.b.c.key1","a.b.legacyKey",area1.key2"}) - @DefaultValue("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.") - String value1; - - // Using a (default) String -> Integer converter - @ConfiguredProperty(keys="a.b.c.key2") - private int value2; - - // resolved by default as foo.bar.ConfiguredClass.accessUrl - // Using a (default) String -> URL converter - @DefaultValue("http://127.0.0.1:8080/res/api/v1/info.json") - private URL accessUrl; - - // Config injection disabled for this property - @NoConfig - private Integer int1; - - // Overriding the String -> BigDecimal converter with a custom implementation. - @ConfiguredProperty(keys="BD") - @WithAdapter(MyBigDecimalRoundingAdapter.class) - private BigDecimal bigNumber; - - ... -} --------------------------------------------- - -The class does not show all (but most) possibilities provided. Configuring an instance of the -class using Tamaya is very simple. The only thing is to pass the instance to Tamaya to let -Tamaya inject the configuration (or throw a +ConfigException+, if this is not possible): - -[source,java] -.Configuring the +ConfiguredClass+ Instance --------------------------------------------- -ConfiguredClass classInstance = new ConfiguredClass(); -ConfigurationInjector.configure(configuredClass); --------------------------------------------- - -==== The Annotations in detail - -The +ConfigurationInjector+ interface provides methods that allow any kind of instances to be configured -by passing the instances to +T ConfigurationInjector.getInstance().configure(T);+. The classes passed -hereby must not be annotated with +@ConfiguredProperty+ for being configurable. By default Tamaya -tries to determine configuration for each property of an instance passed, using the following resolution policy: - -Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the following keys: -[source, listing] --------------------------------------------- -a.b.MyClass.myField -a.b.MyClass.my-field -MyClass.myField -MyClass.my-field -myField -my-field --------------------------------------------- - -So given the following properties: - -[source, properties] --------------------------------------------- -a.b.Tenant.id=1234 -Tenant.description=Any kind of tenant. -name= --------------------------------------------- - -The following bean can be configured as follows: - -[source, java] --------------------------------------------- -package a.b; - -public final class Tenant{ - private int id; - private String name; - private String description; - - public int getId(){ - return id; - } - public String getName(){ - return name; - } - public String getDescription(){ - return description; - } -} - -Tenant tenant = ConfigurationInjector.getInstance().configure(new Tenant()); --------------------------------------------- - -In many cases you want to create a supplier that simply creates instances that are correctly configured as defined -by the current context. This can be done using +Suppliers+: - -[source, java] --------------------------------------------- -Supplier configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(Tenant::new); --------------------------------------------- - - - -Hereby this annotation can be -used in multiple ways and combined with other annotations such as +@DefaultValue+, -+@WithLoadPolicy+, +@WithConfig+, +@WithConfigOperator+, +@WithPropertyAdapter+. - -To illustrate the mechanism below the most simple variant of a configured class is given: - -[source,java] -.Most simple configured class --------------------------------------------- -pubic class ConfiguredItem{ - @ConfiguredProperty - private String aValue; -} --------------------------------------------- - -When this class is configured, e.g. by passing it to +Configuration.configure(Object)+, -the following is happening: - -* The current valid +Configuration+ is evaluated by calling +Configuration cfg = Configuration.of();+ -* The current property value (String) is evaluated by calling +cfg.get("aValue");+ -* if not successful, an error is thrown (+ConfigException+) -* On success, since no type conversion is involved, the value is injected. -* The configured bean is registered as a weak change listener in the config system's underlying - configuration, so future config changes can be propagated (controllable by applying the - +@WithLoadPolicy+ annotation). - -In the next example we explicitly define the property value: -[source,java] --------------------------------------------- -pubic class ConfiguredItem{ - - @ConfiguredProperty - @ConfiguredProperty("a.b.value") - @configuredProperty("a.b.deprecated.value") - @DefaultValue("${env:java.version}") - private String aValue; -} --------------------------------------------- - -Within this example we evaluate multiple possible keys. Evaluation is aborted if a key could be successfully -resolved. Hereby the ordering of the annotations define the ordering of resolution, so in the example above -resolution equals to +"aValue", "a.b.value", "a.b.deprecated.value"+. If no value could be read -from the configuration, it uses the value from the +@DefaultValue+ annotation. Interesting here -is that this value is not static, it is evaluated by calling +Configuration.evaluateValue(Configuration, String)+. http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a375f26f/docs/modules/modules.adoc ---------------------------------------------------------------------- diff --git a/docs/modules/modules.adoc b/docs/modules/modules.adoc deleted file mode 100644 index 19421db..0000000 --- a/docs/modules/modules.adoc +++ /dev/null @@ -1,20 +0,0 @@ -= Apache Tamaya -- Extension Mdoules -:name: Tamaya -:rootpackage: org.apache.tamaya -:title: Apache Tamaya Extension Modules -:revnumber: 0.1-SNAPSHOT -:revremark: Incubator -:revdate: November 2014 -:longversion: {revnumber} ({revremark}) {revdate} -:authorinitials: ATR -:author: Anatole Tresch -:email: -:source-highlighter: coderay -:website: http://tamaya.incubator.apache.org/ -:toc: -:toc-placement: manual -:icons: -:encoding: UTF-8 -:numbered: - -toc::[] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a375f26f/docs/usecases.adoc ---------------------------------------------------------------------- diff --git a/docs/usecases.adoc b/docs/usecases.adoc new file mode 100644 index 0000000..4c9d88a --- /dev/null +++ b/docs/usecases.adoc @@ -0,0 +1,59 @@ += Apache Tamaya -- Use Cases +:name: Tamaya +:rootpackage: org.apache.tamaya +:title: Apache Tamaya +:revnumber: 0.1-SNAPSHOT +:revremark: Incubator +:revdate: November 2014 +:longversion: {revnumber} ({revremark}) {revdate} +:authorinitials: OBF +:author: Oliver B. Fischer +:email: +:source-highlighter: coderay +:website: http://tamaya.incubator.apache.org/ +:toc: +:toc-placement: manual +:icons: +:encoding: UTF-8 +:numbered: +// 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. +toc::[] + + +== Use Cases for Java SE Environments + +include::uc/simple-access.adoc[] +include::uc/simple-property-access.adoc[] +include::uc/value-placeholders.adoc[] +include::uc/type-safe-properties.adoc[] +include::uc/templates.adoc[] +include::uc/java8.adoc[] +include::uc/locations.adoc[] +include::uc/formats.adoc[] +include::uc/multiple-configurations.adoc[] +include::uc/external-configuration.adoc[] +include::uc/context-dependent-configuration.adoc[] +include::uc/dynamic-provisioning.adoc[] +include::uc/minimal-propertysource.adoc[] +include::uc/scannable-properties.adoc[] +include::uc/combine-configs.adoc[] +include::uc/management.adoc[] +include::uc/service-context.adoc[] +include::uc/injection.adoc[] + +