TAMAYA-274 Some minor additions. TAMAYA-353 Some minor additions.
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/7fc31c0a Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/7fc31c0a Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/7fc31c0a Branch: refs/heads/master Commit: 7fc31c0a7af3b6af39b39a7fe997a961ed898d5e Parents: 1c03371 Author: Anatole Tresch <[email protected]> Authored: Mon Nov 5 00:16:15 2018 +0100 Committer: Anatole Tresch <[email protected]> Committed: Mon Nov 5 00:16:15 2018 +0100 ---------------------------------------------------------------------- content/documentation/api.adoc | 366 ++++++++++--------- content/documentation/core.adoc | 66 ++-- content/documentation/extensions.adoc | 4 - .../extensions/mod_classloader_support.adoc | 4 + .../extensions/mod_collections.adoc | 177 ++++++--- .../documentation/extensions/mod_events.adoc | 29 +- .../documentation/extensions/mod_filter.adoc | 14 +- .../documentation/extensions/mod_formats.adoc | 98 +++-- .../documentation/extensions/mod_functions.adoc | 22 +- .../documentation/extensions/mod_injection.adoc | 66 +--- content/documentation/extensions/mod_jndi.adoc | 2 +- .../documentation/extensions/mod_jodatime.adoc | 2 +- content/documentation/extensions/mod_json.adoc | 6 +- .../documentation/extensions/mod_metamodel.adoc | 2 +- .../extensions/mod_microprofile.adoc | 2 +- .../extensions/mod_mutable_config.adoc | 42 +-- .../documentation/extensions/mod_optional.adoc | 2 +- .../documentation/extensions/mod_resolver.adoc | 21 +- .../documentation/extensions/mod_resources.adoc | 17 +- .../documentation/extensions/mod_server.adoc | 36 +- .../extensions/mod_usagetracker.adoc | 25 +- .../extensions/mod_validation.adoc | 2 +- content/documentation/extensions/mod_vertx.adoc | 6 +- content/documentation/extensions/mod_yaml.adoc | 4 +- content/documentation/quickstart.adoc | 38 +- content/documentation/spisupport.adoc | 29 +- 26 files changed, 572 insertions(+), 510 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/api.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/api.adoc b/content/documentation/api.adoc index 9e133fe..56d7b19 100644 --- a/content/documentation/api.adoc +++ b/content/documentation/api.adoc @@ -12,28 +12,32 @@ link:../highleveldesign.html[High Level Design Documentation] == The Tamaya API The API provides the artifacts as described in the link:../highleveldesign.html[High Level Design Documentation], which are: -* The package +org.apache.tamaya+ defines a simple but complete SE *API* for accessing key/value based _Configuration_: +* The package +org.apache.tamaya+ defines a simple but complete SE *API* for accessing _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. + ** +Configuration+ also provides with +current()+ and +current(ClassLoader)+ static access point for + obtaining the current 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 in case non-String types - are accessed. - ** +PropertyConverter+, which defines conversion of configuration values (String) into any required target type. + are accessed. It is especially useful when accessing collections from Tamaya. + ** +PropertyConverter+, which defines conversion of configuration values (one or multiple Strings) into any + required target type. * The package +org.apache.tamaya.spi+ provides interfaces used for extending and/or adapting Tamaya's core functionality, as well as artifacts for creating +Configuration+ instances programmatically: ** _PropertySource:_ is the the interface to be implemented for adding configuration entries. A +PropertySource+ hereby *** is minimalistic and can be implemented in any way. E.g. there is no distiction that - the configuration data provided is managed locally, remotedely. There is even no + the configuration data provided is managed locally, remotely. There is even no requirement that the configuration data is always fully available. Summarizing a +PropertySource+ - *** provides property access for single key/value pairs in _raw_ format (meaning no postprocessing - is applied yet). A single property hereby is modelled as +PropertyValue+, which also includes - its source and additional arbitrary metadata entries. + *** provides property access for property values. A single property value hereby is modelled as +PropertyValue+, + which by default contains a single literal value. Nevertheles Tamaya also supports more complex scenarios + by allowing property values to have children either as array/list type or as named fields. These children + themselves are recursively also modelled by property values. This makes it possible to map also complex + structures such as JSON, XML or YAML data. Finally a property value also may contain additional metadata entries. *** can _optionally_ provide access to a +Map<String,PropertyValue>+, providing all its properties at once. *** defines the default ordinal to be used for establishing the order of significance among all auto-discovered property sources. @@ -42,36 +46,32 @@ The API provides the artifacts as described in the link:../highleveldesign.html[ ** +ConfigurationProviderSpi+ defines the interface to be implemented by the delegating bean that is implementing the +ConfigurationProvider+ singleton. ** +PropertyFilter+ allows filtering of property values prior getting returned to the caller. Filters by default are - registered as global filters, filtering _raw_ values. The final +String+ value of a configuration entry is the - final value after all registered filters have been applied. - ** A +PropertyValueCombinationPolicy+ optionally can be registered to change the logic how key/value - pairs from subsequent property sources in the property source chain are combined to calculate the final - _raw_ value passed over to the filters registered. - ** A +ConfigurationContext+ is the container of all inner components (+PropertySource, PropertyFilter, - PropertyValueCombinationPolicy, PropertyConverter+) required to implement a +Configuration+. Also the ordering + registered as global filters. The final value of a configuration entry is the final value after all registered + filters have been applied. + ** A +ConfigurationContext+ is the container of all components that make up a configuration (+PropertySource, + PropertyFilter, PropertyConverter, MetadataProvider+) required to implement a +Configuration+. Also the ordering of the property sources, filters and converters is defined by the context. - A +ConfigurationContext+ is automatically created on startup collecting and adding all registered artifacts. - Based on this +ConfigurationContext+ the _default_ +Configuration+ is created, which can be accessed from - +ConfigurationProvider.getConfiguration+. + By default a +ConfigurationContext+ is automatically created on first use for each classloader collecting and + adding all registered artifacts. Based on a +ConfigurationContext+ a +Configuration+ can be created. Summarizing a +ConfigurationContext+ contains the ordered property sources, property filters, converters and combination policy used. Once a +ConfigurationContext+ is instanciated a corresponding +Configuration+ instance can be - created easily by calling +ConfigurationProvider.createConfiguration(context)+. - ** Finally Tamaya also supports _programmatically_ creating +Configuration+ instances and using them in your code - as needed. This can be achieved most easily by building a custom +ConfigurationContext+ using a - +ConfigurationContextBuilder+. This builder can be obtained calling +ConfigurationProvider.getConfigurationContextBuilder();+. + created easily using +ConfigurationBuilder+. + ** Whereas the Tamaya's API provides access to automatic configuration resources, it also allows to create + _programmatically_ +Configuration+ instances. This can be achieved using a + +ConfigurationContextBuilder+. This builder can be obtained calling +Configuration.createConfigurationBuilder();+. ** Finally +ServiceContext+ and +ServiceContextManager+ provide an abstraction to the underlying runtime environment, allowing different component loading and lifecycle strategies to be used. This is very useful since component (service) loading in Java SE, Java EE, OSGI and other runtime environments may be differ significantly. In most cases even - extension programmers will not have to deal with these two artifacts. + extension programmers will not have to deal with these internals. [[APIKeyValues]] -=== Key/Value Pairs +=== Key/Value Pairs and More 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. +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 @@ -95,11 +95,38 @@ val = props.getProperty("a.b.c.1"); ... -------------------------------------------- +But we also have more complex configuration mechanism today. For example YAML is widely used format, which also +supports lists and maps. Basically these can be mapped also as key/value pairs. Unfortunately this is not very +useful in some cases: + +* a configuration client want to access a list of server configurations +* a configuration client wants to map structures with named fields. +* both of the above. + +As an example think of a server, which wants to extract a list of all members in the current cluster. Hereby: + +* A member is modelled by a +MembeConfigr+ class, with the fields +serverId, serverName, serverURL+. +* The current members should be accessed as list, as follows: + +[source,java] +---- +List<MemberConfig> members = configuration.get("cluster.members", new TypeLiteral<List<MemberConfig>>(); +---- + +This coud be modelled as property as well, but it is more convenient to let Tamaya have a more flexible model +to represent a configuration internally. This is why a +PropertyValue+ can have one of three flavors: + +. it is a simple literal value. +. it is an object containing none to many child property values as named fields. +. it is an array containing none to many child properties as unnamed array instances. + +Summarizing Tamaya is capable of fully represent the structures described by widely used configuration file formats. + ==== 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: +there are several advantages: * Strings are simple to understand * Strings are human readable and therefore easy to prove for correctness @@ -146,24 +173,36 @@ public interface Configuration{ <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); + <T> Optional<T> getOptional(String key, TypeLiteral<T> type); + <T> Optional<T> getOptional(String key, Class<T> type); Map<String,String> getProperties(); // extension points - Configuration with(ConfigOperator operator); - <T> T query(ConfigQuery<T> query); + Configuration map(UnaryOperator<Configuration> operator); + <T> T adapt(Function<Configuration,T> adapter); ConfigurationContext getContext(); + ConfigurationBuilder toBuilder(); + static Configuration current(); + static Configuration current(ClassLoader classsLoader); + static void setCurrent(Configuration config); + static void setCurrent(Configuration config, ClassLoader classLoader); + static ConfigurationBuilder createConfigurationBuilder(); + + // the deault EMPTY configuration + static Configuration EMPTY{} } -------------------------------------------- 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. +* +map, adapt+ 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+. * +getConfigurationContext()+ allows access to the underlying components of a +Configuration+ instance. +* the +static+ methods allow access for obtaining or changing +Configuration+. The class +TypeLiteral+ is basically similar to the same class provided with CDI: @@ -193,7 +232,8 @@ public class TypeLiteral<T> implements Serializable { -------------------------------------------- -Instances of +Configuration+ can be accessed from the +ConfigurationProvider+ singleton: +Instances of +Configuration+ can be accessed using the +Configuration.current()+ or +Configuration.current(ClassLoader)+ +singleton: [source,java] .Accessing Configuration @@ -237,10 +277,10 @@ We are well aware of the fact that this library will not be able to cover all ki we have added _functional_ extension mechanisms to +Configuration+ that were used in other areas of the Java eco-system (e.g. Java Time API and JSR 354) as well: -* +with(ConfigOperator operator)+ allows to pass arbitrary unary functions that take and return instances of +* +map(UnaryOperator<Configuration> 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 +* +adapt(Function<Configuration,T)+ 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. @@ -249,9 +289,9 @@ Both interfaces hereby are functional interfaces. Because of backward compatibil use Lambdas and method references in Java 8: [source,java] -.Applying a +ConfigurationQuery+ using a method reference +.Applying an Adapter using a method reference -------------------------------------------- -ConfigSecurity securityContext = ConfigurationProvider.getConfiguration().query(ConfigSecurity::targetSecurityContext); +ConfigSecurity securityContext = Configuration.current().adapt(ConfigSecurity::targetSecurityContext); -------------------------------------------- NOTE: +ConfigSecurity+ is an arbitrary class only for demonstration purposes. @@ -262,7 +302,7 @@ Operator calls basically look similar: [source,java] .Applying a +ConfigurationOperator+ using a lambda expression: -------------------------------------------- -Configuration secured = ConfigurationProvider.getConfiguration() +Configuration secured = Configuration.current() .with((config) -> config.get("foo")!=null?; FooFilter.apply(config): @@ -280,7 +320,7 @@ The class +ConfigException+ models the base *runtime* exception used by the conf == SPI [[PropertyValue]] -=== PropertyValue, PropertyValueBuilder +=== PropertyValue On the API properties are represented as Strings only, whereas in the SPI value are represented as +ProeprtyValue+, which contain @@ -289,6 +329,7 @@ which contain * the property's _value_ (String) * the property's _source_ (String, typically equals to the property source's name) * any additional meta-data represented as _Map<String,String>_ +* named or unnamed child objects, arrays or text filters.s This helps to kepp all value relevant data together in one place and also allows to choose any kind of representation for meta-data entries. The +PropertyValue+ itself is a final and _serializable_ data container, @@ -299,36 +340,33 @@ which also has a powerful builder API (e.g. for using within filters): public final class PropertyValue implements Serializable{ [...] - public static PropertyValue of(String key, String value, String source); + public static ObjectValue createObject(){ + public static ListValue createList(){ + public static PropertyValue createValue(String key, String value){ + public static ListValue createList(String key){ + public static ObjectValue createObject(String key) + + public final boolean isImmutable(); + public PropertyValue immutable(); + public PropertyValue mutable(); + public final ValueType getValueType(); public String getKey(); + public String getQualifiedKey(); public String getSource(); public String getValue(); + public PropertyValue setValue(String value); public Map<String, String> getMetaEntries(); public String getMetaEntry(String key); public PropertyValueBuilder toBuilder(); - public static PropertyValueBuilder builder(String key, String source); - public static PropertyValueBuilder builder(String key, String value, String source); - - /** - * Maps a map of {@code Map<String,String>} to a {@code Map<String,PropertyValue>}. - * @param config the String based map, not null. - * @param source the source name, not null. - * @return the corresponding value based map. - */ + public final PropertyValue getParent(); + public final int getVersion(); + public final boolean isRoot(); + public final boolean isLeaf(); public static Map<String,PropertyValue> map(Map<String, String> config, String source); - - /** - * Maps a map of {@code Map<String,String>} to a {@code Map<String,PropertyValue>}. - * @param config the String based map, not null. - * @param source the source name, not null. - * @param metaData additional metadata, not null. - * @return the corresponding value based map. - */ public static Map<String,PropertyValue> map(Map<String, String> config, String source, Map<String,String> metaData); -} ---------------------------------------------------------------- When writing your own datasource you can easily create your own +PropertyValues+: @@ -455,7 +493,7 @@ A +PropertyFilter+ is defined as follows: [source,java] -------------------------------------------- -// Functional Interface +@FunctionalInterface public interface PropertyFilter{ PropertyValue filterProperty(PropertyValue value, FilterContext context); } @@ -472,113 +510,71 @@ Hereby: 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 is purely optional and can be used to adapt the way how property key/value pairs are combined to -build up the final configuration _raw_ value 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 -more intelligent logic is required. - -[source,java] --------------------------------------------- -// FunctionalInterface -public interface PropertyValueCombinationPolicy{ - - PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR = - new PropertyValueCombinationPolicy(){ - @Override - public PropertyValue collect(PropertyValue currentValue, String key, - PropertySource propertySource) { - PropertyValue value = propertySource.get(key); - return value!=null?value:currentValue; - } - }; - - PropertyValue collect(PropertyValue currentValue, String key, - PropertySource propertySource); - -} --------------------------------------------- - -Looking at the +collect+ method's signature, returning a +PropertyValue+ allows also to filter/combine/use meta entries. - - [[ConfigurationContext]] ==== The Configuration Context -A +Configuration+ is created from a +ConfigurationContext+. Each +Configuration+ instance provides it's underlying -context by +Configuration.getContext()+: +A +Configuration+ is created based on a +ConfigurationContext+, which ia accessible calling ++configuration.getContext()+: [source,java] -.Accessing the current +ConfigurationContext+ +.Accessing the +ConfigurationContext+ of a configuration -------------------------------------------- Configuration config = ...; ConfigurationContext context = config.getContext(); -------------------------------------------- -The +ConfigurationContext+ provides access to the internal artifacts that determine the +Configuration+ and -also defines the ordering of the property sources, filters and converters contained: +The +ConfigurationContext+ provides access to the internal artifacts that determine the +Configuration+. +Similarly the context also defines the ordering and significance of property sources, filters and +converters: * +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 - -A +ConfigurationContext+ is not mutable once it is created. In many cases mutability is also not needed. Nevertheless -there are use cases where the current +ConfigurationContext+ (and -consequently +Configuration+) must be adapted: +==== Changing a Configuration -* 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. +A +Configuration+ is basically not mutable. Nevertheless when the containing property sources provide different +values, e.g. because a configuration file has been updated, also the configuration values may change +(dependiing on the significance of the changed property source). -In such cases the +ConfigurationContext+ may change, meaning it must be possible: +Nevertheless it is also possible to create a new +ConfigurationBuilder+ based on an existing configuration +and add/remove property sources, filters or converters as needed. -* to add or remove +PropertySource+ instances -* to add or remove +PropertyFilter+ instances -* to add or remove +PropertyConverter+ instances -* to redefine the current +PropertyValueCombinationPolicy+ instances. +A new configuration builder can be easily accessed from an existing configuration as follows: -This is nothing new, a +ConfigurationContextBuilder+ already allows us to achive this. So we must only ensure that -we can easily create a new +ConfigurationContextBuilder+ using a given +ConfigurationContext+ as input. This can be -done by +[source,java] +.Accessing a +ConfigurationContextBuilder+ +-------------------------------------------- +Configuration config = ...; +ConfigurationBuilder preinitializedConfigBuilder = config.toBuilder(); +-------------------------------------------- -* calling +ConfigurationContext.toBuilder()+, hereby returning a builder instance preinitialized with the values from the - current +ConfigurationContext+. -* calling +ConfigurationProvider.getConfigurationContextBuilder()+ and then applying the current +ConfigurationContext+ - by calling +setContext(ConfigurationContext)+ on the +ConfigurationContextBuilder+ instance. +It is also possible to builkd up a configuration completely from scratch, having full control on the +resources included: [source,java] .Accessing a +ConfigurationContextBuilder+ -------------------------------------------- -ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext().toBuilder(); -ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder(); +ConfigurationBuilder emptyConfigBuilder = Configuration.createConfigurationBuilder(); -------------------------------------------- -Finally when we are finished a new +ConfigurationContext+ can be created: +Using the builder we then can change the configuration as needed: [source,java] -.Creating and applying a new +ConfigurationContext+ -------------------------------------------- -ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext() - .toBuilder(); - .addPropertySources(new MyPropertySource()) - .addPropertyFilter(new MyFilter()) - .build(); +ConfigurationBuilder builder = Configuration.crteateConfigurationBuilder(); +builder.addPropertySources(new MyPropertySource()) + .addPropertyFilter(new MyFilter()) + .setMeta("a.b.c.collectionType", "List") + .build(); -------------------------------------------- -But let's also have a deeper look at what functionality a +ConfigurationContextBuilder+ provides. Basically such a + +Let's have a short look at the +ConfigurationBuilder+. Basically such a builder allows to add, remove or reorder property sources, converters and filters or changing any other aspect -of a +ConfigurationContext+: +of a +Configuration+. Finally a new +Configuration+ instance can be built. [source,java] .Chain manipulation using +ConfigurationContextBuilder+ @@ -593,41 +589,37 @@ builder.decreasePriority(propertySource); builder.sortPropertyFilters(MyFilterComparator::compare); -------------------------------------------- -Finally if the new +ConfigurationContext+ is ready a new +Configuration+ can be created. -Optionally the new +Configuration+ can also be installed as the new _default_ +Configuration+ -instace as illustrated below: +Finally if a new +Configuration+ can be built. Optionally the new +Configuration+ can also be installed as +the _default_ +Configuration+ instance as illustrated below: [source,java] -.Creating and applying a new +ConfigurationContext+ +.Creating and applying a new +Configuration+ -------------------------------------------- -ConfigurationContext context = builder.build(); - // Creates a new matching Configuration instance -Configuration newConfig = ConfigurationProvider.createConfiguration(context); +Configuration config = builder.build(); // Apply the new context to replace the current configuration: -ConfigurationProvider.setConfiguration(newConfig); +Configuration.setCurrent(newConfig); -------------------------------------------- -Hereby +ConfigurationProvider.setConfiguration(Configuration)+ can throw an +UnsupportedOperationException+. -This can be checked by calling the method +boolean ConfigurationProvider.isConfigurationSettable()+. +Hereby +Configuration.setCurrent(Configuration)+ can throw an +UnsupportedOperationException+. +This can be checked by calling the method +boolean Configuration.isConfigurationSettable()+. +== SPI [[ConfigurationProviderSpi]] -==== Implementing and Managing Configuration +=== Implementing and Managing Configuration One of the most important SPI in Tamaya is 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 +Configuration+ in the scope and granularity required. -* to provide access to the right +Configuration+ based on the current runtime context. -* Performing changes as set with the current +ConfigurationContextBuilder+. ++Configuration+ static accessor methods. Implementing this interface allows -= Interface ConfigurationContextBuilder +* to fully determine the implementation class for +Configuration, ConfigurationBuilder, ConfigurationContext+ +* to manage +Configurations+ in the scope and granularity required. +* to provide access to the right +Configuration+ based on the current runtime context (e.g. classloader). [[BuilderCore]] -== Interface ConfigurationContextBuilder +== Interface ConfigurationBuilder + === Overview The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances, @@ -635,12 +627,12 @@ e.g. as follows: [source,java] --------------------------------------------------------------- -ConfigurationBuilder builder = new ConfigurationBuilder(); +ConfigurationBuilder builder = Configuration.createConfigurationBuilder(); // do something Configuration config = builder.build(); --------------------------------------------------------------- -Basically the builder allows to create configuration instances completely independent of the current configuration +Basically a builder allows to create configuration instances completely independent of the current configuration setup. This gives you full control how and when +Configuration+ is created. @@ -650,12 +642,12 @@ The builder allows you to add +PropertySource+ instances: [source,java] ---------------------------------------------------------------- -ConfigurationContextBuilder builder = ConfigurationProvider.getConfigurationContextBuilder(); +ConfigurationBuilder builder = Configuration.createConfigurationBuilder(); builder.addPropertySources(sourceOne, sourceTwo, sourceThree -Configuration config = ConfigurationProvider.createConfiguration(builder.build()); +Configuration config = builder.build(); ---------------------------------------------------------------- -Hereby the ordering of the propertysources is not changed, regardless of the ordinals provided +Hereby the ordering of the property sources is not changed, regardless of the ordinals provided by the property sources. This allows alternate ordering policies easily being implemented because creating a configuration based on a configuration context is already implemented and provided by the core API. @@ -674,10 +666,11 @@ builder.addPropertyFilters(new MyConfigFilter()); builder.addPropertySourceProvider(new MyPropertySourceProvider()); ---------------------------------------------------------------- +...and of course converters and other artifacts. [[ServiceContext]] -==== The ServiceContext +== The ServiceContext The +ServiceContext+ allows to define how components are loaded in Tamaya. It is the glue layer, which interacts with the underlying runtime system such as Java SE, Java EE, OSGI, VertX etc. @@ -687,32 +680,54 @@ The +ServiceContext+ hereby defines access methods to obtain components, whereas [source,java] .Accessing the +ServiceContext+ -------------------------------------------- +// using an explicit classloader (recommended) +ClassLoader classloader = ...; +ServiceContext serviceContext = ServiceContextManager.getServiceContext(classloader); + +// using the default classloader ServiceContext serviceContext = ServiceContextManager.getServiceContext(); public interface ServiceContext{ int ordinal(); <T> T getService(Class<T> serviceType); + <T> T getService(Class<T> serviceType, Supplier<T> serviceSupplier); + <T> T createService(Class<T> serviceType); + <T> T createService(Class<T> serviceType, Supplier<T> serviceSupplier); <T> List<T> getServices(Class<T> serviceType); + <T> List<T> getServices(Class<T> serviceType, Supplier<List<T>> serviceSupplier); + <T> T register(Class<T> type, T instance, boolean force); + <T> List<T> register(Class<T> type, List<T> instances, boolean force); + + Enumeration<URL> getResources(String resource) throws IOException; + URL getResource(String resource); + } -------------------------------------------- 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 a type. This will return (by default) all instances loadedable from the current - runtime context, ordered by priority (the most significant components added first). +. access as as a single service. Hereby the detected services (if multiple) are sorted by priority and then finally + the most significant instance (the one with the highest priority value) is selected and cached. +. access all items given a type. This will return (by default) all service instances loadedable from the current + runtime context (classloader), ordered by priority (the most significant components added first). +. service lookup can be further customized by passing suppliers. The supplier is called if no default services + could be auto-detected. The supplied instance(s) are registered and cached for subsequent accesses. +. the _register_ methods allow to explcitly register (and optionally override) a service or services + registered. +. Finally the methods `getResource(s)` allow to load resources from the classpath. This is especially useful + when running in an OSGI context, where loading of resources from the classloaders will fail. ## Examples ### Accessing Configuration -_Configuration_ is obtained from the ConfigurationProvider singleton: +_Configuration_ is obtained from the `Configuration` interface using static accessors: [source,java] .Accessing +Configuration+ -------------------------------------------- -Configuration config = ConfigurationProvider.getConfiguration(); +Configuration config = Configuration.current(); +Configuration config = Configuration.current(Thread.currentThread().getContextClassLoader()); -------------------------------------------- Many users in a SE context will probably only work with _Configuration_, since it offers all functionality @@ -721,9 +736,10 @@ very similar to *Map<String,String>*, whereas in Java 8 additionally usage of _O [source,java] -------------------------------------------- -Configuration config = ConfigurationProvider.getConfiguration(); -String myKey = config.get("myKey"); // may return null -int myLimit = config.get("all.size.limit", int.class); +Configuration config = Configuration.current(); +String myValue = config.get("myKey"); // access as (raw) String value. +int myLimit = config.get("all.size.limit", int.class); // access a value using type conversion. +List<URL> urls = config.get("all.urls", new TypeLiteral<List<URL>>(); // access a value using advanced type conversion. -------------------------------------------- @@ -737,7 +753,7 @@ _PROMPT_ environment variable as follows: String prompt = ConfigurationProvider.getConfiguration().get("PROMPT"); -------------------------------------------- -Similary the system properties are directly applied to the _Configuration_. So if we pass the following system +Similary the system properties are directly applied to the _Configuration_. Let's assume, we pass the following system property to our JVM: [source,java] @@ -745,18 +761,18 @@ property to our JVM: java ... -Duse.my.system.answer=yes -------------------------------------------- -we can access it as follows: +We can then access the value from the configuration: [source,java] -------------------------------------------- -boolean useMySystem = ConfigurationProvider.getConfiguration().get("use.my.system.answer", boolean.class); +boolean useMySystem = Configuration.current().get("use.my.system.answer", boolean.class); -------------------------------------------- -### Adding a Custom Configuration +### Adding additional configuration entries -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: +Adding additional configuration entries is simple: just implement an according `PropertySource` and register +it with the Java `ServiceLoader`. Using the _tamaya-spi-support_ extension library you just have to perform a few steps: . Define a PropertySource as follows: @@ -788,5 +804,13 @@ com.mypackage.MyPropertySource [[APIImpl]] == API Implementation -The API is implemented by the +tamaya-core+ module. Refer to the link:core.html[Core documentation] for +The Tamaya configuration API is implemented by the +tamaya-core+ module. Refer to the link:core.html[Core documentation] for further details. + +Furhtermore Tamaya also implements or supports + +* the API as defined by JSR 310 (Config JSR) +* the Microprofile API +* the Spring Configuration Mechanism +* integration with the OSGI `ConfigAdmin` API. +* the Apache Camel Configuration SPI http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/core.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/core.adoc b/content/documentation/core.adoc index f3cac3e..a63e199 100644 --- a/content/documentation/core.adoc +++ b/content/documentation/core.adoc @@ -2,31 +2,27 @@ :jbake-status: published [[Core]] -== Tamaya Core Implementation +== Apache Tamaya: Core Implementation === Overview -Tamaya Core provides an implementation of the link:api.html[Tamaya Configuration API] and adds additional functionality +`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: -* *tamaya-spisupport* provides implementations and base classes for different API artifacts such as +Configuration, - ConfigurationContext, ConfigurationContextBuilder, ConfigurationProviderSpi, BasePropertySource+ and more. It is - built as an independent core module, which also can be used with other implementations. The *tamaya-core* - implementation leverages these base classes to build up a full API implementation. -* A +java.util.ServiceLoader+ based +ServiceContext+ implementation. This allows component priorization based - on the +@Priority+ annotations. -* A +PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances, - thus 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+ implementation (+DefaultConfigurationContextBuilder+) and allows to - change 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 +* A service loader implementation, configurations and further logic required to run + in an OSGI environment. +* Numerous *converters*, including an +EnumConverter+, that is a converter implementation that can automatically select + the currect enumeration values based on a configured entry. +* A configurable `BannerManager`to print Tamaya's start logo on load. + +Basically `tamaya-core` leverages the base implementations contained in Tamaya's SPI support module, so it is quite +small in size. All required components are implemented and registered, so basically the +Core module with its trasitive dependencies (API and spi-support) is a complete configuration solution. Nevertheless +it is also very minimalistic, but fortunately it can be easily extended/accommodated with additional features as needed. + +These extensions are managed in the extensions repository of the Tamaya project. Some of the most commonly used +extensions are * placeholder and resolution mechanisms (+org.apache.tamaya.ext:tamaya-resolver+) * dynamic resource path lookup, e.g. with ant styled patterns (+org.apache.tamaya.ext:tamaya-resources+) @@ -35,18 +31,15 @@ enough to be extended/accommodated with additional features as needed, such as * integration with other existing solutions (e.g. +org.apache.tamaya.ext:tamaya-spring+) * configuration and configuration isolation targeting Java EE (+org.apache.tamaya.ext:tamaya-injection-ee+) * dynamic configuration and configuration updates (+org.apache.tamaya.ext:tamaya-events+) -* remote configuration (+org.apache.tamaya.ext:tamaya-etcd, org.apache.tamaya.ext:tamaya-consul, - org.apache.tamaya.ext:tamaya-hazelcast+) -* and more -For details about the extension modules available and their functionality refer to the link:extensions.html[extension user guide]. +For details about the extension modules available and their functionality refer to the link:extensions.html[extension +user guide]. [[CorePropertyConverters]] === Default PropertyConverters -The _SPI_ base module provides several +PropertyConverter+ implementations, which are automatically registered by the -_Core_ module. Find below the listing of converters automatically registered with the Core module: +The `tamaya-core` module provides several +PropertyConverter+ implementations, which are automatically registered: [width="100%",frame="1",options="header",grid="all"] |======= @@ -59,29 +52,36 @@ _Core_ module. Find below the listing of converters automatically registered wit |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.time.Duration |DurationConverter |<Duration as defined by Duration.parse(String)> +|java.io.File |FileConverter |value -> new File(value) |java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE +|java.time.Instant |InstantConverter |<Instant as defined by Instant.parse(String)> |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.time.LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String) +|java.time.LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)> +|java.time.LocalTime |LocalTimeConverter |<Time as defined by LocalTime.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.time.OffsetDateTime |OffsetDateTimeConverter |<OffsetDateTime as defined by OffsetDateTime.parse(String)> +|java.time.OffsetTime |OffsetTimeConverter |<OffsetTime as defined by OffsetTime.parse(String)> +|java.util.Optional |OptionalConverter | +|java.nio.Path |PathConverter | |java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE +|java.util.Supplier |SupplierConverter | |java.net.URI |URIConverter |http://localhost:2020/testresource?api=true |java.net.URL |URLConverter |http://localhost:2020/testresource?api=true -|ZoneId |ZoneIdConverter |Europe/Zurich +|_Enums_ |EnumConverter |<Enum item name> |======= === Registering PropertyConverters -Additional +PropertyConverters+ can be implemented easily. It is recommended to register them using +Additional +PropertyConverter+ classes can be implemented easily. It is recommended to register them 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 each) to enable auto-discovery. -Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters +Alternatively you can also use a +ConfigurationBuilder+ to add additional converters programmatically. @@ -114,7 +114,7 @@ NOTE: Sorting the property sources based on their ordinal value is only the defa +PropertySource+ implementations that provide configuration properties are registered as components as described in the previous section. Hereby the precedence (ordering) of property sources is not hard-coded. Instead a +Comparator<PropertySource>+ -can be passed to a +ConfigurationContextBuilder+ to perform automatic ordering of the property sources +can be passed to a +ConfigurationBuilder+ to perform automatic ordering of the property sources registered. The default implementation hereby implements the following logic: . It checks for an property entry +tamaya.ordinal+ if present the value is parsed into an +int+ value and used as http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc index 76fc692..098652c 100644 --- a/content/documentation/extensions.adoc +++ b/content/documentation/extensions.adoc @@ -12,7 +12,6 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati [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-collections+ |Collections support. |link:extensions/mod_collections.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] @@ -34,8 +33,6 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati |+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation] |======= -NOTE: The former Tamaya _Builder_ extension module has been removed. The corresponding methods were integrated into -Tamaya's main API's +ConfigurationContextBuilder+ interface. === Extensions Sandbox @@ -43,7 +40,6 @@ Extensions in _draft state_ rather experimental or not yet very mature. API chan and the may also have severe issues or even not work at all. So use at your own risk or join and help us getting them stable and well tested! -NOTE: All extensions currently require Java 8. [width="100%",frame="1",options="header",grid="all"] |======= http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_classloader_support.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_classloader_support.adoc b/content/documentation/extensions/mod_classloader_support.adoc index 50a3e61..6037153 100644 --- a/content/documentation/extensions/mod_classloader_support.adoc +++ b/content/documentation/extensions/mod_classloader_support.adoc @@ -10,6 +10,10 @@ toc::[] Tamaya _Classloader_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details. +CAUTION: Classloader support has been added into the main API and implementation module. This module probably is not + useful anymore and will probably be removed in the future. + + === What functionality this module provides ? The Tamaya _Classloader_ support provides an alternative implementation of +java.util.ServiceLoader+, which is aware http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_collections.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_collections.adoc b/content/documentation/extensions/mod_collections.adoc index 8078d46..8716688 100644 --- a/content/documentation/extensions/mod_collections.adoc +++ b/content/documentation/extensions/mod_collections.adoc @@ -20,7 +20,7 @@ Collections extension adds this functionality to the Tamaya eco-system. === Compatibility -The module is based on Java 8, so it will not run on Java 7 and beyond. +The module requires Java 8. === Installation @@ -64,19 +64,21 @@ my.list.config.entry=1,34454,23,344545,3445 Additionally the module allows adding additional meta-entries, which allows to tweak some of the inner-workings, e.g. -* using your own +PropertyConverter+ implementation for parsing entries. -* specifying a custom separator to split the items (default is {{','}}. -* specifying a custom separator to split key/value pairs when parsing map entries. -* specifying the implementation type of the collection item to be returned. -* specifying the implementation type of the collection to be returned. +* `item-converter`: using a custom +PropertyConverter+ implementation for parsing collection entries. +* `entry-separator`: specifying a custom separator to split the list and map items (default is {{','}}. +* `map-entry-separator`: specifying a custom separator to split key/value pairs when parsing map entries. +* `collection-type`: specifying the implementation type of the collection to be returned. +* `mapping-type`: specifying the implementation type of the collection item to be returned. === Supported Types This module currently supports the following types: +* +java.util.Iterable+ * +java.util.Collection+ * +java.util.List+ * +java.util.ArrayList+ +* +java.util.ArrayList+ * +java.util.LinkedList+ * +java.util.Set+ * +java.util.SortedSet+ @@ -87,17 +89,32 @@ This module currently supports the following types: * +java.util.HashMap+ * +java.util.TreeMap+ -Hereby the collection type is determined by the parameter type accessed, e.g. + +==== Default Collection Type Mapping + +The collection type is determined by the parameter type accessed, e.g. +config.get("mylist", ArrayList.class)+ will always return an +ArrayList+ as result. +* if you have a generic type: + ** an `ArrayList` is returned for `Collection, List, ArrayList, Iterable` + ** a `HashSet` is returned for `Set, HashSet` + ** a `HashMap` is returned for `Map, HashMap` + ** a `TreeMap` is returned for `SortedMap, TreeMap` + ** a `TreeSet` is returned for `SortedSet, TreeSet` +* in all other cases you have to explicitly define the collection type. Hereby you may + omit the `java.util` package. Collection types not contained in `java.util` + require adding an additional converter implementation. NOTE: This means that depending on your use case you can access different collection types based on the same configuration values, as long as their is a +PropertyConverter+ that can convert the _raw configuration value_ to the required target type. +CAUTION: If you do *NOT* use `TypeLiteral` to define your target type, the item target type will not + be available to Tamaya due to Java's type erasure. In this case it will always return `String` + as item type. -==== Configuring the target implementation type +==== Configuring Collection Type Mapping Tamaya Collections allows you to configure the _default_ target collection type by adding the following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part +java.util.+ @@ -106,7 +123,7 @@ can be ommitted: [ source, properties] ----------------------------------------------- mylist=a,b,c -_mylist.collection-type=LinkedList +[META]mylist.collection-type=LinkedList ----------------------------------------------- When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect, so you will still @@ -117,17 +134,32 @@ This mechanism similarly applies to all kind of collections, so you can use it s type returned when accessing +List+, +Map+ or +Collection+. -=== Collecting Configuration Entries instead of Overriding +=== Evaluating Collection Entries + +Tamaya's internal representation of configuration is a modelled by a `PropertyValue`. This class actually supports +different models how configuration data can be represented: -By default Tamaya applies always an overriding +CombinationPolicy+, where only the configuration entry for -the most significant configuration entry is used. In case of collections (and maybe also other use cases), -overriding is not always the mechanism of choice. E.g. when you want to have all entries added to your -configuration to be *combined* to a new entry containing all values provided by any property sources. +. as simple literal key-value pair, or +. as map-like value object, or +. as list-like list object. -Therefore _Tamaya Collections_ also provides a more sophistiated +CombinationPolicy+ (automatically configured) -that allows to adapt the way how configuration entries are combined. All you must do is declaring -the mechanism to be applied by an according _meta-configuration_ parameter, e.g. for +my.list+ your config may -look as follows: +Tamaya's `ConversionContext` actually provides all values matching a given target key. As a consequence there +are four basic algorithms, how a collection can be mapped from entries given: + +* _value_all:_ The list values are identiified by parsing the node value(s) into items, hereby + the items of all values are combined. +* _value:_ The list values are identiified by parsing the node value(s) into items. + Hereby only the items of the most significant config entry are considered. +* _node:_ The list values are identiified by using the node's child value(s) as items. + Hereby only the items of the most significant config entry are considered. +* _node_all:_ The list values are identiified by using the node's child value(s) as items. Hereby + the items of all values are combined. +* _override:_ This policy will try to guess the best _value_ and _node_ evaluation policy for most significant + `PropertyValue`. +* _combine:_ This policy will try to guess the best _value_ and _node_ evaluation policy for each + `PropertyValue` and combine the values to one collection. *This is the default behaviour.* + +As an example consider the following configuration for +my.list+: [source, properties] ----------------------------------------------- @@ -136,23 +168,56 @@ my.list=1,2,3 # from PropertSource 2, with higher precedence my.list=4,5,6 +----------------------------------------------- + +Using the _value_ evaluation policy this would result in the following final property: -# without any additional meta-info these entries would be combined to +[source, properties] +----------------------------------------------- my.list=4,5,6 ----------------------------------------------- -With Tamaya Collections you can now configure the combination policy as follows: +Using the _value_all_ evaluation policy this would result in the following final property: [source, properties] ----------------------------------------------- -# use one of the default policies: override / collect -_my.list.combination-policy=collect +my.list=1,2,3,4,5,6 +----------------------------------------------- -# or use your own custom CombinationPolicy to combine the values -_my.list.combination-policy=com.mycomp.app.MyCombincationPolicy +For the _node_based evaluation policies consider the following YAML input data: + +[source, yaml] ----------------------------------------------- +# from PropertSource 1 +my.list: + - 1 + - 2 + - 3 -So declaring the +collect+ policy the resulting raw output of the entry looks as follows: +# from PropertSource 2, with higher precedence +my.list: + - 4 + - 5 + - 6 +----------------------------------------------- + +In this case the entries are mapped to `ListValue` instances with multiple children. Similar mappings would apply +using JSON or XML configuration formats. In this case it is more useful to collect the child nodes, instead the +values (which basically are `null` on the parent node level). This is excatly what the _node_ and _node_all_ +evaluaion policies are doing. + +With Tamaya Collections you can now configure the evaluation policy using metadata, e.g. when using the default +metadata format of Tamaya: + +[source, properties] +----------------------------------------------- +# use one of the policies: node, node_all, value, value_all, override or collect +[META]my.list.collection-mapping=collect +----------------------------------------------- + +So declaring the +collect+ policy the resulting raw output of the entry looks as illustrated below. Hereby it is even +possible to mix different representations. E.g. it is possible to add additional values in a simple property files, +whereas other values are configured in YAML or other formats: [source, properties] ----------------------------------------------- @@ -160,20 +225,19 @@ So declaring the +collect+ policy the resulting raw output of the entry looks as my.list=1,2,3,4,5,6 ----------------------------------------------- -The customizable policy mechanism of Tamaya Collections also honors the +item-separator+ meta-configuration -parameter explained later in this document. -=== Format of Collection Configuration +=== Item Value Splitting -By default collections are modelled as simple String values, that are tokenized into individual parts using a +When evaluating collections from literal values, these values have to be tokenized into individual parts using a defined +item-separator+ (by default +','+). So a given configuration entry of +1,2,3+ is mapped to +"1","2","3". -If the target context type is something different than String the smae conversion logic is used as when mapping -configuration parameters directly to non-String target types (implemented as +PropertyConverter+ classes, manahed -within the current +ConfigurationContext+. The procedure is identical for all collection types, including +Map+ types, -with the difference that each token in the list is parsed once more for separating it into a +key+ and a +value+. -The default separator for map entries hereby is +"::"+. Map keys, as of now, are always of type +String+, whereas -for values the same logic is applied as for non-map collection types. +If the target context type is something different than String the same conversion logic is used as when mapping +configuration parameters directly to non-String target types (implemented as +PropertyConverter+ classes). +The procedure is identical for all collection types, including +Map+ types, +with the difference that each token for a map is parsed additionally for separating it into a +key+ and a +value+ parts. +The default separator for map entries hereby is +"="+. Map keys, as of now, are always of type +String+, whereas +for values all convertible types are supported. All separator characters can be masked by prefixing them with a `\` +character. [source, properties] ----------------------------------------------- @@ -181,11 +245,11 @@ for values the same logic is applied as for non-map collection types. list=1,2,3,4,5,6 # a map, using the default format -map=a::b, c::d +map=a=b, c=d ----------------------------------------------- -==== Trimming of entries +==== Trimming By default all tokens parsed are trimmed _before_ adding them to the final collection. In case of map entries this is also the case for key/value entries. So the following configuration results in the identical values for @@ -194,15 +258,15 @@ also the case for key/value entries. So the following configuration results in t [source, properties] ----------------------------------------------- # a list, using the default format -list1=1,2,3,4,5,6 +list1=1, 2 ,3,4 , 5,6 list2=1, 2, 3, 4, 5, 6 # a map, using the default format -map1=a::b, c::d -map2=a :: b, c :: d +map1=a =b, c= d +map2=a=b, c = d ----------------------------------------------- -Nevertheless truncation can be controlled by the usage of brackets, e.g. the last list or map entry will have a single +Nevertheless trimming/truncation can be controlled by the usage of brackets, e.g. the last list or map entry will have a single space character as value: [source, properties] @@ -211,7 +275,7 @@ space character as value: list3=1, 2, 3, 4, 5, [ ] # a map, with a ' ' value for key '0' -map3=1 :: a, 2 :: b, 0::[ ] +map3=1 = a, 2 = b, 0=[ ] ----------------------------------------------- Hereby +\[+ escapes the sequence. @@ -219,18 +283,18 @@ Hereby +\[+ escapes the sequence. ==== Customizing the format -The item and entry separators (by default +','+ and +"::"+) can be customized by setting corresponding meta-data -entries as follows, resulting in the same values as in the prevoius listing: +The item and entry separators (by default +','+ and +"="+) can be customized by setting corresponding meta-data +entries, resulting in the same values as in the previous listing: [source, properties] ----------------------------------------------- # a list, with a ' ' value at the end list3=1__2__3__ 4__ 5__[ ] -_list3.item-separator=__ +[META]list3.item-separator=__ # a map, with a ' ' value for key '0' map3=1->a, 2->b, 0->[ ] -_map3.map-entry-separator=-> +[META]map3.map-entry-separator=-> ----------------------------------------------- Of course these settings also can be combined: @@ -239,6 +303,23 @@ Of course these settings also can be combined: ----------------------------------------------- # a reformatted map redefined-map=0==none | 1==single | 2==any -_redefined-map.map-entry-separator=== -_redefined-map.item-separator=| +[META]redefined-map.map-entry-separator=== +[META]redefined-map.item-separator=| +----------------------------------------------- + + +==== Using a custom Converter + +If configuring of item and map item separators as shown above is not sufficient, you still have an option: you can +configure a custom converter to use for converting the given keys. This can be also configured by addinf a corresponding +meta-configuration entry `item-converter`. As you would expect the converter must implement Tamaya's `PropertyConverter` +interface: + +[source, properties] ----------------------------------------------- +# a map using a custom converter +server.0=server1, localhost:8001 +server.1.name=server2, localhost:8000, master=true +server.2=server3, localhost:8003 +[META]server.item-converter=com.mycompany.config.ServerConverter +----------------------------------------------- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_events.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_events.adoc b/content/documentation/extensions/mod_events.adoc index ccba9d1..44b0a94 100644 --- a/content/documentation/extensions/mod_events.adoc +++ b/content/documentation/extensions/mod_events.adoc @@ -27,7 +27,7 @@ change events. === Compatibility -The module is based on Java 7, so it can be used with Java 7 and beyond. +The module is based on Java 8. === Installation @@ -59,7 +59,7 @@ public interface ConfigEvent<T> { long getTimestamp(); } -// @FunctionalInterface +@FunctionalInterface public interface ConfigEventListener { void onConfigEvent(ConfigEvent<?> event); @@ -94,20 +94,23 @@ public final class ConfigEventManager { private ConfigEventManager() {} - public static void addListener(ConfigEventListener l); - public static <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType); - public static void removeListener(ConfigEventListener l); - public static <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType); - public static <T extends ConfigEvent> + public static ConfigEventManager getInstance(); + public static ConfigEventManager getInstance(ClassLoader classLoader); + + public void addListener(ConfigEventListener l); + public <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType); + public void removeListener(ConfigEventListener l); + public <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType); + public <T extends ConfigEvent> Collection<? extends ConfigEventListener> getListeners(); - public static <T extends ConfigEvent> + public <T extends ConfigEvent> Collection<? extends ConfigEventListener> getListeners(Class<T> type); - public static <T> void fireEvent(ConfigEvent<?> event); - public static <T> void fireEventAsynch(ConfigEvent<?> event); + public <T> void fireEvent(ConfigEvent<?> event); + public <T> void fireEventAsynch(ConfigEvent<?> event); - public static void enableChangeMonitoring(boolean enable); - public static boolean isChangeMonitoring(); + public void enableChangeMonitoring(boolean enable); + public boolean isChangeMonitoring(); public long getChangeMonitoringPeriod(); public void setChangeMonitoringPeriod(long millis); @@ -263,7 +266,7 @@ In code freezing is a no-brainer: [source,java] .Freezing the current Configuration -------------------------------------------------- -Configuration config = ConfigurationProvider.getConfiguration(); +Configuration config = Configuration.current(); Configuration frozenConfig = FrozenConfiguration.of(config); -------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_filter.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_filter.adoc b/content/documentation/extensions/mod_filter.adoc index bce6947..a41d187 100644 --- a/content/documentation/extensions/mod_filter.adoc +++ b/content/documentation/extensions/mod_filter.adoc @@ -22,7 +22,7 @@ explicitily no filtering is applied and everything is visible. === Compatibility -The module is based on Java 7, so it will not run on Java 7 and beyond. +The module is based on Java 8. === Installation @@ -43,9 +43,9 @@ To benefit from filter support you only must add the corresponding dependency to Tamaya Filter comes basically with 3 artifacts: -* The +org.apache.tamaya.filter.ConfigurationFilter+ provides several static methods to register +PropertyFilter+ +* The +org.apache.tamaya.filter.ThreadBasedConfigurationFilter+ provides several static methods to register +PropertyFilter+ instances on the current thread. -* The +org.apache.tamaya.filter.DefaultMetdataFilter+ is a +PropertyFilter+ with hides all entries starting with +* The +org.apache.tamaya.filter.ThreadFilterContext+ is a +PropertyFilter+ with hides all entries starting with an underscore ('_'), when a full property map is accessed. @@ -95,22 +95,22 @@ is part of this module, So you can add a customized filter as follows: [source, java] ----------------------------------------------- try { - ConfigurationFilter.getMapFilters().addFilter(new myFilter()); + ThreadBasedConfigurationFilter.getMapFilters().addFilter(new myFilter()); // do your code with filtering active } finally { // cleanup - ConfigurationFilter.clearFilters(); + ThreadBasedConfigurationFilter.clearFilters(); } ----------------------------------------------- -The +FilterContext+ is a simple structure just providing some handy accessors to the dynamic thread-local +The +ThreadFilterContext+ is a simple structure just providing some handy accessors to the dynamic thread-local managed filters: [source, java] ----------------------------------------------- -public final class FilterContext implements PropertyFilter { +public final class ThreadFilterContext implements PropertyFilter { public void addIncludes(PropertyFilter filter); public void addExcludes(int pos, PropertyFilter filter); http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_formats.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_formats.adoc b/content/documentation/extensions/mod_formats.adoc index aa7d559..db3202c 100644 --- a/content/documentation/extensions/mod_formats.adoc +++ b/content/documentation/extensions/mod_formats.adoc @@ -24,7 +24,7 @@ Tamaya _Formats_ provides an abstraction for configuration formats provding the === Compatibility -The module is based on Java 7, so it can be used with Java 7 and beyond. +The module is based on Java 8. === Installation @@ -66,34 +66,20 @@ public final class ConfigurationData { public ConfigurationFormat getFormat(); public String getResource(); - public Set<String> getSectionNames(); - public Map<String,String> getSection(String name); - - public boolean hasDefaultProperties(); - public Map<String,String> getDefaultProperties(); - public Map<String,String> getCombinedProperties(); + public List<PropertyValue> getData(); public boolean isEmpty(); } ------------------------------------------------------- -In detail the data read from a file is organized into _sections_ as follows: - * with +getResource()+ and +getFormat()+ the underlying resource and the format that read this data can be accessed. -* properties can be owned by - ** named sections - ** an (unnamed) default section -* each section section contains a map of properties. Hereby the same key can be part of the default section and multiple - named sections, depending on the configuration format. -* The method +getSectionNames()+ returns a set of all section names. -* With +getSection(String name)+ a named section can be accessed. -* With +getDefaultSection()+ the 'default' section can be accessed. This is a convenience method. -* With +getCombinedProperties()+ a flattened entry map can be accessed built up (by default) out of - ** all entries from the default section, without any changes. - ** all entries from named sections, where the key for each entry is prefix with the section name and a '::' separator. -* The configuration format used determines the mapping of configuration data read into this structure. The format - implementation can as well provide alternate implementations of how the data read should be mapped into the - combined properties map. +* +getData()+ allows access to the data read. Hereby this data can be mapped in different ways: +** as (multiple) simple key-value literal pairs, or +** as field-mapped object type values, or as +** list values +** the children of list and object values can be of any of the three types described above. As a consequence a simple + `PropertyValue` can be a simple literal value, or a complex tree/list structure, similar to common configuration + formats. ==== ConfigurationFormat @@ -111,6 +97,7 @@ public interface ConfigurationFormat { } ------------------------------------------------------- + === Creating a default PropertySource for a ConfigurationFormat The module defines a singleton +ConfigurationFormats+ which provides @@ -121,32 +108,35 @@ using abstract +ConfigurationFormat+ implementations: ------------------------------------------------------- public final class ConfigurationFormats { - public static List<ConfigurationFormat> getFormats(); - public static List<ConfigurationFormat> getFormats(String... formatNames); - public static List<ConfigurationFormat> getFormats(final URL url); + public static ConfigurationFormats getInstance(); + public static ConfigurationFormats getInstance(ClassLoader classLoader); + + public List<ConfigurationFormat> getFormats(); + public List<ConfigurationFormat> getFormats(String... formatNames); + public List<ConfigurationFormat> getFormats(final URL url); - public static ConfigurationData readConfigurationData(final URL url) + public ConfigurationData readConfigurationData(final URL url) throws IOException; - public static ConfigurationData readConfigurationData(URL url, ConfigurationFormat... formats) + public ConfigurationData readConfigurationData(URL url, ConfigurationFormat... formats) throws IOException; - public static ConfigurationData readConfigurationData(URL url, Collection<ConfigurationFormat> formats) + public ConfigurationData readConfigurationData(URL url, Collection<ConfigurationFormat> formats) throws IOException; - public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, ConfigurationFormat... formats); - public static Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, Collection<ConfigurationFormat> formats); - public static ConfigurationData readConfigurationData(String resource, InputStream inputStream, + public Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, ConfigurationFormat... formats); + public Collection<ConfigurationData> readConfigurationData(Collection<URL> urls, Collection<ConfigurationFormat> formats); + public ConfigurationData readConfigurationData(String resource, InputStream inputStream, ConfigurationFormat... formats) throws IOException; - public static ConfigurationData readConfigurationData(String resource, InputStream inputStream, + public ConfigurationData readConfigurationData(String resource, InputStream inputStream, Collection<ConfigurationFormat> formats) throws IOException; - public static PropertySource createPropertySource(URL url, ConfigurationFormat... formats) + public PropertySource createPropertySource(URL url, ConfigurationFormat... formats) throws IOException; - public static PropertySource createPropertySource(URL url, Collection<ConfigurationFormat> formats) + public PropertySource createPropertySource(URL url, Collection<ConfigurationFormat> formats) throws IOException; - public static PropertySource createPropertySource(String resource, InputStream inputStream, + public PropertySource createPropertySource(String resource, InputStream inputStream, ConfigurationFormat... formats); - public static PropertySource createPropertySource(String resource, InputStream inputStream, + public PropertySource createPropertySource(String resource, InputStream inputStream, Collection<ConfigurationFormat> formats); } ------------------------------------------------------- @@ -166,10 +156,10 @@ So creating a +PropertySource+ from a resource is basically a one liner: [source,java] ------------------------------------------------------- URL url = ...; -PropertySource propertySource = ConfigurationFormats.createPropertySource(url); +PropertySource propertySource = ConfigurationFormats.getInstance().createPropertySource(url); // constraining the formats to be used (assumption: json and yaml extensions are loaded) -PropertySource propertySource = ConfigurationFormats.createPropertySource( +PropertySource propertySource = ConfigurationFormats.getInstance().reatePropertySource( url, ConfigurationFormats.getFormats("json", "yaml")); ------------------------------------------------------- @@ -177,25 +167,19 @@ PropertySource propertySource = ConfigurationFormats.createPropertySource( === Customize how ConfigurationData maps to PropertySource -For for the conversion of +ConfigurationData+ into a +PropertySource+ different approaches can be useful: - -. The +ConfigurationFormat+ that reads the data can provides all properties read either as sectioned properties - or/and as default properties. The most simple cases is, where all properties have been added as 'default' - properties. In this case the default properties can be used as the property sources properties without any change. -. If the format did also add section based properties, the combined properties returned can be used, hereby - replacing the '::' separator with a '.' separator. -. In all other cases a custom mapping is useful, which can be acomplished by using the +MappedConfigurationDataPropertySource+ - and overriding the +Map<String,String> populateData(ConfigurationData data)+ method. - +For for the conversion of +ConfigurationData+ into a +PropertySource+ different approaches can be useful. In most cases the usage of a +MappedConfigurationDataPropertySource+, is a good choice to start. This class -provides a convenient default mapping and also allows to customized the mapping easily: +provides a convenient default mapping and also allows to customized the mapping easily: it simply iterates over all +values recursively and adds them using their fully qualified name as single value properties. + +This behaviour can be easily adapted by overriding the +popoulateData+ method: [source,java] ------------------------------------------------------- ConfigurationData data = ...; MappedConfigurationDataPropertySource ps = new MappedConfigurationDataPropertySource(data){ - protected Map<String, String> populateData(ConfigurationData data) { + protected Map<String, PropertyValue> populateData(ConfigurationData data) { ... } }; @@ -204,9 +188,9 @@ MappedConfigurationDataPropertySource ps = Nevertheless, depending on the context, where a configuration source was read (classloader, time, source etc.) the resulting properties can have different semnatics, especially different priorities. Also section names may be mapped into different ordinals instead of using them as key prefixes (e.g. imagine configuration formats -with a 'default', 'main', and 'overrides' sections). For such more complex or custom cases no simple mapping +with a 'default', 'main', and 'overrides' sections). For such use cases no simple mapping can be defined. Consequently the functionality mapping the normalized +ConfigurationData+ read to the -appropriate collection of +PropertySource+ instances must be implemented. +appropriate collection of +PropertySource+ instances must be implemented by the client code. For this scenario the +BaseFormatPropertySourceProvider+ can be used, defining the following mapping function that mus be implemented: @@ -262,9 +246,9 @@ This file content by default is mapped to the following Tamaya properties: ------------------------------------------------------- a=valA a.b=valB -section1::valA=sectionValA -section1::a.b.c=SectionValC -section2::a=val2Section2 +section1.valA=sectionValA +section1.a.b.c=SectionValC +section2.a=val2Section2 ------------------------------------------------------- Summarizing @@ -272,7 +256,7 @@ Summarizing * entries without a section are mapped to the _default_ section. * entries with a section are mapped to a corresponding section, hereby everything between the brackets is used as section name (trimmed). -* section names are separated using a double colon (`::`). +* section names are separated using a double colon (`.`), they are modelled as simple parent `PropertyValue` nodes. +ConfigurationData+ allows to access all the different parts: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_functions.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_functions.adoc b/content/documentation/extensions/mod_functions.adoc index 50a2b8b..afb8b3c 100644 --- a/content/documentation/extensions/mod_functions.adoc +++ b/content/documentation/extensions/mod_functions.adoc @@ -51,36 +51,36 @@ For using the functionality shown in this document you only must add the corresp The following sections explain the provided functions defined by +ConfigurationFunctions+ singleton. -* *ConfigOperator filter(PropertyMatcher matcher)* creates a +ConfigOperator+ that creates a +Configuration+ +* *UnaryOperator<Configuration> filter(PropertyMatcher matcher)* creates a +UnaryOperator<Configuration>+ that creates a +Configuration+ containing only keys that are selected by the given _matcher predicate_. The +PropertyMatcher+ hereby allows to evaluate not only the _key_, but also the _value_. -* *ConfigOperator map(KeyMapper keyMapper)* creates a +ConfigOperator+ that maps the keys as defined +* *UnaryOperator<Configuration> map(KeyMapper keyMapper)* creates a +UnaryOperator<Configuration>+ that maps the keys as defined by the given _keyMapper_. -* *ConfigOperator section(String section)* creates a +ConfigOperator+ that creates a +Configuration+ containing only +* *UnaryOperator<Configuration> section(String section)* creates a +UnaryOperator<Configuration>+ that creates a +Configuration+ containing only entries that are direct or indirect members of the given section. -* *ConfigOperator section(String areaKey, boolean stripKeys)* creates a +ConfigOperator+ that creates a +Configuration+ +* *UnaryOperator<Configuration> section(String areaKey, boolean stripKeys)* creates a +UnaryOperator<Configuration>+ that creates a +Configuration+ containing only entries that are direct or indirect members of the given section. Hereby _stripKeys_ allows to determine if the returned entries should be relative to the search criteria {{stripKeys=true}} or absolute keys. * *isKeyInSection(String section, String sectionKey)* allows to easily determine if a given _key_ is a direct or indirect member of a given section. * *boolean isKeyInSections(String key, String... sectionKeys)* allows to easily determine if one key of given _key_ is a direct or indirect member of at least one of the given _sectionKeys_. -* *ConfigQuery<Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that +* *Function<Configuration,Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that also have parameters present). -* *ConfigQuery<Set<String>> transitiveSections()* allows to query all the contained fully qualified section names, +* *Function<Configuration,Set<String>> transitiveSections()* allows to query all the contained fully qualified section names, including the transitive closure of sections. -* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully +* *Function<Configuration,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully qualified section names that are selected by the given _predicate_. -* *ConfigQuery<Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully +* *Function<Configuration,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully qualified section names that are selected by the given _predicate_, including the transitive closure of sections identified. -* *ConfigOperator sectionsRecursive(String... sectionKeys)* provides a +ConfigOperator+ that filters all sections identified +* *UnaryOperator<Configuration> sectionsRecursive(String... sectionKeys)* provides a +UnaryOperator<Configuration>+ that filters all sections identified by the given _sectionKeys_ and its child sections. -* *ConfigOperator sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +ConfigOperator+ +* *UnaryOperator<Configuration> sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +UnaryOperator<Configuration>+ that filters all sections identified by the given _sectionKeys_ and its child sections. _stripKeys_ allows to determine if the resulting configuration should be relative to the selected areas ({{stripKeys=true}}) or absolute (filtering only). -* *ConfigQuery<String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+ +* *Function<Configuration,String> jsonInfo()* returns a query that converts a +Configuration+ into a JSON formatted +String+ representation.
