TAMAYA-186: Add existing pages. * Still work in progress.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/3d91bad5 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/3d91bad5 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/3d91bad5 Branch: refs/heads/master Commit: 3d91bad59dfd5766f0df3e053bde43bb8028ad48 Parents: 90f34d2 Author: Phil Ottlinger <[email protected]> Authored: Mon Oct 31 22:34:17 2016 +0100 Committer: Phil Ottlinger <[email protected]> Committed: Mon Oct 31 22:34:17 2016 +0100 ---------------------------------------------------------------------- content/api.adoc | 616 +++++++++++++++++++ content/community.adoc | 143 +++++ content/core.adoc | 228 +++++++ content/devguide.adoc | 213 +++++++ content/download.adoc | 109 ++++ content/examples.adoc | 71 +++ content/extensions.adoc | 107 ++++ content/extensions/mod_builder.adoc | 101 +++ content/extensions/mod_camel.adoc | 145 +++++ content/extensions/mod_cdi.adoc | 233 +++++++ content/extensions/mod_classloader_support.adoc | 91 +++ content/extensions/mod_collections.adoc | 248 ++++++++ content/extensions/mod_consul.adoc | 75 +++ content/extensions/mod_environment.adoc | 58 ++ content/extensions/mod_etcd.adoc | 205 ++++++ content/extensions/mod_events.adoc | 372 +++++++++++ content/extensions/mod_filter.adoc | 135 ++++ content/extensions/mod_formats.adoc | 243 ++++++++ content/extensions/mod_functions.adoc | 124 ++++ content/extensions/mod_injection.adoc | 445 ++++++++++++++ content/extensions/mod_jodatime.adoc | 64 ++ content/extensions/mod_json.adoc | 77 +++ content/extensions/mod_management.adoc | 108 ++++ content/extensions/mod_metamodel-staged.adoc | 74 +++ content/extensions/mod_model.adoc | 467 ++++++++++++++ content/extensions/mod_mutable_config.adoc | 258 ++++++++ content/extensions/mod_optional.adoc | 70 +++ content/extensions/mod_osgi.adoc | 132 ++++ content/extensions/mod_remote.adoc | 131 ++++ content/extensions/mod_resolver.adoc | 144 +++++ content/extensions/mod_resources.adoc | 173 ++++++ content/extensions/mod_server.adoc | 382 ++++++++++++ content/extensions/mod_spi-support.adoc | 73 +++ content/extensions/mod_spring.adoc | 150 +++++ content/extensions/mod_yaml.adoc | 127 ++++ content/highleveldesign.adoc | 167 +++++ content/history.adoc | 48 ++ content/quickstart.adoc | 208 +++++++ content/release-guide.adoc | 276 +++++++++ content/source.adoc | 41 ++ content/start.md | 57 ++ content/usecases.adoc | 506 +++++++++++++++ jbake.properties | 2 +- templates/menu.thyme | 6 +- templates/post.thyme | 1 - templates/sitemap.thyme | 2 +- 46 files changed, 7701 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/api.adoc ---------------------------------------------------------------------- diff --git a/content/api.adoc b/content/api.adoc new file mode 100644 index 0000000..f830585 --- /dev/null +++ b/content/api.adoc @@ -0,0 +1,616 @@ +// 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 + +[[CoreDesign]] +== Apache Tamaya: API + +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. As a starting point we recommend you read the corresponding +llink:HighLevelDesign.html[High Level Design Documentation] + +[[API]] +== The Tamaya API +The API provides the artifacts as described in the link:HighLevelDesign.html[High Level Design Documentation], which are: + +* A simple but complete SE *API* for accessing key/value based _Configuration_: + ** +Configuration+ hereby models configuration, the main interface of Tamaya. +Configuration+ provides + *** access to literal key/value pairs. + *** functional extension points (+with, query+) using a unary +ConfigOperator+ or + a function +ConfigurationQuery<T>+. + ** +ConfigurationProvider+ provides with +getConfiguration()+ the static entry point for accessing configuration. + ** +ConfigException+ defines a runtime exception for usage by the configuration system. + ** +TypeLiteral+ provides a possibility to type safely define the target type to be returned by a registered + +PropertyProvider+. + ** +PropertyConverter+, which defines conversion of configuration values (String) into any required target type. + +* Additionally the *SPI* provides: + ** _PropertySource:_ is the the SPI for adding configuration data. A +PropertySource+ hereby + *** is designed as a minimalistic interface that be implemented by any kind of data provider (local or remote) + *** provides single access for key/value pairs in raw format as String key/values only (+getPropertyValue+). + *** can optionally support scanning of its provided values, implementing +getProperties()+. + ** _PropertySourceProvider:_ allows to register multiple property sources dynamically, e.g. all config files found in + file system folder.. + ** +ConfigurationProviderSpi+ defines the SPI that is used as a backing bean for the +ConfigurationProvider+ + singleton. + ** +PropertyFilter+, which allows filtering of property values prior getting returned to the caller. + ** +ConfigurationContext+, which provides the container that contains the property sources and filters that form a + configuration. + ** +PropertyValueCombinationPolicy+ optionally can be registered to change the way how different key/value + pairs are combined to build up the final +Configuration+ passed over to the filters registered. + ** +ServiceContext+, which provides access to the components loaded, depending on the current runtime stack. + ** +ServiceContextManager+ provides static access to the +ServiceContext+ loaded. + +This is also reflected in the main packages of the API: + +* +org.apache.tamaya+ contains the main API abstractions used by users. +* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +ServiceContext+ + mechanism. + + + +[[APIKeyValues]] +=== Key/Value Pairs + +Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple +and most commonly used approach are simple literal key/value pairs. So the core building block of {name} are key/value pairs. +You can think of a common +.properties+ file, e.g. + +[source,properties] +.A simple properties file +-------------------------------------------- +a.b.c=cVal +a.b.c.1=cVal1 +a.b.c.2=cVal2 +a=aVal +a.b=abVal +a.b2=abVal +-------------------------------------------- + +Now you can use +java.util.Properties+ to read this file and access the corresponding properties, e.g. + +[source,properties] +-------------------------------------------- +Properties props = new Properties(); +props.readProperties(...); +String val = props.getProperty("a.b.c"); +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 +there are several huge advantages: + +* Strings are simple to understand +* Strings are human readable and therefore easy to prove for correctness +* Strings can easily be used within different language, different VMs, files or network communications. +* Strings can easily be compared and manipulated +* Strings can easily be searched, indexed and cached +* It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in + production as well in testing. +* and more... + +On the other side there are also disadvantages: + +* Strings are inherently not type safe, they do not provide validation out of the box for special types, such as +numbers, dates etc. +* In many cases you want to access configuration in a typesafe way avoiding conversion to the target types explicitly + throughout your code. +* Strings are neither hierarchical nor multi-valued, so mapping hierarchical and collection structures requires some + extra efforts. + +Nevertheless most of these advantages can be mitigated easily, hereby still keeping all the benefits from above: + +* Adding type safe adapters on top of String allow to add any type easily, that can be directly mapped out of Strings. + This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more. +* Also multi-valued, complex and collection types can be defined as a corresponding +PropertyAdapter+ knows how to + parse and create the target instance required. +* 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: + +[source,java] +.Interface Configuration +-------------------------------------------- +public interface Configuration{ + String get(String key); + String getOrDefault(String key, String value); + <T> T get(String key, Class<T> type); + <T> T getOrDefault(String key, Class<T> type, T defaultValue); + <T> T get(String key, TypeLiteral<T> type); + <T> T getOrDefault(String key, TypeLiteral<T> type, T defaultValue); + Map<String,String> getProperties(); + + // extension points + Configuration with(ConfigOperator operator); + <T> T query(ConfigQuery<T> query); + + ConfigurationContext getContext(); +} +-------------------------------------------- + +Hereby + +* +<T> T get(String, Class<T>)+ provides type safe accessors for all basic wrapper types of the JDK. +* +with, query+ provide the extension points for adding additional functionality. +* +getProperties()+ provides access to all key/values, whereas entries from non scannable property sources may not + be included. +* +getOrDefault+ allows to pass default values as needed, returned if the requested value evaluated to +null+. + +The class +TypeLiteral+ is basically similar to the same class provided with CDI: + +[source,java] +-------------------------------------------- +public class TypeLiteral<T> implements Serializable { + + [...] + + protected TypeLiteral(Type type) { + this.type = type; + } + + protected TypeLiteral() { } + + public static <L> TypeLiteral<L> of(Type type){...} + public static <L> TypeLiteral<L> of(Class<L> type){...} + + public final Type getType() {...} + public final Class<T> getRawType() {...} + + public static Type getGenericInterfaceTypeParameter(Class<?> clazz, Class<?> interfaceType){...} + public static Type getTypeParameter(Class<?> clazz, Class<?> interfaceType){...} + + [...] +} +-------------------------------------------- + +Instances of +Configuration+ can be accessed from the +ConfigurationProvider+ singleton: + +[source,java] +.Accessing Configuration +-------------------------------------------- +Configuration config = ConfigurationProvider.getConfiguration(); +-------------------------------------------- + +Hereby the singleton is backed up by an instance of +ConfigurationProviderSpi+. + + +[[PropertyConverter]] +==== Property Converters + +As illustrated in the previous section, +Configuration+ also to access non String types. Nevertheless internally +all properties are strictly modelled as pure Strings only, so non String types must be derived by converting the +configured String values into the required target type. This is achieved with the help of +PropertyConverters+: + +[source,java] +-------------------------------------------- +public interface PropertyConverter<T>{ + T convert(String value, ConversionContext context); + //X TODO Collection<String> getSupportedFormats(); +} +-------------------------------------------- + +The +ConversionContext+ contains additional meta-information for the accessed key, inclusing the key'a name and +additional metadata. + ++PropertyConverter+ instances can be implemented and registered by default using the +ServiceLoader+. Hereby +a configuration String value is passed to all registered converters for a type in order of their annotated +@Priority+ +value. The first non-null result of a converter is then returned as the current configuration value. + +Access to converters is provided by the current +ConfigurationContext+, which is accessible from +the +ConfigurationProvider+ singleton. + + +[[ExtensionPoints]] +=== Extension Points + +We are well aware of the fact that this library will not be able to cover all kinds of use cases. Therefore +we have added functional extension mechanisms to +Configuration+ that were used in other areas of the Java eco-system +as well: + +* +with(ConfigOperator operator)+ allows to pass arbitrary unary functions that take and return instances of + +Configuration+. Operators can be used to cover use cases such as filtering, configuration views, security + interception and more. +* +query(ConfigQuery query)+ allows to apply a function returning any kind of result based on a + +Configuration+ instance. Queries are used for accessing/deriving any kind of data based on of a +Configuration+ + instance, e.g. accessing a +Set<String>+ of root keys present. + +Both interfaces hereby are functional interfaces. Because of backward compatibility with Java 7 we did not use ++UnaryOperator+ and +Function+ from the +java.util.function+ package. Nevertheless usage is similar, so you can +use Lambdas and method references in Java 8: + +[source,java] +.Applying a +ConfigurationQuery+ using a method reference +-------------------------------------------- +ConfigSecurity securityContext = ConfigurationProvider.getConfiguration().query(ConfigSecurity::targetSecurityContext); +-------------------------------------------- + +NOTE: +ConfigSecurity+ is an arbitrary class only for demonstration purposes. + + +Operator calls basically look similar: + +[source,java] +.Applying a +ConfigurationOperator+ using a lambda expression: +-------------------------------------------- +Configuration secured = ConfigurationProvider.getConfiguration() + .with((config) -> + config.get("foo")!=null?; + FooFilter.apply(config): + config); +-------------------------------------------- + + +[[ConfigException]] +=== ConfigException + +The class +ConfigException+ models the base *runtime* exception used by the configuration system. + + +[[SPI]] +== SPI + +[[PropertySource]] +=== Interface PropertySource + +We have seen that constraining configuration aspects to simple literal key/value pairs provides us with an easy to +understand, generic, flexible, yet expendable mechanism. Looking at the Java language features a +java.util.Map<String, +String>+ and +java.util.Properties+ basically model these aspects out of the box. + +Though there are advantages in using these types as a model, there are some severe drawbacks, notably implementation +of these types is far not trivial and the collection API offers additional functionality not useful when aiming +for modelling simple property sources. + +To render an implementation of a custom +PropertySource+ as convenient as possible only the following methods were +identified to be necessary: + +[source,java] +-------------------------------------------- +public interface PropertySource{ + int getOrdinal(); + String getName(); + String get(String key); + boolean isScannable(); + Map<String, String> getProperties(); +} +-------------------------------------------- + +Hereby + +* +get+ looks similar to the methods on +Map+. It may return +null+ in case no such entry is available. +* +getProperties+ allows to extract all property data to a +Map<String,String>+. Other methods like +containsKey, + keySet+ as well as streaming operations then can be applied on the returned +Map+ instance. +* But not in all scenarios a property source may be scannable, e.g. when looking up keys is very inefficient, it + may not make sense to iterator over all keys to collect the corresponding properties. + This can be evaluated by calling +isScannable()+. If a +PropertySource+ is defined as non scannable accesses to + +getProperties()+ may not return all key/value pairs that would be available when accessed directly using the + +String get(String)+ method. +* +getOrdinal()+ defines the ordinal of the +PropertySource+. Property sources are managed in an ordered chain, where + property sources with higher ordinals override the ones with lower ordinals. If ordinal are the same, the natural + ordering of the fulloy qualified class names of the property source implementations are used. The reason for + not using +@Priority+ annotations is that property sources can define dynamically their ordinals, e.g. based on + a property contained with the configuration itself. +* Finally +getName()+ returns a (unique) name that identifies the +PropertySource+ within the current + +ConfigurationContext+. + +This interface can be implemented by any kind of logic. It could be a simple in memory map, a distributed configuration +provided by a data grid, a database, the JNDI tree or other resources. Or it can be a combination of multiple +property sources with additional combination/aggregation rules in place. + ++PropertySources+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current + active +ServiceContext+. + + +[[PropertySourceProvider]] +==== Interface PropertySourceProvider + +Instances of this type can be used to register multiple instances of +PropertySource+. + +[source,java] +-------------------------------------------- +// @FunctionalInterface in Java 8 +public interface PropertySourceProvider{ + Collection<PropertySource> getPropertySources(); +} +-------------------------------------------- + +This allows to evaluate the property sources to be read/that are available dynamically. All property sources +are read out and added to the current chain of +PropertySource+ instances within the current +ConfigurationContext+, +refer also to [[ConfigurationContext]]. + ++PropertySourceProviders+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the +current active +ServiceContext+. + + +[[PropertyFilter]] +==== Interface PropertyFilter + +Also +PropertyFilters+ can be added to a +Configuration+. They are evaluated before a +Configuration+ instance is +passed to the user. Filters can hereby used for multiple purposes, such as + +* resolving placeholders +* masking sensitive entries, such as passwords +* constraining visibility based on the current active user +* ... + ++PropertyFilters+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current +active +ServiceContext+. Similar to property sources they are managed in an ordered filter chain, based on the +applied +@Priority+ annotations. + +A +PropertyFilter+ is defined as follows: + +[source,java] +-------------------------------------------- +// Functional Interface +public interface PropertyFilter{ + String filterProperty(String value, FilterContext context); +} +-------------------------------------------- + +Hereby: + +* returning +null+ will remove the key from the final result +* non null values are used as the current value of the key. Nevertheless for resolving multi-step dependencies + filter evaluation has to be continued as long as filters are still changing some of the values to be returned. + To prevent possible endless loops after a defined number of loops evaluation is stopped. +* +FilterContext+ provides additional metdata, inclusing the key accessed, which is useful in many use cases. + +This method is called each time a single entry is accessed, and for each property in a full properties result. + + +[[PropertyValueCombinationPolicy]] +==== Interface PropertyValueCombinationPolicy + +This interface can be implemented optional. It can be used to adapt the way how property key/value pairs are combined to +build up the final Configuration to be passed over to the +PropertyFilters+. The default implementation is just +overriding all values read before with the new value read. Nevertheless for collections and other use cases it is +often useful to have alternate combination policies in place, e.g. for combining values from previous sources with the +new value. Finally looking at the method's signature it may be surprising to find a +Map+ for the value. The basic +value hereby is defined by +currentValue.get(key)+. Nevertheless the +Map+ may also contain additional meta entries, +which may be considered by the policy implementation. + +[source,java] +-------------------------------------------- +// FunctionalInterface +public interface PropertyValueCombinationPolicy{ + + PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR = + new PropertyValueCombinationPolicy(){ + @Override + public Map<String,String> collect(Map<String,String> currentValue, String key, + PropertySource propertySource) { + PropertyValue value = propertySource.get(key); + return value!=null?value.getConfigEntries():currentValue; + } + }; + + String collect(Map<String,String> currentValue currentValue, String key, + PropertySource propertySource); + +} +-------------------------------------------- + + +[[ConfigurationContext]] +==== The Configuration Context + +A +Configuration+ is basically based on a so called +ConfigurationContext+, which is +accessible from +Configuration.getContext()+: + +[source,java] +.Accessing the current +ConfigurationContext+ +-------------------------------------------- +ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext(); +-------------------------------------------- + +The +ConfigurationContext+ provides access to the internal building blocks that determine the final +Configuration+: + +* +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances). +* +PropertyFilters+ registered, which filter values before they are returned to the client +* +PropertyConverter+ instances that provide conversion functionality for converting String values to any other types. +* the current +PropertyValueCombinationPolicy+ that determines how property values from different PropertySources are + combined to the final property value returned to the client. + + +[[Mutability]] +==== Changing the current Configuration Context + +By default the +ConfigurationContext+ is not mutable once it is created. In many cases mutability is also not needed +or even not wanted. Nevertheless there are use cases where the current +ConfigurationContext+ (and +consequently +Configuration+) must be adapted: + +* New configuration files where detected in a folder observed by Tamaya. +* Remote configuration, e.g. stored in a database or alternate ways has been updated and the current system must + be adapted to these changes. +* The overall configuration context is manually setup by the application logic. +* Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the + tests executed. + +In such cases the +ConfigurationContext+ must be mutable, meaning it must be possible: + +* to add or remove +PropertySource+ instances +* to add or remove +PropertyFilter+ instances +* to add or remove +PropertyConverter+ instances +* to redefine the current +PropertyValueCombinationPolicy+ instances. + +This can be achieved by obtaining an instance of +ConfigurationContextBuilder+. Instances of this builder can be +accessed either + +* from the current +ConfigurationContext+, hereby returning a builder instance preinitialized with the values from the + current +ConfigurationContext+ +* from the current +ConfigurationProvider+ singleton. + +[source,java] +.Accessing a +ConfigurationContextBuilder+ +-------------------------------------------- +ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext().toBuilder(); +ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder(); +-------------------------------------------- + +With such a builder a new +ConfigurationContext+ can be created and then applied: + +[source,java] +.Creating and applying a new +ConfigurationContext+ +-------------------------------------------- +ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext() + .toBuilder(); +ConfigurationContext context = preinitializedContextBuilder.addPropertySources(new MyPropertySource()) + .addPropertyFilter(new MyFilter()).build(); +ConfigurationProvider.setConfigurationContext(context); +-------------------------------------------- + +Hereby +ConfigurationProvider.setConfigurationContext(context)+ can throw an +UnsupportedOperationException+. +This can be checked by calling the method +boolean ConfigurationProvider.isConfigurationContextSettable()+. + + +[[ConfigurationProviderSpi]] +==== Implementing and Managing Configuration + +One of the most important SPI in Tamaya if the +ConfigurationProviderSpi+ interface, which is backing up the ++ConfigurationProvider+ singleton. Implementing this class allows + +* to fully determine the implementation class for +Configuration+ +* to manage the current +ConfigurationContext+ in the scope and granularity required. +* 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 + +The +ServiceContext+ is also a very important SPI, which allows to define how components are loaded in Tamaya. +The +ServiceContext+ hereby defines access methods to obtain components, whereas itself it is available from the ++ServiceContextManager+ singleton: + +[source,java] +.Accessing the +ServiceContext+ +-------------------------------------------- +ServiceContext serviceContext = ServiceContextManager.getServiceContext(); + +public interface ServiceContext{ + int ordinal(); + <T> T getService(Class<T> serviceType); + <T> List<T> getServices(Class<T> 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 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<String,String>*, 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.get("all.size.limit", int.class); +-------------------------------------------- + + +### Environment and System Properties + +By default environment and system properties are included into the _Configuration_. So we can access the current +_PROMPT_ environment variable as follows: + +[source,java] +-------------------------------------------- +String prompt = ConfigurationProvider.getConfiguration().get("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.getConfiguration().get("use.my.system.answer", boolean.class); +-------------------------------------------- + + +### Adding a Custom Configuration + +Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the +_tamaya-spi-support_ module you just have to perform a few steps: + +. Define a PropertySource as follows: + +[source,java] +-------------------------------------------- + public class MyPropertySource extends PropertiesResourcePropertySource{ + + public MyPropertySource(){ + super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"), DEFAULT_ORDINAL); + } + } +-------------------------------------------- + +Then register +MyPropertySource+ using the +ServiceLoader+ by adding the following file: + +[source,listing] +-------------------------------------------- +META-INF/services/org.apache.tamaya.spi.PropertySource +-------------------------------------------- + +...containing the following line: + +[source,listing] +-------------------------------------------- +com.mypackage.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-site/blob/3d91bad5/content/community.adoc ---------------------------------------------------------------------- diff --git a/content/community.adoc b/content/community.adoc new file mode 100644 index 0000000..a3219f7 --- /dev/null +++ b/content/community.adoc @@ -0,0 +1,143 @@ +// +// 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: Community + +:sectnums: + +// Document properties +:twitterhandle: tamayaconf + +== Users + +If you are a new user and you would like to participate in Tamaya +(would be great!), you can have a look at the current +project documentation. Apache Tamaya currently does +not yet have a users mailing list. If you want discuss your use cases +we encourage you to mailto:[email protected][subscribe] +to our mailto:[email protected][mailing list for developers]. +Furthermore, you can check our xref:a_mailing_lists[mail-archives]. + +Before you file a ticket in our https://issues.apache.org/jira/browse/TAMAYA[Jira^] +please ask on the mailing list if it's a known issue in case of a +bug or if there is an ongoing discussion in case of a feature. + +You are very welcome to follow our twitter account +http://twitter.com/{twitterhandle}[@{twitterhandle}^] and spread the word +of Tamaya with tweets, blog entries,... + +== Getting Involved + +Everybody is welcome to get involved with our community. You can find general +information at http://apache.org/foundation/getinvolved.html and +http://apache.org/foundation/how-it-works.html. +The following sections provides some details about the different levels of getting involved. + +If you want to contribute to the +documentation of Apache Tamaya, please +read the instructions about the Documentation +that addresses how to contribute, render and publish it. + + +=== Contributors + +Before you get a committer you have to contribute to our effort. +E.g. you can help users, participate in discussions on the dev list, +submit patches,... . Therefore, it's essential to file +a http://www.apache.org/licenses/icla.txt[Individual Contributor License Agreement (ICLA)^] +or http://www.apache.org/licenses/cla-corporate.txt[Software Grant and Corporate Contributor License Agreement (CCLA)^] +and send it to secretary at apache dot org (or fax it) as early as possible. + +If you would like to submit a patch through Jira, you can have a look at the +link:devguide.html[suggested Git approach]. + +The lists of current contributors and committers can be found +on the link:team-list.html[team and contributers page^]. + + +=== Committers + +Before you read this section, please ensure that you have read +the contributor section. All of you are welcome to join our development effort. +mailto:[email protected][Subscribe] to our +mailto:[email protected][mailing list for developers] and +start contributing and help users. + +// todo Fix the link when finishing the new homepage, Oliver B. Fischer, 2015-09-12 +Optionally mailto:[email protected][subscribe] to our +mailto:[email protected][mailing list for commits]. +Furthermore, you can check our link:community.html#mailing-lists[mail-archives]. + +Further details are available at http://www.apache.org/dev/[http://www.apache.org/dev/^]. + +=== Mailing lists + +The table below lists all mailings used by the Tamaya project. + +[width="70"] +[cols="5*.<", options="header"] +|=== +| List +| Subscribe +| Unsubscribe +| Archive +| Mirrors +//-- next row +| Developer List +| mailto:[email protected][Subscribe] +| mailto:[email protected][Unsubscribe] +| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-dev/[Archive^] +| +//-- next row +| Committer List +| mailto:[email protected][Subscribe] +| mailto:[email protected][Unsubscribe] +| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-commits/[Archive^] +| +|=== + +=== JIRA + +Any kind of issue has to be filed in our +https://issues.apache.org/jira/browse/TAMAYA[issue tracker^]. +If you have any question, you can ask us +(e.g. via the mailing list for developers). + +=== Spread the word + +You are very welcome e.g. to write blog entries, mention our twitter handle + @{twitterhandle} if you tweet about the project or just follow our twitter +account http://twitter.com/{twitterhandle}[@{twitterhandle}^] + +=== IRC + +Usually discussions happen on the mailing list. Some informal discussions take +place in our IRC-Channel irc://irc.freenode.net/apache-tamaya. + +---- +// with the irssi command-line client: +$ irssi + +> /connect irc.freenode.net +> /join #apache-tamaya +---- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/core.adoc ---------------------------------------------------------------------- diff --git a/content/core.adoc b/content/core.adoc new file mode 100644 index 0000000..fe891b2 --- /dev/null +++ b/content/core.adoc @@ -0,0 +1,228 @@ +// 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 + +[[Core]] +== Tamaya Core Implementation +=== Overview + +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+ 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+. + +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 +* configuration injection and configuration templates +* abstraction for reusable formats +* integration with other existing solutions +* configuration and configuration isolation targeting Java EE +* dynamic configuration and configuration updates +* Configuration management extensions +* remote configuration +* and more + +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 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"] +|======= +|_Target Type_ |_Class Name_ |_Supported Formats_ +|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF +|java.math.BigInteger |BigIntegerConverter |0xFF, 1234 +|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0 +|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123 +|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123 +|java.ui.lang.Class |ClassConverter |<fully qualified class name> +|java.util.Currency |CurrencyConverter |CHF, 123 +|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE +|_Enums_ |EnumConverter |<Enum item name> +|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE +|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE +|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String) +|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String) +|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)> +|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE +|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY +|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE +|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true +|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true +|ZoneId |ZoneIdConverter |Europe/Zurich +|======= + + +=== Registering PropertyConverters + +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: API Implementations can be read-only thus not allowing adding additional converters programmatically. + + +[[ComponentLoadingAndPriorization]] +=== Component Loading and Priorization + +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/<myInterfaceName>+ 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 +core adds this functionality by the possibility to add +@Priority+ annotations to the components registered. +By default, and if no annotation is added +0+ is used as priority. Hereby higher values preceed lower values, meaning + +* if a singleton component is accessed from the current +ServiceContext+ the component with the higher value + effectively _overrides/replaces_ any component with lower values. +* if a collection of components is obtained from the +ServiceContext+ the components are ordered in order, where the + ones with higher priority are before components with lower priority. +* if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is + still defined and predictable in almost all scenarios. + + +[[RegisteringPropertySources]] +=== Registering Property Sources + +PropertySources that provide configuration properties are registered as ordinary components as described in the previous +section. Nevertheless the priority is not managed based on +@Priority+ annotations, but based on an explicit ++int getOrdinal()+ method. This allows to define the ordinal/priority of a +PropertySource+ explicitly. This is useful +due to several reasons: + +* it allows to define the ordinal as part of the configuration, thus allowing new overriding property sources being + added easily. +* it allows to define the ordinal dynamically, e.g. based on the configuration location, the time of loading or + whatever may be appropriate. + + +[[CorePropertySources]] +== Configuration Setup in Core + +Tamaya Core provides a minimal configuration setting, that allows you to configure SE +applications already easily. Basically configuration is built up by default as follows: + +. Read environment properties and add them prefixed with +env.+ +. Read all files found at +META-INF/javaconfiguration.properties+ + and +META-INF/javaconfiguration.xml+ + + +=== 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+ and ++org.apache.tamaya.core.provider+: + +[width="100%",frame="1",options="header",grid="all"] +|======= +|_Type_ |_Class Name_ |_Ordinal Used_ +|META-INF/javaconfiguration.properties |JavaConfigurationProvider |0 +|META-INF/javaconfiguration.xml |JavaConfigurationProvider |0 +|Environment Properties |EnvironmentPropertySource |300 +|System Properties |SystemPropertySource |400 +|======= + + +=== Abstract Class PropertiesFilePropertySource + +The abstract class +PropertiesFilePropertySource+ can be used for implementing a +PropertySource+ based on a +URL+ +instance that points to a +.properites+ file. It requires a +URL+ to be passed on the constructor: + +[source,java] +-------------------------------------------- +PropertiesFilePropertySource(URL url); +-------------------------------------------- + + +==== Abstract Class PropertiesPropertySource + +The abstract class +PropertiesPropertySource+ can be used for implementing a +PropertySource+ based on a +Properties+ +instance. It requires a +PropertySource+ to be passed on the constructor: + +[source,java] +-------------------------------------------- +PropertiesPropertySource(Properties properties); +-------------------------------------------- + + +==== Abstract Class BasePropertySource + +The abstract class +BasePropertySource+ can be used for implementing custom +PropertySource+ classes. It requires only +one method to implemented: + +[source,java] +.Implementing a PropertySource using BasePropertySource +-------------------------------------------- +public class MyPropertySource extends BasePropertySource{ + + public String getName(){ + // return a unique name for the property source, e.g. based on the underlying resource. This name also + // allows to access the property source later + } + + public Map<String, String> getProperties(){ + // Get a map with all properties provided by this property source + // If the property source is not scannable, the map returned may be empty. + // In the ladder case the +boolean isScannale()+ must be overridden, since + // by default property sources are assumed to be scannable. + } + +} +-------------------------------------------- + +By default the ordinal of the property sources will be 1000, unless the key +tamaya.ordinal+ asdefined in ++PropertySource.TAMAYA_ORDINAL+ is present in the current +PropertySource+. Of course it is also possible to override +the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, or directly +int getOrdinal()+. + + +[[CorePropertySourceProviders]] +=== Default PropertySourceProvider in Core + +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+ +and +META-INF/javaconfiguration.xml+. + + +[[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 further 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:extensions.html[extensions documentation]. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/devguide.adoc ---------------------------------------------------------------------- diff --git a/content/devguide.adoc b/content/devguide.adoc new file mode 100644 index 0000000..6d28edc --- /dev/null +++ b/content/devguide.adoc @@ -0,0 +1,213 @@ +// 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: Development Guide + +== Suggested Git Workflows + +=== Avoid git pull! + +`git pull` should never get invoked if you have dirty files lying around +or if your branch is ahead of master. This will always lead to +some dirty artifacts in the commit history: + +---- +Merge branch 'master' of http://git-wip-us.apache.org/tamaya into master +---- + +=== Use git pull --rebase + +An easy version for getting rid of the auto-merges is using + +---- +$ git pull --rebase +---- + +Please note that this sometimes trashes your working tree if there +are unmergeable files around. Cleaning this up with a forced manual +rebase is not something we would recommend for a git beginner. + +=== Working in an own branch + +This is actually the suggested way to prevent auto-merges. Create an own +branch where you do your feature work. Either do all your work in one +branch or create one branch per feature you are working on. + +---- +$ git branch mybranch +---- + +After you finished your feature, first add (`git add`) and commit (`git commit`) your work. +Check with `git status` that you don't have any dirty files and uncommitted +changes around. You can use `git stash` to 'backup' unfinished work. + +Then switch back to the master branch and pull changes +done by other committers in the meantime. + +---- +$ git checkout master +$ git pull --rebase +---- + +You should now get all the changes done by other committers and +the will get applied to your local master branch. Now go back to +your private branch and rebase your locally performed work to the HEAD of master. + +---- +$ git checkout mybranch +$ git rebase master +---- + +If you got conflicts, you will get lines with ">>>>" added to those +files. Resolve those conflicts manually, add them and finish the rebase. + +Check with `git-status` and `gitk` if the merge went well and the history now contains your changes. +If all is well, go back to the master branch and merge your changes in. + +---- +$ git pull --rebase // (just for safety, you should see no changes) +$ git checkout master +$ git merge mybranch +---- + +Finally you can push your changes to the ASF git repo + +---- +$ git push +---- + +[[contributing-workflow]] +== Contribution workflow + +=== Creating patches + +You should use the following workflow, if you plan to contribute +patches or new features to Tamaya. + +First update you local copy of the repository: + +---- +$ git checkout master +$ git pull --rebase +---- + +Then create a new local branch for your work. It's good practice to name +it after the corresponding JIRA issue. + +---- +$ git checkout -b TAMAYA-XXX +---- + +Now you can start to work on your patch. When you are finished, commit your changes. But don't forget to **add the name +of the JIRA issue to the commit message**. + +---- +$ git add -am "TAMAYA-XXX: Fixed some issue" +---- + +For small patches we recommend to do a single commit containing your changes. For larger contributions you should try +to group your work into separate sub-tasks that you can commit one by one. + +Before you create your patch you should make sure that your local repository is up to date with the master repository. +This is very important especially if you work on your branch for a long time. Use the following commands to pull the +latest changes from the upstream repository and rebase your branch against the current master. + + +---- +$ git checkout master +$ git pull --rebase +$ git checkout TAMAYA-XXX +$ git rebase master +---- + +Now you are ready to create your patch: + +---- +$ git checkout TAMAYA-XXX +$ git format-patch --stdout master > ../TAMAYA-XXX.patch +---- + +Please attach the resulting patch file to the correspoding JIRA issue. + +=== Applying patches + +If you are a committer and want to apply a patch you should do so in a separate branch. + +---- +$ git checkout -b TAMAYA-XXX +---- + +Then apply the patch using `git am` and rebase it against the master branch. + +---- +$ git am < ../TAMAYA-XXX.patch +$ git rebase master +---- + +After reviewing the changes and testing the code, the changes are ready to +be merged into the master branch: + +---- +$ git checkout master +$ git merge TAMAYA-XXX +$ git branch -d TAMAYA-XXX +---- + +=== Discussion workflow (optional) + +All discussions which lead to a decision take place on the mailing list. +Sometimes it's required to show-case an idea esp. if the solution is +more than few lines. As shown above it makes sense to use local branches +for developing new parts. Git allows to push such local branches to a +public repository. So it's easier to share it with the community +for discussing it. The following listings show an example in combination +with GitHub - for sure it works with any hosting platform like BitBucket, +Google-Code,... The only important part here is that such branches +*NEVER* get pushed to the main Apache repository to keep the commit history +as clean as possible. + +=== Initial setup + +---- +$ git clone https://git-wip-us.apache.org/repos/asf/incubator-tamaya.git +$ git remote add discuss https://[username]@github.com/[username]/[repo-name].git +$ git push -u discuss master +---- + +=== Branches for discussions + +---- +$ git checkout -b TAMAYA-XXX # 1-n commits +$ git push discuss TAMAYA-XXX # share the link to the branch for the discussions +---- + +*If the community agrees on the suggested change, the implementation will be applied to the origin master. A committer +has to follow the steps described above for the basic workflow to keep the commit history simple, clean and straight. +A contributor has to follow the steps described above for creating a patch.* + +=== Delete the branch again + +---- +$ git push discuss :TAMAYA-XXX +$ git branch -d TAMAYA-XXX +---- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/download.adoc ---------------------------------------------------------------------- diff --git a/content/download.adoc b/content/download.adoc new file mode 100644 index 0000000..37e8c98 --- /dev/null +++ b/content/download.adoc @@ -0,0 +1,109 @@ +// 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 + +:sectnums: yes +:linkattrs: true + += Apache Tamaya: Download + +The latest release is Apache Tamaya {tamaya_version_released}. +You can download it it from the +http://www.apache.org/dist/incubator/tamaya[Apache Software Foundation Distribution Directory^]. + +The release notes for each release of Apache Tamaya +can be found at the link:history.html[release history page]. + +== Current Source Code + +Downloading of the the current state of the project can be done by + +* cloning the https://github.com/apache/incubator-tamaya[GitHub mirror^] +* Github also provides an easy way to dowload the current project source as zip archive. +// @todo * Cloning the Apache source tree, see link:3[source section]. source.html + + +== Maven Dependencies + +// @todo +// @todo Details are available <a href="documentation/#_project_configuration_without_maven">here</a>. + + +// @todo Source highlighting does not work currently. +// +[source,xml,subs="verbatim,attributes"] +---- +<dependency> + <groupId>{tamaya_mvn_group_id}</groupId> + <artifactId>tamaya-api</artifactId> + <version>{tamaya_version_released}</version> +</dependency> +<dependency> + <groupId>{tamaya_mvn_group_id}</groupId> + <artifactId>tamaya-core</artifactId> + <version>{tamaya_version_released}</version> +</dependency> +---- + + +== Previous Releases + +All previous releases can also be found at the +http://www.apache.org/dist/incubator/tamaya/[Apache Software Foundation Distribution Directory^]. +In our link:history.html[release history overview] you can find all previous releases of Tamaya. + +== Verifying Releases + +It is essential that you verify the integrity of any downloaded files using +the PGP or MD5 signatures. For more information on signing artifacts and +why we do it, check out the +http://www.apache.org/dev/release-signing.html[Release Signing FAQ^]. + +The PGP signatures can be verified using PGP or GPG. First download the +http://www.apache.org/dist/incubator/tamaya/KEYS[KEYS file^] +as well as the asc signature file for the artifact. Make sure you get +these files from the +http://www.apache.org/dist/incubator/tamaya/[main distribution directory^] +rather than from a +http://www.apache.org/dyn/closer.cgi/tamaya/[mirror^]. +Then verify the signatures using e.g.: + +[source,shell] +---- +$ pgpk -a KEYS +$ pgpv tamaya-project-1.2.0-source-release.zip.asc +---- + +or +[source,shell] +---- +$ pgp -ka KEYS +$ pgp tamaya-project-1.2.0-source-release.zip.asc +---- + +or + +[source,shell] +---- +$ gpg --import KEYS +$ gpg --verify tamaya-project-1.2.0-source-release.zip.asc +---- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/examples.adoc ---------------------------------------------------------------------- diff --git a/content/examples.adoc b/content/examples.adoc new file mode 100644 index 0000000..3bc94ef --- /dev/null +++ b/content/examples.adoc @@ -0,0 +1,71 @@ +// 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: Examples + +toc::[] + +== Tamaya Examples + +=== Minimal + +This example shows the basic functionality that is available when Tamaya is used without any further extensions. +It shows how configuration can be added to the classpath and how it can be accessed. + +=== Simple PropertySource + +This example shows how to write and register an additional +PropertySource+ and +PropertySourceProvider+, which is +the SPI to add your own configuration data and locations. For a more advanced example you may also have a look at +the provided default metamodels, e.g. the simple metamodel (currently in the experimental part and not shipped with +the current release). + +=== Resources + +This example shows how resources can be located using ANT-styled paths and this feature can help you to implement ++PropertySourceProvider+ instances that provide configuration for a set of files/folders at a certain (searchable) +location, as provided by the resource extension_. + +=== Resolver + +The resolver example defines a configuration file that illustrates the usage of placeholders that are resolved on +configuration access, as provided by the _resolver extension_. + +=== Injection + +The injection sample shows how to inject configuration into a created object instance, or how to instantiate a proxied +configuration template, which provides a type-safe configuration access mechanism. This functionality is provided +by the _injection extension_. Hereby neither JSR 330 nor 299 are used, so it is pure and minimal SE based +implementation. + +=== FileObserver + +This example shows how the +event extension+ can be used to automatically adapt the current configuration when +the underlying configuration data is changing, e.g. when new configuration is added to a file folder, or removed or +adapted. + +=== Builder + +This example shows how to build a +Configuration+ using a simple pure SE builder API as provided by the +_builder extension_. + +=== Remote + +THe remote example shows a simple setup where parts of the +Configuration+ are read remotedly. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions.adoc ---------------------------------------------------------------------- diff --git a/content/extensions.adoc b/content/extensions.adoc new file mode 100644 index 0000000..93b34b5 --- /dev/null +++ b/content/extensions.adoc @@ -0,0 +1,107 @@ +// 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: Extension Modules + +toc::[] + +=== Mature Extensions + +Mature extensions have a stable API and SPI, similar to the API and Implementations provided. + +[width="100%",frame="1",options="header",grid="all"] +|======= +|_Artifact_ |_Description_ |_Links_ +| | N/A: currently no extensions have reached that maturity level. | - +|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation] +|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation] +|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation] +|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation] +|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation] +|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.html[Documentation] +|======= + + +=== Extensions + +Extensions in _draft state_ are tested well and normally should have rather stable APIs. Nevertheless API changes may +still occurr, but we try to prevent such changes if possible. + +NOTE All extensions currently run on Java 7 as well as on Java 8. + +[width="100%",frame="1",options="header",grid="all"] +|======= +|_Artifact_ |_Description_ |_Links_ +|+org.apache.tamaya.ext:tamaya-builder+ |Provides a fluent-style builder for configurations | link:extensions/mod_builder.html[Documentation] +|+org.apache.tamaya.ext:tamaya-classloader-support+ |Manages Tamaya configuration and services considering classloading hierarchies. |link:extensions/mod_classloader_support.html[Documentation] +|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation] +|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. | link:extensions/mod_filter.html[Documentation] +|+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:extensions/mod_injection.html[Documentation] +|+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation] +|+org.apache.tamaya.ext:tamaya-model+ |Provides support documenting ang validating configuration during runtime. |link:extensions/mod_model.html[Documentation] +|+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation] +|+org.apache.tamaya.ext:tamaya-remote+ |Provides remote configuration support. |link:extensions/mod_remote.html[Documentation] +|+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation] +|+org.apache.tamaya.ext:tamaya-server+ |Lets a Tamaya configuration instance provide scoped configuration as a REST service. |link:extensions/mod_server.html[Documentation] +|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation] +|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation] +|======= + +=== Integrations + +These extensions integrate/bridge Tamayas functionality with other frameworks turning their configuration capabilities +from a sledgehammer to a scalpell: + +[width="100%",frame="1",options="header",grid="all"] +|======= +|_Artifact_ |_Description_ |_Links_ +|+org.apache.tamaya.ext:tamaya-cdi+ | Java EE/standalone compliant CDI integration | link:extensions/mod_cdi.html[Documentation] +|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:extensions/mod_camel.html[Documentation] +|+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation] +|+org.apache.tamaya.ext:tamaya-osgi+ | Integration for OSGI containers. | link:extensions/mod_osgi.html[Documentation] +|+org.apache.tamaya.ext:tamaya-consul+ | Integration with consul clusters. | link:extensions/mod_consul.html[Documentation] +|+org.apache.tamaya.ext:tamaya-etcd+ | Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation] +|======= + + +=== Extensions in Experimental Stage + +Extensions in _experimental mode_ may still be under discussions. API changes may still happen, so use them +very carefully and especially give us feedback, so we can improve them before progressing to _draft_ state. + +[width="100%",frame="1",options="header",grid="all"] +|======= +|_Artifact_ |_Description_ |_Links_ +|+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation] +|+org.apache.tamaya.ext:tamaya-staged+ |Simple configuration extension to add staged config. | link:extensions/mod_metamodel-staged.html[Documentation] +|======= + + +=== Integrations in Experimental Stage + +Integrations in _experimental mode_ may still be under discussions, or may even not compile ! API changes may still happen, so use them +very carefully and especially give us feedback, so we can improve them before progressing to _draft_ state. + +[width="100%",frame="1",options="header",grid="all"] +|======= +|_Artifact_ |_Description_ |_Links_ +|+org.apache.tamaya.ext:tamaya-commons+ |Integration with Apache Commons Configuration. | - +|======= http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_builder.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_builder.adoc b/content/extensions/mod_builder.adoc new file mode 100644 index 0000000..d734fec --- /dev/null +++ b/content/extensions/mod_builder.adoc @@ -0,0 +1,101 @@ +// 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 + +// include::temp-properties-files-for-site/attributes.adoc[] +:jbake-type: page +:jbake-status: published + +[[BuilderCore]] +== Tamaya Builder (Extension Module) +=== Overview + +The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances, +e.g. as follows: + +[source,java] +--------------------------------------------------------------- +ConfigurationBuilder builder = new ConfigurationBuilder(); +// do something +Configuration config = builder.build(); +--------------------------------------------------------------- + +Basically the builder allows to create configuration instances completely independent of the current configuration +setup. This gives you full control on the +Configuration+ setup. + +=== Compatibility + +The module is based on Java 7, so it will run on Java 7 and does +not require Java 8. The +ConfigurationProvider+ +as defined by the API, provides a builder instance for +ConfigurationContext+ +in a similar way. A +Configuration+ can also be created by passing an instance of a +ConfigurationContext+: + + +=== Installation + +To benefit from configuration builder support you only must add the corresponding +dependency to your module: + +[source,xml,subs="verbatim,attributes"] +----------------------------------------------- +<dependency> + <groupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-builder</artifactId> + <version>{tamaya_version_development}</version> +</dependency> +----------------------------------------------- + +=== Supported Functionality + +The builder allows you to add +PropertySource+ instances: + +[source,java] +---------------------------------------------------------------- +ConfigurationBuilder builder = new ConfigurationBuilder(); +builder.addPropertySources(sourceOne).addPropertySources(sourceTwo); +Configuration config = builder.build(); +---------------------------------------------------------------- + +Similarly you can add filters: + +[source,java] +---------------------------------------------------------------- +builder.addPropertyFilters(new MyConfigFilter()); +---------------------------------------------------------------- + +...or +PropertySourceProvider+ instances: + +[source,java] +---------------------------------------------------------------- +builder.addPropertySourceProvider(new MyPropertySourceProvider()); +---------------------------------------------------------------- + +Also the builder module allows to include/exclude any filters and property source already known to the current ++ConfigurationContext+: + +[source,java] +---------------------------------------------------------------- +builder.disableProvidedPropertyConverters(); +builder.enableProvidedPropertyConverters(); + +builder.disableProvidedPropertyFilters(); +builder.enableProvidedPropertyFilters(); + +builder.disableProvidedPropertySources(); +builder.enableProvidedPropertySources(); +---------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/3d91bad5/content/extensions/mod_camel.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_camel.adoc b/content/extensions/mod_camel.adoc new file mode 100644 index 0000000..9d9a60d --- /dev/null +++ b/content/extensions/mod_camel.adoc @@ -0,0 +1,145 @@ +// 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: Integration with Apache Camel +:jbake-type: page +:jbake-status: published + +toc::[] + + +[[Optional]] +== Integration with Apache Camel (Extension Module) +=== Overview + +The Tamaya Camel integration module provides different artifacts which allows integration of Apachae Tamaya +configuration with Apache Camel. + + +=== Compatibility + +The 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-camel</artifactId> + <version>{tamayaVersion}</version> +</dependency> +----------------------------------------------- + + +=== The Extensions Provided + +Camel integration comes basically with three artifacts: + +* A Camel +ResolverFunction+ implementation adding explicit property resolution + (+org.apache.tamaya.integration.camel.TamayaPropertyResolver+). +* A Camel +PropertiesComponent+ implementation, which allows implicitly preconfigures the resolvers from above and + additionally allows using Tamaya configuration as Camel _overrides_ + (+org.apache.tamaya.integration.camel.TamayaPropertiesComponent+). + + +=== Configuring using Camel Java DSL + +Camel integration using Java DSL is basically simple: + +[source, java] +----------------------------------------------- +import org.apache.tamaya.integration.camel.TamayaPropertiesComponent; + +camelContext.addComponent("properties", new TamayaPropertiesComponent()); +----------------------------------------------- + +Given so you can then use +cfg+ or +tamaya+ as prefix for resolving entries with Tamaya as follows: + +[source, java] +----------------------------------------------- +RouteBuilder builder = new RouteBuilder() { + public void configure() { + from("direct:hello1").transform().simple("{{cfg:message}}"); + } +}; +camelContext.addRoutes(builder); +builder = new RouteBuilder() { + public void configure() { + from("direct:hello2").transform().simple("{{tamaya:message}}"); + } +}; +camelContext.addRoutes(builder); +----------------------------------------------- + + +Optionally you can also configure +TamayaPropertiesComponent+ that all currently known Tamaya properties are used +as Camel overrides, meaning they are evaluated prior to all other available resolver functions in the Camel ++PropertiesComponent+: + +[source, java] +----------------------------------------------- +TamayaPropertiesComponent props = new TamayaPropertiesComponent(); +props.setTamayaOverrides(true); +----------------------------------------------- + + +=== Configuring using Camel XML DSL + +Camel integration using XML DSL is basically very similar. You just have to add the +properties+ component as bean +as well. All other configuration parameters (e.g. file URIs are similar supported). In the example code below we +again use Tamaya as the main configuration solutions only using Camel's default behaviour as a fallback: + +[source, xml] +----------------------------------------------- +<beans xmlns="http://www.springframework.org/schema/beans"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd + "> + + <routeContext id="myCoolRoutes" xmlns="http://camel.apache.org/schema/spring";> + <route id="r1"> + <from uri="direct:hello1"/> + <transform> + <simple>{{message}}</simple> + </transform> + </route> + <route id="r2"> + <from uri="direct:hello2"/> + <transform> + <simple>{{cfg:message}}</simple> + </transform> + </route> + <route id="r3"> + <from uri="direct:hello3"/> + <transform> + <simple>{{tamaya:message}}</simple> + </transform> + </route> + </routeContext> + + <bean id="properties" class="org.apache.tamaya.integration.camel.TamayaPropertiesComponent"> + <property name="tamayaOverrides" value="true"/> + </bean> + +</beans> +-----------------------------------------------
