Repository: incubator-tamaya Updated Branches: refs/heads/master eafcadea6 -> 924613847
TAMAYA-182: Adapted API documentation to include builder support.$ Adapted configuration for new module structure. Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/92461384 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/92461384 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/92461384 Branch: refs/heads/master Commit: 924613847f098b66c285ff0592470bcef764df82 Parents: eafcade Author: anatole <[email protected]> Authored: Sun Nov 6 16:38:16 2016 +0100 Committer: anatole <[email protected]> Committed: Sun Nov 6 16:38:16 2016 +0100 ---------------------------------------------------------------------- src/site/asciidoc/API.adoc | 125 ++++- src/site/asciidoc/Core.adoc | 6 +- src/site/asciidoc/extensions.adoc | 74 +-- src/site/asciidoc/extensions/mod_builder.adoc | 100 ---- .../extensions/mod_metamodel-staged.adoc | 76 --- src/site/asciidoc/extensions/mod_model.adoc | 465 ------------------- .../asciidoc/extensions/mod_usagetracker.adoc | 169 +++++++ .../asciidoc/extensions/mod_validation.adoc | 111 +++++ 8 files changed, 416 insertions(+), 710 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/API.adoc ---------------------------------------------------------------------- diff --git a/src/site/asciidoc/API.adoc b/src/site/asciidoc/API.adoc index f8d01c1..6aac2da 100644 --- a/src/site/asciidoc/API.adoc +++ b/src/site/asciidoc/API.adoc @@ -22,7 +22,7 @@ include::temp-properties-files-for-site/attributes.adoc[] == 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 +that are 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]] @@ -50,10 +50,14 @@ The API provides the artifacts as described in the link:HighLevelDesign.html[Hig ** +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. + ** +ConfigurationContext+, which provides a container for all the artifacts needed to build up a +Configuration+. + For example a context contains the property sources, property filters, converters and combination policy used. + Also the ordering of the property sources is defined by the context. A context instance given a + +Configuration+ can be created by calling +ConfigurationProvider.createConfiguration(context);+. + ** Similarly a +ConfigurationContext+ can be created using a +ConfigurationContextBuilder+. This builder can be + obtained calling +ConfigurationProvider.getConfigurationContextBuilder();+. ** +ServiceContext+, which provides access to the components loaded, depending on the current runtime stack. ** +ServiceContextManager+ provides static access to the +ServiceContext+ loaded. @@ -201,7 +205,7 @@ Hereby the singleton is backed up by an instance of +ConfigurationProviderSpi+. [[PropertyConverter]] -==== Property Converters +==== Property Type Conversion 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 @@ -327,7 +331,7 @@ property sources with additional combination/aggregation rules in place. [[PropertySourceProvider]] -==== Interface PropertySourceProvider +=== Interface PropertySourceProvider Instances of this type can be used to register multiple instances of +PropertySource+. @@ -348,7 +352,7 @@ current active +ServiceContext+. [[PropertyFilter]] -==== Interface 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 @@ -419,7 +423,7 @@ public interface PropertyValueCombinationPolicy{ [[ConfigurationContext]] ==== The Configuration Context -A +Configuration+ is basically based on a so called +ConfigurationContext+, which is +A +Configuration+ is created from a +ConfigurationContext+, which is accessible from +Configuration.getContext()+: [source,java] @@ -428,7 +432,8 @@ accessible from +Configuration.getContext()+: ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext(); -------------------------------------------- -The +ConfigurationContext+ provides access to the internal building blocks that determine the final +Configuration+: +The +ConfigurationContext+ provides access to the internal artifacts that determine the final +Configuration+ and +also defines the ordering of the property sources, filters and converters contained: * +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances). * +PropertyFilters+ registered, which filter values before they are returned to the client @@ -440,8 +445,8 @@ The +ConfigurationContext+ provides access to the internal building blocks that [[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 +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: * New configuration files where detected in a folder observed by Tamaya. @@ -451,7 +456,7 @@ consequently +Configuration+) must be adapted: * 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: +In such cases the +ConfigurationContext+ must be changed, meaning it must be possible: * to add or remove +PropertySource+ instances * to add or remove +PropertyFilter+ instances @@ -461,9 +466,9 @@ In such cases the +ConfigurationContext+ must be mutable, meaning it must be pos 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. +* calling +ConfigurationContext.toBuilder()+, hereby returning a builder instance preinitialized with the values from the + current +ConfigurationContext+. +* calling +ConfigurationProvider.getConfigurationContextBuilder()+. [source,java] .Accessing a +ConfigurationContextBuilder+ @@ -477,10 +482,41 @@ 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(); +ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext() + .toBuilder(); + .addPropertySources(new MyPropertySource()) + .addPropertyFilter(new MyFilter()) + .build(); +-------------------------------------------- + +Hereby the builder provides several methods for adding, removing of property sources and also operations +for programmatically change the property sourcepriorities, e.g. + +[source,java] +.Chain manipulation using +ConfigurationContextBuilder+ +-------------------------------------------- +PropertySource propertySource = builder.getPropertySource("sourceId"); + +// changing the priority of a property source. The ordinal value hereby is not considered. +// Instead the position of the property source within the chain is changed. +builder.decreasePriority(propertySource); + +// Alternately a comparator expression can be passed to establish the defined ordering... +builder.sortPropertyFilters(MyFilterComparator::compare); +-------------------------------------------- + +Finally if the new context is ready a new configuration can be created, or the context is applied to the +current configuration. + +[source,java] +.Creating and applying a new +ConfigurationContext+ +-------------------------------------------- +ConfigurationContext context = builder.build(); + +// Creates a new matching Configuration instance +Configuration newConfig = ConfigurationProvider.createConfiguration(context); + +// Apply the new context to replace the current configuration: ConfigurationProvider.setConfigurationContext(context); -------------------------------------------- @@ -499,6 +535,59 @@ One of the most important SPI in Tamaya if the +ConfigurationProviderSpi+ interf * to provide access to the right +Configuration/ConfigurationContext+ based on the current runtime context. * Performing changes as set with the current +ConfigurationContextBuilder+. += Interface ConfigurationContextBuilder + +include::temp-properties-files-for-site/attributes.adoc[] + +[[BuilderCore]] +== Interface ConfigurationContextBuilder +=== 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. + + +=== Supported Functionality + +The builder allows you to add +PropertySource+ instances: + +[source,java] +---------------------------------------------------------------- +ConfigurationContextBuilder builder = ConfigurationProvider.getConfigurationContextBuilder(); +builder.addPropertySources(sourceOne, sourceTwo, sourceThree +Configuration config = ConfigurationProvider.createConfiguration(builder.build()); +---------------------------------------------------------------- + +Hereby the ordering of the propertysources 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. + +Similarly you can add filters: + +[source,java] +---------------------------------------------------------------- +builder.addPropertyFilters(new MyConfigFilter()); +---------------------------------------------------------------- + +...or +PropertySourceProvider+ instances: + +[source,java] +---------------------------------------------------------------- +builder.addPropertySourceProvider(new MyPropertySourceProvider()); +---------------------------------------------------------------- + + [[ServiceContext]] ==== The ServiceContext http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/Core.adoc ---------------------------------------------------------------------- diff --git a/src/site/asciidoc/Core.adoc b/src/site/asciidoc/Core.adoc index e31c319..927004b 100644 --- a/src/site/asciidoc/Core.adoc +++ b/src/site/asciidoc/Core.adoc @@ -35,7 +35,8 @@ hereby providing type conversion for all important types. * A simple default configuration setup using the current classpath and an optional staging variable. * It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and registers them in the global +ConfigurationContext+ -* It provides a +ConfigurationContextBuilder+ and allows changing the current +ConfigurationContext+. +* It provides a +ConfigurationContextBuilder+ implementation (class +DefaultConfigurationContextBuilder+) 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 @@ -115,6 +116,9 @@ By default, and if no annotation is added +0+ is used as priority. Hereby higher * 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. +NOTE: Sorting the property sources based on their ordinal value is only the default ordering principle applied. By implementing + your own implementation of +ConfigurationProviderSpi+ you can apply a different logic: + [[RegisteringPropertySources]] === Registering Property Sources http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/extensions.adoc ---------------------------------------------------------------------- diff --git a/src/site/asciidoc/extensions.adoc b/src/site/asciidoc/extensions.adoc index 939241b..14b3e58 100644 --- a/src/site/asciidoc/extensions.adoc +++ b/src/site/asciidoc/extensions.adoc @@ -34,72 +34,46 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati |+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-api+ |Provides Tamaya's injection annotations API. |link:extensions/mod_injection.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-injection-cdi+ | Java EE/standalone compliant CDI integration using CDI for injection. | link:extensions/mod_cdi.html[Documentation] +|+org.apache.tamaya.ext:tamaya-injection-cdi-se+ | Java EE/standalone compliant CDI integration using Tamaya SE injection mechanism. | link:extensions/mod_cdi.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-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.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 Sandbox -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. +Extensions in _draft state_ rather experimental or not yet very mature. API changes may occurr at any time +and the may also have severe issues. So use at your own risk or join and help us getting them stable and +well tested! + +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-commons+ |Combines Tamaya's Format Abstraction with Apache Commons. | - |+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] +|+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-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation] +|+org.apache.tamaya.ext:tamaya-metamodel+ |Provides support defining configuration using XML based meta-configuration. |link:extensions/mod_metamodel.html[Documentation] +|+org.apache.tamaya.ext:tamaya-validation+ |Provides support for XML based meta-configuration allowing to validate configuration read. |link:extensions/mod_validation.html[Documentation] +|+org.apache.tamaya.ext:tamaya-usagetracker+ |Provides support tracking of configuration usage and the consumer locations consuming configuration. |link:extensions/mod_usagetracker.html[Documentation] +|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:extensions/mod_camel.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] +|+org.apache.tamaya.ext:tamaya-configured-sysprops+ | Allows Tamaya to integrate with +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation] +|+org.apache.tamaya.ext:tamaya-remote+ |Provides remote configuration support. |link:extensions/mod_remote.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-ui+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.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/blob/92461384/src/site/asciidoc/extensions/mod_builder.adoc ---------------------------------------------------------------------- diff --git a/src/site/asciidoc/extensions/mod_builder.adoc b/src/site/asciidoc/extensions/mod_builder.adoc deleted file mode 100644 index 8555dc9..0000000 --- a/src/site/asciidoc/extensions/mod_builder.adoc +++ /dev/null @@ -1,100 +0,0 @@ -// 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[] - - -[[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/blob/92461384/src/site/asciidoc/extensions/mod_metamodel-staged.adoc ---------------------------------------------------------------------- diff --git a/src/site/asciidoc/extensions/mod_metamodel-staged.adoc b/src/site/asciidoc/extensions/mod_metamodel-staged.adoc deleted file mode 100644 index 9fb89c3..0000000 --- a/src/site/asciidoc/extensions/mod_metamodel-staged.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// 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: Staged PropertySources - -toc::[] - - -[[Remote]] -== Tamaya Metamodel: Staged PropertySources (Extension Module) -=== Overview - -The Tamaya Staged PropertySources extension provides a base class and default implementation for loading -multistaged configuration easily from a common configuration location. - - -=== Compatibility - -The module is based on Java 7, so it will not run on Java 7 and beyond. - - -=== Installation - -To benefit from Tamaya CDI integration you only must add the corresponding dependency to your module: - -[source, xml] ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext.metamodels</groupId> - <artifactId>tamaya-metamodel.staged</artifactId> - <version>{tamayaVersion}</version> -</dependency> ------------------------------------------------ - -The component will not register any components. The component basically provides the following options: - -* Use it as default configuration extension. Hereby you should define your stages in use by setting the - +env.STAGE+ system property with the stages to be loaded in order of precedence (most significant last), - e.g. +sys-env,DEFAULTS,TEST,DEVELOPMENT. _Additionally_ you must register - +org.apache.tamaya.staged.StagedConfigPropertiesProvider+ as in - --------------------------------------------------------------- -META-INF -|_service - |_org.apache.tamaya.spi.PropertySourceProvider --------------------------------------------------------------- - -Tamaya will then load .properties files from +System.getenv(), -classpath:DEFAULTS.properties, classpath:TEST.properties+ and -+classpath:DEVELOPMENT.properties+ - -* For more advanced requirements, such as alternate locations, patterns or formats, you can also extend one of the - provided classes (+org.apache.tamaya.staged.StagedConfigPropertiesProvider+, - ** +BaseStagedPropertySourceProvider+). Extending provides features such as: - - ** Defining a prefix for all entries provided/loaded. - ** Using alternate locations or formats. - ** Defining the ordinals used. - - - - http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/extensions/mod_model.adoc ---------------------------------------------------------------------- diff --git a/src/site/asciidoc/extensions/mod_model.adoc b/src/site/asciidoc/extensions/mod_model.adoc deleted file mode 100644 index 0bc9f74..0000000 --- a/src/site/asciidoc/extensions/mod_model.adoc +++ /dev/null @@ -1,465 +0,0 @@ -// 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: Model Documentation and Validation - -toc::[] - - -[[ExtModel]] -== Tamaya Model Documentation and Validation (Extension Module) -=== Overview - -The Tamaya model module provides support for documenting configuration and validating configuration read and processed -against this model. Documentation and config models can be provided in different ways: - -* as separate meta-model documents -* by providers that check classes/packages for configuration annotations (planned) - - -=== 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-model</artifactId> - <version>{tamayaVersion}</version> -</dependency> ------------------------------------------------ - - -=== Describing the Configuration Meta-Model - -Basically configuration is modelled using key, value-pairs. Looking at a keys -+a.b.c.param1+ and +a.b.c.param2+ the following concepts can be used to defined/describe -configuration: - -. the _configuration section:_ In our case this equals to +a.b.c+, which itself also includes the - transitive entries +a.b+ and +a+. -. the _configuration parameter:_ Basically parameters are adressed using their fully qualified names, - which equals to the containing section name and the relative parameter name, separated by the dor separator. - In the above example +a.b.c.param1+ and +a.b.c.param2+ are the fully qualified parameter names. - -Now with only these 2 concepts a simple configuration meta-model can be defined as - -* a meta-model's name, used just for grouping different meta-models and entries to better separate - descriptions, e.g. in a management console or generated configuration documentation site. -* a set of sections. -* a set of parameters. -* Both, sections (+.model.target=Section+) as well as parameter models (+.model.target=Parameter+) - ** can be modelled by a meta-data entry, by default +_my.config.key.model+. - ** may be required, or optional (+.model.required=true|false+) - ** may have an optional description -* Parameters additionally have - ** a _type_ (+.model.type=Classname+), described by the fully qualified class name, into which any configured (String) - value must be convertable into. If no type is configured +java.ui.lang.String+ is assumed as default. - ** an optional regular expression that can be used to validate the +String+ values returned from a - configuration (+.model.expression=regexpression+). - -Given these concepts a configuration can be fully described. Entries that are not contained in one of the given -sections (or its children), or parameters not described or marked as valid (e.g. for dynamic configModels of -a section), are called _undefined_. Undefined parameters should be grouped with its parent section. Each section, as -well as all parent sections, including transitive) of any parametet read, should similarly marked as undefined, if and -only if - -. the section itself is (directly) _undefined_ -. the section is not a _super section_ of a defined section. - -As en example the section definition of +a.b.c+ also implicitly includes the sections +a.b+ and +a+ to be defined -sections, despite the fact that section properties, such as description and custom configModels are not inherited to -its parent, or child section. - - -=== Defining Meta-Configuration Model - -The configuration meta-model is defined by simple configuration meta-data entries. The section for all model -configuration by default is called +model+, which results in entries such as +_my.config.key.model.target=Section+. -Within this section fully qualified configuration keys defines -which part of the configuration is targeted by certain entries. - -==== Defining Sections - -First we start to define some configuration sections, the example below starts with the most important -variants supported: - -[source,listing] -------------------------------------------------------------------------------- -# Metamodel information -_model.provider=ConfigModel Extension - -# org.mycompany.root (optional section) -_org.mycompany.root.model.target=Section -_org.mycompany.root.model.description=Root section defining my company configuration. - -# org.mycompany.security (required section) -_org.mycompany.security.model.target=Section -_org.mycompany.security.model.required=true -_org.mycompany.security.model.description=Security related settings.\ - refer for further details to XXX. - -# minmal section -_minimal.model.target=Section - -# custom validated section -_validated.model.target=Section -_validated.model.validator=org.apache.tamaya.model.TestValidator -------------------------------------------------------------------------------- - -Above +org.mycompany.root+ transitively defines 3 sections: - -* org -* org.mycompany -* org.mycompany.root - -All sections are optional. Additionally the model above also defines a required section +org.mycompany.security+. -Required sections are checked so the section is not empty. It is not checked for any specific parameter hereby, -only the existance of any child parameter is validated. - -The _class_ attribute has to be defined for any section definition, because if not set a model entry is, by default, -defined to be a parameter configModel entry. Given above the entry for the section +minimal+ shows such a minimal -entry. - -+validated+ defines a section, which is validated through a customizable validator. Hereby an ordered list of validators -can be provided, separated by commas. - - -==== Defining Parameters - -Similarly parameters also can be defined: - -[source,listing] -------------------------------------------------------------------------------- -# org.mycompany.root.name (required parameter) -_org.mycompany.root.name.model.target=Parameter -_org.mycompany.root.name.model.required=true -_org.mycompany.root.name.model.description=The company's name, also used in the application's main header. - -# org.mycompany.security (required parameters) -_org.mycompany.security.uid.model.required=true -_org.mycompany.security.uid.model.description=The user id. -_org.mycompany.security.realm.model.required=true -_org.mycompany.security.realm.model.validator=org.apache.tamaya.model.RealmValidator -_org.mycompany.security.realm.model.description=The security realm required. -_org.mycompany.security.tokenid.model.description=The token id, if the token service is used (optional). - -# A minmal parameter -_minimalClass.model.target=Class -------------------------------------------------------------------------------- - -Similarly as when defining section also parameter entries define transitively its containing sections. E.g. -the entry above for +org.mycompany.security.realm+ also defines the following sections (as optional). - -* org -* org.mycompany -* org.mycompany.security - -Additional entries for section, e.g. configModels to be done, can be added as described in the previous section, -but are optional. - -Since the parameter is the default type for model entries, a minmal parameter model entry only only needs it's -parameter type to be defined. In the example above we define a parameter +minimalClass+ of type +Class+. -Types hereby are fully qualified class names, whereas as 'java.ui.lang' for built-in language types can be -ommitted. - -==== Model Locations - -By default the configuration model can be defined at the following locations: - -* +classpath*:META-INF/configmodel.properties+, separate to the current +Configuration+. This functionality is enabled - by default, but can be disabled by adding +org.apache.tamaya.model.default.enabled=false+ to your current - +Configuration+. -* +implicitly as part of the current +Configuration+. THis can be disabled by setting - the +org.apache.tamaya.model.integrated.enabled+ configuration poarameter to +false+. -* customized by configuring the +org.apache.tamaya.model.resources+ in the current +Configuration+. This - parameter allows to define the locations from where the model extension is trying to read the - model configuration. If the _resources extension_ is available in your system it is used to - evaluate the locations. If not the default +Classloader.getResources+ command is issued. Also it - is required that the _formats extension_ is available, since this is used to effectively read the - data. This extension also allows you to use alternate representation formats such as +ini, xml, yml, json+. - - -=== Tracking Configuration Access - -The model module also allows tracking which code accesses configuration properties or configuration parameters. -It checks the stacktrace to evaluate the calling code location, hereby any unwanted packages can be implicitly -ommitted from the stacktrace. Also the maximal length of the stacktrace retained can be constraint in length. -The usages are recorded as +Usage+ instances. Hereby for each parameter accessed a corresponding +Usage+ -instance is created. It can be accessed by calling +Usage ConfigUsageStats.getUsage(String key)+. Usage -statistics for calling +Configuration.getProperties()+ can be obtained calling +Usage getUsageAllProps();+. - -Usage tracking is disabled by default. It can be enabled by calling +ConfigUsageStats.enableUsageTracking(true);+. -+ConfigUsageStats.isUsageTrackingEnabled()+ returns the current tracking status. - -The +Usage+ class itself provides access to further fainer grained usage data (+AccessDetail+) containing: - -* the access point (+fqn.ClassName#method(line: xxx)+). -* the number of accesses -* the first an last access -* the values read -* the access stacktrace (filtered by ignored packages). - -[source,java] ------------------------------------------------------------ -public final class Usage { - [...] - public String getKey(); - public void clearMetrics(); - public int getReferenceCount(); - public int getUsageCount(); - public Collection<AccessDetail> getAccessDetails(Class type); - public Collection<AccessDetail> getAccessDetails(Package pack); - public Collection<AccessDetail> getAccessDetails(String lookupExpression); - public Collection<AccessDetail> getAccessDetails(); - public void trackUsage(String value); - public void trackUsage(String value, int maxTraceLength); - - - public static final class AccessDetail { - [...] - public void clearStats(); - public long trackAccess(String value); - public long getAccessCount(); - public String getAccessPoint(); - public long getFirstAccessTS(); - public long getLastAccessTS(); - public String[] getStackTrace(); - public Map<Long, String> getTrackedValues(); - } - -} ------------------------------------------------------------ - -With +ConfigUsageStats.clearUsageStats()+ the collected statistics can be reset at any time. Summarizing the main -singleton for configuration statistics is defined as follows: - -[source,java] ------------------------------------------------------------ -public final class ConfigUsageStats{ - public static Set<String> getIgnoredUsagePackages(); - public static void addIgnoredUsagePackages(String... packageName); - public static void enableUsageTracking(boolean enabled); - public static Usage getUsage(String key); - public static Collection<Usage> getUsages(); - public static void clearUsageStats(); - public static Usage getUsageAllProperties(); - public static boolean isUsageTrackingEnabled(); - public static String getUsageInfo(); -} ------------------------------------------------------------ - -==== Customizing the Stacktrage for Usage Reporting - -The stacktrace tracked by the system can be customized in several ways: - -* +ConfigUsageStats.addIgnoredPackageNames(String...)+ allows to add additional ignored package names. -* With +Usage.setMaxTraceLength(int)+ the maximal size of the stacktraces logged can be set. Setting a - negative value will disable stacktrace logging completelely. - - -=== Accessing Usage Statistics - -Bascially usage statistics are available in two forms: - -* The +Usage/AccessDetail+ object tree can be accessed programmatically from the +ConfigUsageStats+ - singleton. -* With +ConfigUsageStats.getUsageInfo()+ also a textual representation of the usage statistics - can be obtained, as illustrated below (a snipped from the current test output): - -[source,listing] ------------------------------------------------------------ -Apache Tamaya Configuration Usage Metrics -========================================= -DATE: Sat Apr 30 21:51:09 CEST 2016 - -220 <<all>>: - - 220 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016 -3 java.version: - - 2 test.model.TestConfigAccessor#readProperty(line:43), first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016 - - 1 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016 - ------------------------------------------------------------ - - -==== Programmatic API - -Basically the configModel module provides a simple API to access the defined +ConfigModel+ instances and -validating the current +Configuration+ against the models as follows: - -[source,java] ------------------------------------------------------------ -public final class ConfigModelManager { - - private ConfigModelManager() {} - - public static Collection<ConfigModel> getModels(); - public static Collection<ConfigModel> findModels(ModelType type, String namePattern); - public static <T extends ConfigModel> T getModel(String name, Class<T> modelType); - public static Collection<ConfigModel> findModels(String namePattern); - - public static Collection<ValidationResult> validate(); - public static Collection<ValidationResult> validate(boolean showUndefined); - public static Collection<ValidationResult> validate(Configuration config); - public static Collection<ValidationResult> validate(Configuration config, boolean showUndefined); - - public static void registerMBean(); - public static void registerMBean(String context); - -} ------------------------------------------------------------ - -This singleton allows to validate the current or any +Configuration+ instance. All the ConfigModels read also are -available from the +getModels+ method. This models can be used to provide documentation, e.g. as part of a CLI interface -or shown on a documentation web server. - -A +ConfigModel+ hereby is defined as one single part of configuration, typically corresponding to a specific concern -of your system. As an example you can define different models for different modules or products plugged together. -With resolution mechanism in place you can also define a shared module that is targeted by multiple modules as a -single configuration source (e.g. for configuring the machine's IP address and subnet settings only once. - -[source,java] ------------------------------------------------------------ -public interface ConfigModel { - - ModelTarget getType(); - String getName(); - String getProvider(); - boolean isRequired(); - String getDescription(); - Collection<ValidationResult> validate(Configuration config); -} ------------------------------------------------------------ - - -Hereby +ModelTarget+ defines more details on the kind of model: - -[source,java] ------------------------------------------------------------ -public enum ModelTarget { - /** - * A configuration section. - */ - Section, - /** - * A configuration paramter. - */ - Parameter, - /** - * ConfigModel that is a container of other validations. - */ - Group -} ------------------------------------------------------------ - -A +ValidationResult+ models one validation executed by a +ConfigModel+ on a certain +Configuration+ instance: - -[source,java] ------------------------------------------------------------ -public final class ValidationResult { - - public static ValidationResult ofValid(ConfigModel configModel); - public static ValidationResult ofMissing(ConfigModel configModel); - public static ValidationResult ofMissing(ConfigModel configModel, String message); - public static ValidationResult ofError(ConfigModel configModel, String error); - public static ValidationResult ofWarning(ConfigModel configModel, String warning); - public static ValidationResult ofDeprecated(ConfigModel configModel, String alternateUsage); - public static ValidationResult ofDeprecated(ConfigModel configModel); - public static ValidationResult ofUndefined(final String key); - public static ValidationResult of(ConfigModel configModel, ValidationState result, String message); - - public ConfigModel getConfigModel(); - public ValidationState getResult(); - public String getMessage(), -} ------------------------------------------------------------ - -The result of a complete validation on a concrete +Configuration+ instance finally is mapped as a -+Collection<ValidationResult>+, refer to the methods on +ConfigModelManager+. - - -=== Auto-Documentation of Classes with Configuration Injection - -A special feature of this module is that it observes +ConfigEvent+ published through Tamaya'as event channel -(+tamaya-events+ module). If no metaconfiguration model is found the model manager by default automatically creates -models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment -time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different -behaviour. Nevertheless this means that after your system has been started you should have access to a complete -set of +ConfigModel+ instances that automatically document all the classes in your system that consume configuration -(through injection). - - -== Model SPI -=== Registering Configuration Models - -The model extension also provides an SPI where customized functionality can be added. The main abstraction hereby is -the +ModelProviderSpi+ interface, which allows any kind of additional config models to be added to the system: - -[source,java] ------------------------------------------------------------ -public interface ModelProviderSpi { - - Collection<ConfigModel> getConfigModels(); - -} ------------------------------------------------------------ - -New instances implementing this interface must be registered into the current +ServiceContext+, by default the -+ServiceLoader+ is used. - - -=== The ConfigUsageStatsSpi - -The methods for managing and tracking of configuration changes are similarly delegated to an -implementation of the +org.apache.tamaya.model.spi.ConfigUsageStatsSpi+ SPI. -By implementing this SPI and registerting it with the +ServiceContext+ the usage tracking -logic can be adapted or replaced. - -=== Other Utility Classes - -The module also provides further utility classes that may be useful for implementing models or testing: - -* +AbstractModel+ provides a base class that can be extended, when implementing +ConfigModel+. -* +AreaConfigModel+ provides a +ConfigModel+ implementation (with a corresponding +Builder+) to model the - requirement of certain configuration sections being present, or opionally present, in the model. -* +ParameterModel+ provides an implementation base class for validating parameters on existence and compliance - with a regular expression. -* +ConfigDocumentationMBean+ is the MBean registered that models similar functionality as +ConfigModelManager+. -* +ConfigModelGroup+ provides a +ConfigModel+ that groups several child models. -* +ConfigModelReader+ allows to read +ConfigModels+ from properties files as described at the beginning of this - document. - - -=== Switches to enable/disable functionality - -The model module provides different switches that can be used to activate or deactivate features: - -* +tamaya.model.integrated.enabled+ allows to deactivate reading inline metaconfiguration delivered with - the normal Tamaya Configuration. By default inline entries (+_.abcd.model.*+) are evaluated. -* +tamaya.model.default.enabled+ allows to deactivate reading metamodel information from - +classpath:META-INF/configmodel.properties+. By default it is active. -* +tamaya.model.resources+ allows to define additional resources (loaded through the resources extension), - that can be used to read metamodel information in any format using Tamaya's format module. -* the system property +tamaya.model.autoModelEvents+ allows to activate/deactivate the automatic - documentation of classes configured and published by Tamaya +ConfiguredType+ event instances (e.g. published by - Tamaya's injection modules). http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/extensions/mod_usagetracker.adoc ---------------------------------------------------------------------- diff --git a/src/site/asciidoc/extensions/mod_usagetracker.adoc b/src/site/asciidoc/extensions/mod_usagetracker.adoc new file mode 100644 index 0000000..41d4871 --- /dev/null +++ b/src/site/asciidoc/extensions/mod_usagetracker.adoc @@ -0,0 +1,169 @@ +// 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: Usage Tracking + +toc::[] + + +[[Core]] +== Tamaya Usage Tracking (Extension Module) +=== Overview + +Tamaya Usage Tracking allows to record and count the configuration access and consumer locations in your local +VM. + +=== Compatibility + +The module is based on Java 7, so it can be used with Java 7 and beyond. + +=== Installation + +To benefit from configuration mutability support you only must add the corresponding dependency to your module: + +[source, xml] +----------------------------------------------- +<dependency> + <groupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-usagetracker</artifactId> + <version>{tamayaVersion}</version> +</dependency> +----------------------------------------------- + + +=== Tracking Configuration Access + +The model module also allows tracking which code accesses configuration properties or configuration parameters. +It checks the stacktrace to evaluate the calling code location, hereby any unwanted packages can be implicitly +ommitted from the stacktrace. Also the maximal length of the stacktrace retained can be constraint in length. +The usages are recorded as +Usage+ instances. Hereby for each parameter accessed a corresponding +Usage+ +instance is created. It can be accessed by calling +Usage ConfigUsageStats.getUsage(String key)+. Usage +statistics for calling +Configuration.getProperties()+ can be obtained calling +Usage getUsageAllProps();+. + +Usage tracking is disabled by default. It can be enabled by calling +ConfigUsageStats.enableUsageTracking(true);+. ++ConfigUsageStats.isUsageTrackingEnabled()+ returns the current tracking status. + +The +Usage+ class itself provides access to further fainer grained usage data (+AccessDetail+) containing: + +* the access point (+fqn.ClassName#method(line: xxx)+). +* the number of accesses +* the first an last access +* the values read +* the access stacktrace (filtered by ignored packages). + +[source,java] +----------------------------------------------------------- +public final class Usage { + [...] + public String getKey(); + public void clearMetrics(); + public int getReferenceCount(); + public int getUsageCount(); + public Collection<AccessDetail> getAccessDetails(Class type); + public Collection<AccessDetail> getAccessDetails(Package pack); + public Collection<AccessDetail> getAccessDetails(String lookupExpression); + public Collection<AccessDetail> getAccessDetails(); + public void trackUsage(String value); + public void trackUsage(String value, int maxTraceLength); + + + public static final class AccessDetail { + [...] + public void clearStats(); + public long trackAccess(String value); + public long getAccessCount(); + public String getAccessPoint(); + public long getFirstAccessTS(); + public long getLastAccessTS(); + public String[] getStackTrace(); + public Map<Long, String> getTrackedValues(); + } + +} +----------------------------------------------------------- + +With +ConfigUsageStats.clearUsageStats()+ the collected statistics can be reset at any time. Summarizing the main +singleton for configuration statistics is defined as follows: + +[source,java] +----------------------------------------------------------- +public final class ConfigUsageStats{ + public static Set<String> getIgnoredUsagePackages(); + public static void addIgnoredUsagePackages(String... packageName); + public static void enableUsageTracking(boolean enabled); + public static Usage getUsage(String key); + public static Collection<Usage> getUsages(); + public static void clearUsageStats(); + public static Usage getUsageAllProperties(); + public static boolean isUsageTrackingEnabled(); + public static String getUsageInfo(); +} +----------------------------------------------------------- + +==== Customizing the Stacktrage for Usage Reporting + +The stacktrace tracked by the system can be customized in several ways: + +* +ConfigUsageStats.addIgnoredPackageNames(String...)+ allows to add additional ignored package names. +* With +Usage.setMaxTraceLength(int)+ the maximal size of the stacktraces logged can be set. Setting a + negative value will disable stacktrace logging completelely. + + +=== Accessing Usage Statistics + +Bascially usage statistics are available in two forms: + +* The +Usage/AccessDetail+ object tree can be accessed programmatically from the +ConfigUsageStats+ + singleton. +* With +ConfigUsageStats.getUsageInfo()+ also a textual representation of the usage statistics + can be obtained, as illustrated below (a snipped from the current test output): + +[source,listing] +----------------------------------------------------------- +Apache Tamaya Configuration Usage Metrics +========================================= +DATE: Sat Apr 30 21:51:09 CEST 2016 + +220 <<all>>: + - 220 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016 +3 java.version: + - 2 test.model.TestConfigAccessor#readProperty(line:43), first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016 + - 1 <unknown/filtered/internal> , first=Sat Apr 30 21:51:09 CEST 2016, last=Sat Apr 30 21:51:09 CEST 2016 + +----------------------------------------------------------- + + +=== Auto-Documentation of Classes with Configuration Injection + +A special feature of this module is that it observes +ConfigEvent+ published through Tamaya'as event channel +(+tamaya-events+ module). If no metaconfiguration model is found the model manager by default automatically creates +models for all injected instances on the fly. In the case of CDI integration this happens typically during deployment +time, since CDI initializes during deployment time. Other runtime platforms, such as OSGI, may have rather different +behaviour. Nevertheless this means that after your system has been started you should have access to a complete +set of +ConfigModel+ instances that automatically document all the classes in your system that consume configuration +(through injection). + + +== UsageTracker Module SPI + +=== The ConfigUsageStatsSpi + +The methods for managing and tracking of configuration changes are similarly delegated to an +implementation of the +org.apache.tamaya.model.spi.ConfigUsageStatsSpi+ SPI. +By implementing this SPI and registerting it with the +ServiceContext+ the usage tracking +logic can be adapted or replaced. + http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/92461384/src/site/asciidoc/extensions/mod_validation.adoc ---------------------------------------------------------------------- diff --git a/src/site/asciidoc/extensions/mod_validation.adoc b/src/site/asciidoc/extensions/mod_validation.adoc new file mode 100644 index 0000000..777a1d7 --- /dev/null +++ b/src/site/asciidoc/extensions/mod_validation.adoc @@ -0,0 +1,111 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + += Apache Tamaya -- Extension: Configuration Validation + +toc::[] + + +[[Remote]] +== Tamaya Validation: Validating Configuration (Extension Module) +=== Overview + +The Tamaya Validation extension adds support to validate a configuration against a set of rules +defined in a Tamaya Metaconfiguration XML file. + +=== Compatibility + +The module is based on Java 7, so it will not run on Java 7 and beyond. + + +=== Installation + +To benefit from Tamaya Metamodel feature you only must add the corresponding dependency to your module: + +[source, xml] +----------------------------------------------- +<dependency> + <groupId>org.apache.tamaya.ext</groupId> + <artifactId>tamaya-validation</artifactId> + <version>{tamayaVersion}</version> +</dependency> +----------------------------------------------- + +The component will extend Tamaya's +tamaya-metamodel+ module and adds an additional meta provider ruleset +so validation rules can also be added to the default meta configuration XML file as separate sections. + + +=== Usage + +This module expects meta-configuration to be located at the following locations. Hereby multiple files +are supported: + +[source, text] +----------------------------------------------- +-Dtamaya-validation=<an URL> // any resolvable URL +./tamaya-validation-*.xml // file +META-INF/tamaya-validation-*.xml // classpath (multiple entries-possible) +----------------------------------------------- + +=== The Validation XML Format + +The configuration validation is defined by simple configuration meta-data entries. + +[source, xml] +----------------------------------------------- +<configuration-validation> + ... + <provider>The Validation Provider</provider> <!-- optional --> + <section name="org.mycompany"> + <section name="security" required="true"> + <description>The description of ma area.</description> + </section> + </section> + <section name="minimal"/> + <section name="validated.sections" at-least="1"> + <section name="customValidated" validator="myFQValidatorClassName"/> + <section name="withParams" > + <param name="int" type="int"/> + <param name="aText" expression="[a|b|c]" required="true"/> + <param name="aValidatedText" validator="myValidatorClass"> + <description>This kind of params are more complex...</description> + </param> + </section> + </section> + <validator class="a,b,c,MyGlobalValidator"/> +</configuration-validation> +----------------------------------------------- + +==== The Example Explained + +* The *provider* entry is used for generating validation message, when a validation fails. +* Section itself can be recursively defined, where each level can have it's own validations. +* Sections added, but without validation rules are _defined_ section. Configuration outside of + defined sections can be flagged out using WARNING messages. +* Sections can be _reuired_ and additionally also _validated_. +* There is also the possibility to register global validators, which are called by the validation + logic once a configuration has been completely loaded. + +Similar to sections also parameters can be validated: + +* they can be marked as _required_ +* they can have a certain type, meaning they must be convertible to the given type +* they can have an additional custom validator. +* they can have an optional description for error analysis and error output. + +Similar to section parameters that are not defined, but encountered may be flagged out with +a WARNING message.
