http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/documentation/usecases.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/usecases.adoc b/content/documentation/usecases.adoc new file mode 100644 index 0000000..0d0d4e0 --- /dev/null +++ b/content/documentation/usecases.adoc @@ -0,0 +1,488 @@ +:jbake-type: page +:jbake-status: published + +== Apache Tamaya: Use Cases and Requirements + +toc::[] + +== Use Cases + +=== Simple Access + +Users want to be able to access configuration in a unified way both in SE and EE. EE may provide additional +mechanism, such as injection, but the SE mechanisms should work as well, so any code written in SE is fully +portable to EE as well. +This can only be achieved by providing a static accessor, e.g. + +[source,java] +------------------------------------------------------------ +Configuration config = Configuration.current(); +------------------------------------------------------------ + +The call above should work exactly the same in EE. To enable this the static call must be delegated in the +internals of the singleton, depending on the runtime. In EE the executing component can behave contextually, +or even be loaded within the CDI environment (at least for post loading, application runtime aspects, but not earlier). + +Additionally in EE it should also be possible to inject Configuration, which gives you the same results as the call +above: + +[source,java] +------------------------------------------------------------ +@Inject +private Configuration cfg; +------------------------------------------------------------ + + +=== Simple Lookup of Properties + +Users just want to create a configuration ad hoc, from given property files. The +files could be locally in the file system, on the classpath. + +Tamaya should provide a simple Java API for accessing key/value based configuration. Hereby users want to access +properties as simple String values. + +Hereby returning Java 8 Optional values must be considered as well, instead of returning +null+. + + +=== Value Placeholders + +Users just want to to be able to add placeholders to the values of configuration (not the keys). The mechanisms for +resolving the placeholders hereby should be not constraint to one single lanmguage like EL. Instead of different +replacement strategies should be selectable, e.g. by prefixing an expression with the name of the resolver that +should do the work (eg +"blabla ${env:HOME} using Java version ${sys:java.version}."+. +This allows resolution mechanism to be isolated easily and also allows to use simpler mechanisms, if no more complex +ones like EL are required. This is especially useful to deal with low resource environment like ME. + + +=== Type Safe Properties + +Users just want to access properties not only as Strings, but let Tamaya do the conversion to the required +or the configred target type. By defauklt all java.ui.lang wrapper and primitive types should be supported, but also +other common types like date/time types, math numeric types and more. + +It must be possible that users can register their own custom types. + +Finally users also want to be able to dynamically provide or override type adaption (conversion), when reading a value, +for a certain key/value pair. + + +=== Configuration Templates + +Users want to be able to let Tamaya implement an interface template based on configuration. +This use case is pretty similar to the injection use case. Basically the values are not injected, +but cached within the template proxy returned, e.g. as +DynamicValue+. +Similarly it could even be possible to define callback methods (default methods) +or register listeners to DynamicValue instances returned. + +Templates hereby can easily be managed, but provide a excellent mechanism to provide type-safe configuration +to clients in a very transparent way. Details can be controlled by using the same annotations as for +normal configuration injection. + + +=== Java 8 Functional Support + +Users want to be able to benefit from the new programming styles introduced with Java 8. Configuration +should provide extension points for different aspects, where additional code can be hooked in easily. +In short: were possible functional interfaces should be modelled. + +Examples: + +* code that converts a configuration to another kind of configuration: +UnaryOperator<Configuration>+ +* code that creates any kind of result based on a configuration: +Function<Configuration,T>+ +* Adapters for type conversion are defined as +Function<String,T>+ +* Key, value filters ccan be modelled as +BiFunction<String,String,String>+ +* etc. + + +=== Configuration Locations + +Users want to be able to + +* read configuration from different locations. +* By default classpath and file resources are + supported. But similarly remote access using a JSON ReST call should be possible. +* Tamaya should define a JSON and XML format for configuration. +* Configuration locations should be scannable using ant-styled resource patterns, if possible. +* Scanning and reading logic can be modularized by using a +ConfigReader+ interface. + + +=== Configuration Formats + +Users want to be able to use the format they prefer. + +* properties, xml-properties and ini-format should be supported by default +* Other/custom formats should be easily addable by registering or providing the format on configuration evaluation (read). +* When possible Tamaya should figure out which format to be used and how the InputStream should be correctly + interpreted. + + +=== Multiple Configurations + +When systems grow they must be modularized to keep control. Whereas that sounds not really fancy, it leads to additional +aspects to be considered by a configuration system. + +* Different code modules, libraries, plugins or products want to have their "own" separated configuration. +* Similar it should be possible to add fully specific additional configurations. + +The default configuration hereby should always be present, whereas additional configurations are optional. +Users want to be able to check the availability of such an additional configuration. + +Of course, additional configuration must be identifiable. The best way to do is to be discussed, nevertheless the +mechanism must not depend on Java EE and the identifying keys must be serializable easily. +Basically simple names are sufficient and woukld provide exact this required functionality. + + +=== External Configuration + +Users want to be able to replace, override, extend or adapt any parts or all of an existing configuration from +external sources. +This also must be the case for multi-context environments, where the context identifiers are +the only way to link to the correct remote configuration. + + +=== Context Dependent Configuration + +In multi tenancy setups or complex systems a hierarchical/graph model of contexts for configurations is required, or different runtime contexts are executed in parallel +within the same VN. What sounds normal for EE also may be the case for pure SE environments: + +* Users want to be able to model different layers of runtime context +* Users want to identify the current layer, so configuration used may be adapted. + + + +=== Dynamic Provisioning (UC8) + +In Cloud Computing, especially the PaaS and SaaS areas a typical use case would be that an application (or server) +is deployed, configured and started dynamically. Typically things are controlled by some "active controller components", +which are capable of + +* creating new nodes (using IaaS services) +* deploying and starting the required runtime platform , e.g. as part of a PaaS solution. +* deploying and starting the application modules. + +All these steps require some kind of configuration. As of today required files are often created on the target node +before the systems are started, using proprietary formats and mechanism. Similarly accessing the configuration in place +may require examining the file system or using again proprietary management functions. Of course, a configuration +solution should not try to solve that, but it can provide a significant bunch of functionality useful in such scenarios: + +* provide remote capabilities for configuration +* allow configuration to be updated remotely. +* allow client code to listen for configuration changes and react as needed. + + +=== Minimal Property Source SPI + +Users expect that implementing an additional configuration property source is as easy as possible. +So there should be an SPI defined that allows any kind of data source to be used for providing configuration data. +The interface to be implemented is expected to be minimal to reduce the implementation burden. Default +methods should be used where possible, so only a few methods are expected to be required to implement. + + +=== Scannable Properties + +If possible configuration should be scannable, meaning it should be possible to evaluate the keys available. +The corresponding capabilities should be accessible by a +isScannable()+ method. + + +=== Combine Configurations + +Users want to be able to combine different configurations to a new configuration instance. +Hereby the resulting configuration can be + +* a union of both, ignoring duplicates (and optionally log them) +* a union of both, duplicates are ignored +* a union of both, conflicts are thrown as ConfigException +* an intersection of both, containing only keys present and equal in both configurations +* an arbitrary mapping or filter, modelled by an +CombinationPolicy+, which basically can be modelled + as +BiFunction<String, String, String>+, hereby + ** a result of +null+ will remove the key + ** any other result will use the value returned as final value of the combination. + + +=== MX/ReST Management + +Users want to be have comprehensive management support, which should allow + +* to change configuration +* to remove configuration +* to view configuration and its provider details + + +=== Adaptable Service Context + +Tamaya should support an adaptable +ServiceContext+ to resolve any kind of implememntation services, both API services as core +framework services. The +ServiceContext+ should be dynamically replecable by configuring an alternate instance of +using the Java *ServiceContet+. + +This decouples component usage from its load and management part and als greatly simplifies integration with +new/alternate runtime environments. +The service context is exptected to provide + +* single singleton instances: these service can be cached. +* access to multiple instances which implement some commons SPI interface. +* as useful priorization of components is done by the model itself. + + +=== Configuration Injection + +Users want to be able to polulate configured items by injecting configured values. Hereby + +* the lifecycle of the instances is not managed by Tamaya +* all references to items configured are managed as weak references, to prevent memoryleaks. +* Injection should if possible evaluate the properties by defaults. Even properties without + any annotations are possible. +* Users expect to exclude certain properties from calculation +* Beside injection of properties it is also possible to call setter methods with one parameter similarly. +* Basically injection is performed, when the instance is passed to the Tamaya configuration system. It should also + be possible to inject/provide final values, especially Strings. Changes on configured values should be + reflected in the current value. Setters methods similarly can be called again, with the new values, on changes. +* Users expect to control dynamic values and recall of setter methods, basically the following strategies should be + supported: + ** inject only once and ignore further changes. + ** reinject/reinitialize on each change + +* Dynamic Values can easily be modeled as +ConfiguredValue+ instances, which should have the following functionality: + ** access the current value + ** access the new value + ** access the latest value access time in ms + ** access the latest value update time in ms + ** evaluate easily if the value has changed since the last access + ** accept the change + *** as a shortcut it should be possible to accept the change on access of the value implicitly, hereby always accessing + the latest valid value. + ** ignore the change + ** register +Consumer<DynamicValue>+ liasteners to listen on the changes (ans also removing them later again). + +All observing functionality can be done completely asynchronously and in parallel. + + +[[Requirements]] +== Requirements +=== Core Configuration Requirements +==== General + +Tamaya must provide a Java SE API for accessing key/value based configuration. Hereby + +* +Configuration+ is modelled by an interface +* +Configuration+ is organized as key/value pairs, using a subset of functionality present on +Map<String,String>+ as + follows: + ** access a value by key (+get+) + ** check if a value is present (+containsKey+) + ** get a set of all defined keys (+keySet+) + ** a configuration must be convertible to a +Map+, by calling +toMap()+ + ** a configuration must provide access to its meta information. +* +Configuration+ value access methods must never return null. +* The API must support undefined values. +* The API must support passing default values, to be returned if a value is undefined. +* The API must allow to throw exceptions, when a value is undefined. Customized exceptions hereby should be supported. +* Properties can be stored in the classpath, on a file or accessible by URL. +* Properties can be stored minimally in properties, xml-properties or ini-format. + + +==== Minimalistic Property Source + +For enabling easy integration of custom built configuration sources a minimalistic API/SPI must be defined, that + +* is modelled by an interface +* is a minimal subset of +Configuration+ necessary to implement a configuration. +* must be convertible to a "Configuration+. + +==== Extension Points + +For supporting more complex scenarios, +Configuration+ + +* must implement the composite pattern, meaning new +Configuration+ instances can be created by combining existing + configurations. +* must be adaptable, by creating a new configuration by applying a +UnaryOperator<COnfiguration>+ to it. +* must be queryable, by passing a +ConfigQuery+ to an +Configuration+ instance. + + +==== Type Safety + +Besides Strings +Configuration+ should also support the following types: + +* Primitive types +* Wrapper types +* All other types (by using a +PropertyAdapter+ + +Hereby type conversion should be done as follows: + +. Check if for the given target type an explicit adapter is registered, if so, use the registered adapter. +. If no adapter is present, check if the target type T has static methods called +T of(String), T getInstance(String), T valueOf(String), T from(String)+. If so +use this method to create the non value of T. +. Check if the target type has a constructor T(String). If so, try to instantiate an instance using the constructor. +. Give up, throw a IllegalArgument exception. + +=== Configuration Fomats + +By default Tamaya support the following configuration formats: + +* .properties +* .xml properties +* .ini files + +It must be possible to add additional formats by registering them with the current +ServiceContext+. + +=== Mutability + +* Configurations can be mutable, mutability can be accessed as a property. +* Configuration can be changed by collecting the changes into a +ConfigCHangeSet+ and apply this set to the + given +Configuration+ instance. +* Besides the points above, +Configuration+ is immutable. + +=== Serializability and Immutability of Configuration + +* Configuration is modelled as a service. Therefore serialization may not work. This can be mitigated by adding + a freeze feature, where the know key/value pairs are extracted into an immutable and serializable form. + +=== Configuration Combination Requirements + +At least the following composition policies must be supported: + +* override: subsequent entries override existing ones. +* aggregate-exception: key/values were added, in case of conflicts a +ConfigException+ must be thrown. +* aggregate-ignore-duplicates: similar to union, whereas duplicates are ignored (leaving the initial value loaded). +* aggregate-combine: conflicting entries were resolved by adding them both to the target configuration by + redefining partial keys. +* custom: any function determining the key/values to be kept must be possible + +When combining configuration it must also be possible to override (file/classpath) configuration by + +* system properties. +* command line arguments. + + +=== Configuration Injection + +As metnioned configuration can be injected by passing a unconfigured instance of an annotated class to the ++Configuration.configure+ static method: + +[source, java] +.Configuring a POJO +---------------------------------------------------- +MyPojo instance = new MyPojo(); +Configuration.configure(instance); +---------------------------------------------------- + +Hereby +* It must be possible to define default values to be used, if no valid value is present. +* It must be possible to define dynamic expressions, at least for default values. +* The values configured can be reinjected, if the underlying configuration changes. This should also be the case + for final classes, such as Strings. +* Reinjection should be controllable by an loading policy. +* It must be possible to evaluate multiple keys, e.g. current keys, and as a backup deprecated keys + from former application releases. +* It must be possible to evaluate multiple configurations. +* The type conversion of the properties injected must be configurable, by defining a +PropertyAdapter+. +* The value evaluated for a property (before type conversion) must be adaptable as well. +* It must be possible to observe configuration changes. + +The following annotations must be present at least: + +* *@ConfiguredProperty* defining the key of the property to be evaluated. It takes an optional value, defining the + property name. It must be possible to add multiple annotations of this kind to define an order of evaluation + of possible keys. +* *@DefaultValue* (optional) defines a default String value, to be used, when no other key is present. +* *@WithConfig* (optional) defines the name of the configuration to be used. Similar to +@ConfiguredProperty+ multiple + configuration can be defined for lookup. +* *@WithConfigOperator* allows to adapt the String value evaluated, *before* it is passed as input to injection or + type conversion. +* *@WithPropertyAdapter* allows to adapt the conversion to the required target type, hereby overriding any default + conversion in place. +* *@WithLoadPolicy* allows to define the policy for (re)injection of configured values. +* *@ObservesConfigChange* allows to annotate methods that should be called on configuration changes. +* *@DefaultAreas" allows to define a key prefix key to be used for the configured key, if no absolute key + is defined. + +=== Configuration Templates + +For type safe configuration clients should be able to define an interface and let it implement by the +configuration system based on +Configuration+ available: + +* Clients define an interface and annotate it as required (similar to above) +* The interface methods must not take any arguments +* The configuration system can be called to return such an interface implementation. +* The configuration system returns a proxy hereby providing type-safe access the values required. +* Similar to configured types also templates support multiple values and custom adapters. +* It is possible to listen on configuration changes for templates, so users of the templates + may react on configuration changes. + +The following snippet illustrates the requirements: + +[source, java] +.Type Safe Configuration Template Example +---------------------------------------------------- +public interface MyConfig { + + @ConfiguredProperty("myCurrency") + @DefaultValue("CHF") + String getCurrency(); + + @ConfiguredProperty("myCurrencyRate") + Long getCurrencyRate(); + + @ConfigChange + default configChanged(ConfigChange event){ + ... + } + +} +---------------------------------------------------- + +Templates can be accessed by calling the +Configuration.current(Class)+ method: + +[source, java] +.Accessing a type safe Configuration Template +---------------------------------------------------- +MyConfig config = Configuration.current(MyConfig.class); +---------------------------------------------------- + +[[RequirementsServer]] +=== Server Configuration Requirements + +* Ensure Configuration can be transferred over the network easily. +* Beside serializability text based formats for serialization in +XML+ and +JSON+ must be defined. +* A management API must be defined, which allows to inspect the configuration in place, e.g. using + JMX or REST services. + +[[RequirementsJavaEE]] + +Java EE leads to the following requirements: + +* Configuration must be contextual, depending on the current runtime context (e.g. boot level, ear, war, ...). +* Hereby contextual aspects can even exceed the levels described above, e.g. for SaaS scenarios. +* Resources can be unloaded, e.g. wars, ears can be restarted. +* The different contextual levels can also be used for overriding, e.g. application specific configuration +may override ear or system configuration. +* Configuration may be read from different sources (different classloaders, files, databases, remote locations). +* Configuration may be read in different formats (deployment descriptors, +ServiceLoader+ configuration, alt-DD feature, ...) +* JSF also knows the concept of stages. +* Many SPI's of Java EE require the implementation of some well defined Java interface, so it would be useful if the + configuration solution supports easy implementation of such instances. +* In general it would be useful to model the +Environment+ explicitly. +* Configuration used as preferences is writable as well. This requires mutability to be modelled in way, without the + need of synchronization. +* JNDI can be used for configuration as well. + +[[RequirementsMultitenancy]] + +Configurations made in the tenant or user layer override the default app configuration etc., so + +* It must be possible to structure Configuration in layers that can override/extend each other. +* The current environment must be capable of mapping tenant, user and other aspects, so a corresponding configuration + (or layer) can be derived. + +[[RequirementsExtensions]] +=== Extensions Requirements + +It must be possible to easily add additional functionality by implementing external functional interfaces operating +on +Configuration+. + +* +UnaryOperator<Configuration>+ for converting into other version of +Configuration+. +* +ConfigQuery<T>+ extending +Function<T, Configuration>+. + +[[RequirementsNonFunctional]] +=== Non Functional Requirements +THe following non-functional requirements must be met: + +* tbd
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions.adoc ---------------------------------------------------------------------- diff --git a/content/extensions.adoc b/content/extensions.adoc deleted file mode 100644 index a95f22f..0000000 --- a/content/extensions.adoc +++ /dev/null @@ -1,62 +0,0 @@ -:jbake-type: page -:jbake-status: published - -== Apache Tamaya: Extension Modules - -toc::[] - -=== Mature Extensions - -Mature extensions have a stable API and SPI, similar to the API and Implementations provided. - -[width="100%",frame="1",options="header",grid="all"] -|======= -|_Artifact_ |_Description_ |_Links_ -| | N/A: currently no extensions have reached that maturity level. | - -|+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation] -|+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation] -|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation] -|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation] -|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation] -|+org.apache.tamaya.ext:tamaya-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-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-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-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] -|+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation] -|======= - - -=== Extensions Sandbox - -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-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] -|======= http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_builder.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_builder.adoc b/content/extensions/mod_builder.adoc deleted file mode 100644 index a589374..0000000 --- a/content/extensions/mod_builder.adoc +++ /dev/null @@ -1,83 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: Builder - -[[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}</version> -</dependency> ------------------------------------------------ - -=== Supported Functionality - -The builder allows you to add +PropertySource+ instances: - -[source,java] ----------------------------------------------------------------- -ConfigurationBuilder builder = new ConfigurationBuilder(); -builder.addPropertySources(sourceOne).addPropertySources(sourceTwo); -Configuration config = builder.build(); ----------------------------------------------------------------- - -Similarly you can add filters: - -[source,java] ----------------------------------------------------------------- -builder.addPropertyFilters(new MyConfigFilter()); ----------------------------------------------------------------- - -...or +PropertySourceProvider+ instances: - -[source,java] ----------------------------------------------------------------- -builder.addPropertySourceProvider(new MyPropertySourceProvider()); ----------------------------------------------------------------- - -Also the builder module allows to include/exclude any filters and property source already known to the current -+ConfigurationContext+: - -[source,java] ----------------------------------------------------------------- -builder.disableProvidedPropertyConverters(); -builder.enableProvidedPropertyConverters(); - -builder.disableProvidedPropertyFilters(); -builder.enableProvidedPropertyFilters(); - -builder.disableProvidedPropertySources(); -builder.enableProvidedPropertySources(); ----------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_camel.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_camel.adoc b/content/extensions/mod_camel.adoc deleted file mode 100644 index 9690dda..0000000 --- a/content/extensions/mod_camel.adoc +++ /dev/null @@ -1,129 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: Integration with Apache Camel - -toc::[] - - -[[Optional]] -== Integration with Apache Camel (Extension Module) -=== Overview - -The Tamaya Camel integration module provides different artifacts which allows integration of Apachae Tamaya -configuration with Apache Camel. - - -=== Compatibility - -The module is based on Java 7, so it will not run on Java 7 and beyond. - - -=== Installation - -To benefit from configuration builder support you only must add the corresponding dependency to your module: - -[source, xml] ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-camel</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - - -=== The Extensions Provided - -Camel integration comes basically with three artifacts: - -* A Camel +ResolverFunction+ implementation adding explicit property resolution - (+org.apache.tamaya.integration.camel.TamayaPropertyResolver+). -* A Camel +PropertiesComponent+ implementation, which allows implicitly preconfigures the resolvers from above and - additionally allows using Tamaya configuration as Camel _overrides_ - (+org.apache.tamaya.integration.camel.TamayaPropertiesComponent+). - - -=== Configuring using Camel Java DSL - -Camel integration using Java DSL is basically simple: - -[source, java] ------------------------------------------------ -import org.apache.tamaya.integration.camel.TamayaPropertiesComponent; - -camelContext.addComponent("properties", new TamayaPropertiesComponent()); ------------------------------------------------ - -Given so you can then use +cfg+ or +tamaya+ as prefix for resolving entries with Tamaya as follows: - -[source, java] ------------------------------------------------ -RouteBuilder builder = new RouteBuilder() { - public void configure() { - from("direct:hello1").transform().simple("{{cfg:message}}"); - } -}; -camelContext.addRoutes(builder); -builder = new RouteBuilder() { - public void configure() { - from("direct:hello2").transform().simple("{{tamaya:message}}"); - } -}; -camelContext.addRoutes(builder); ------------------------------------------------ - - -Optionally you can also configure +TamayaPropertiesComponent+ that all currently known Tamaya properties are used -as Camel overrides, meaning they are evaluated prior to all other available resolver functions in the Camel -+PropertiesComponent+: - -[source, java] ------------------------------------------------ -TamayaPropertiesComponent props = new TamayaPropertiesComponent(); -props.setTamayaOverrides(true); ------------------------------------------------ - - -=== Configuring using Camel XML DSL - -Camel integration using XML DSL is basically very similar. You just have to add the +properties+ component as bean -as well. All other configuration parameters (e.g. file URIs are similar supported). In the example code below we -again use Tamaya as the main configuration solutions only using Camel's default behaviour as a fallback: - -[source, xml] ------------------------------------------------ -<beans xmlns="http://www.springframework.org/schema/beans"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation=" - http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd - http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd - "> - - <routeContext id="myCoolRoutes" xmlns="http://camel.apache.org/schema/spring";> - <route id="r1"> - <from uri="direct:hello1"/> - <transform> - <simple>{{message}}</simple> - </transform> - </route> - <route id="r2"> - <from uri="direct:hello2"/> - <transform> - <simple>{{cfg:message}}</simple> - </transform> - </route> - <route id="r3"> - <from uri="direct:hello3"/> - <transform> - <simple>{{tamaya:message}}</simple> - </transform> - </route> - </routeContext> - - <bean id="properties" class="org.apache.tamaya.integration.camel.TamayaPropertiesComponent"> - <property name="tamayaOverrides" value="true"/> - </bean> - -</beans> ------------------------------------------------ http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_cdi.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_cdi.adoc b/content/extensions/mod_cdi.adoc deleted file mode 100644 index c49a61c..0000000 --- a/content/extensions/mod_cdi.adoc +++ /dev/null @@ -1,217 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: Classloader Isolation Support - -toc::[] - - -[[Remote]] -== Tamaya CDI Integration (Extension Modules) -=== Overview - -Apache Tamaya currently provides two implementations for integration with CDI extensions implementing similar -functionality as described in this document: - -* Loading of CDI managed SPI components as configuration extensions such as +PropertySources, PropertySourceProviders, - PropertyFilters, etc+. This also includes SPI defined by any Tamaya submodules. -* Implement and enable Tamaya's configuration injection services with CDI. - -Hereby there are two implementations provided: - -* +tamaya-cdi-ee+ implements injection by using CDI's injection mechanism to inject configuration values into the - beans managed by the CDI systems. -* +tamaya-cdi-se+ implements injection by integrating the +tamaya-injection+ SE based injection module (also used - for Spring and OSGI injection) with CDI. Injection hereby is performed by the Tamaya SE module, whereas - beans and injection control overall are still managed by CDI. -* One difference, of course, is that +tamaya-se+ also provides an SE compatible API (+ConfigurationInjection, - ConfigurationInjector+), which is not available, when using the purely Java EE based variant. - -The annotations used for all injection functionality in Tamaya is defined as a separate module. This allows you to -code against the injection API without dependency on the concrete injection implementation. As a consequence your -components will be compatible regardless if deployed in a pure SE, a Java EE (CDI) or OSGI or Spring environment: - ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-injection-api</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - - -=== Compatibility - -Both modules are based on Java 7, so they will not run on Java 7 and beyond. - - -=== Installation - -To benefit from Tamaya CDI integration you only must one of the following dependencies to your module. Ensure that -you never have installed both CDI extensions at the same time because this may be lead to unforseen side-effects. - -.CDI Pure Application Configuration -[source, xml] ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-cdi-ee</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - -.CDI enhanced with Tamaya SE Application Configuration -[source, xml] ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-cdi-se</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - -Both components will auto-register its components and override the default +ServicceContext+ in use. Additionally they -register CDI extensions that implement Configuration injection as described before. - -IMPORTANT: Never install Tamaya's +tamaya-cdi-se+ and +tamaya-cdi-ee+ on the same system, since unpredictable side - effects could occur. - -=== Registering CDI managed components into the Application's ConfigurationContext - -As mentioned both modules allow to provide Tamaya SPI extensions modules as ordinary CDI managed beans. By default -extensions should be registered using +@Singleton+ or +@ApplicationScoped+ scope annotations. So you can define/deploy -additional application specific +PropertySources+ and other artifacts simply by defining a CDI managed bean implementing -the required SPI interface: - -[source, java] --------------------------------------------------------- -@Singleton -public class TestPropertySource implements PropertySource{ - - final Map<String,String> config = new HashMap<>(); - - public TestPropertySource(){ - config.put("a.b.c.key1", "keys current a.b.c.key1"); - config.put("a.b.c.key2", "keys current a.b.c.key2"); - config.put("{"+getName()+"}source", getClass().getName()); - } - - @Override - public int getOrdinal() { - return 10; - } - - @Override - public String getName() { - return getClass().getName(); - } - - @Override - public String get(String key) { - return config.get(key); - } - - @Override - public Map<String, String> getProperties() { - return config; - } - - @Override - public boolean isScannable() { - return true; - } -} --------------------------------------------------------- - -Note that for many SPI's there is a priority mechanism using +@Priority+ annotations in place. -The +ServiceContext+ implementation combines the components registered with the ones loaded from the +ServiceLoader+ -mechanism hereby considering classloaser hierarchies. - - -=== Annotating your Classes - -Basically annotating your classes is stright forward. +@Config+ defines an additional CDI qualifier that is, depending -on the module deployed, handled by a CDI producer (+tamaya-cdi-ee+) or the Tamaya SE injection mechanism $ -(+tamaya-cdi-se+). All types injected by this module are injected using _dependent scope_. - - -[source, java] --------------------------------------------------------- -@RequestScoped -public class ConfiguredClass{ - - @Config - private String testProperty; - - @Config({"a.b.c.key1","a.b.c.key2","a.b.c.key3"}) - @ConfigDefault("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.") - String value1; - - @Config({"foo","a.b.c.key2"}) - private String value2; - - @Config - @ConfigDefault("N/A") - private String runtimeVersion; - - @Config - @ConfigDefault("${sys:java.version}") - private String javaVersion2; - - @Config - @ConfigDefault("5") - private Integer int1; - - ... - -} --------------------------------------------------------- - -=== Advanced Use Cases - -Beside basic configuration Tamaya also covers additional requirements: - -* _Reading multiple keys, where the first successful one is determining the value of the configuration, is - simply possible, by adding multiple keys to the +@Configy+ annotation. - E.g. for trying first +a.b+ and then +new.b+ you would configure it as follows: - -[source,java] --------------------------------------------------------------------------------------- -@Config({"a.b", "new.b"} -private String value; --------------------------------------------------------------------------------------- - -* When you must apply a +ConfigOperator+ to your config, before reading the configuration, you can - configure one as follows: - -[source,java] --------------------------------------------------------------------------------------- -@Config({"a.b", "new.b"} -@WithConfigOperator(MyOperator.class) -private String value; --------------------------------------------------------------------------------------- - -* When you must apply a some special conversion, or you use a type that is not registered - for conversion, you can configure a custom converter to be applied as follows: - -[source,java] --------------------------------------------------------------------------------------- -@Config({"a.b", "new.b"} -@WithPropertyConverter(MyConverter.class) -private MySpecialFooType value; --------------------------------------------------------------------------------------- - -* Often multiple keys in a class belong to the same root section. So instead of copying this to - every entry you can define the most common root sections in the type's header: - -[source,java] --------------------------------------------------------------------------------------- -@ConfigDefaultSections({"aaaa", "new"}); -public class MyType{ - -@Config({"b", "[legacy.bKey]"} // lookups: "aaaa.b", "new.b", legacy.bKey -private String value; --------------------------------------------------------------------------------------- - -In the example above +legacy.bKey+ defines an absolute key, which is not combined with any defined -default section parts. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_classloader_support.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_classloader_support.adoc b/content/extensions/mod_classloader_support.adoc deleted file mode 100644 index 9a2d0df..0000000 --- a/content/extensions/mod_classloader_support.adoc +++ /dev/null @@ -1,75 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: Classloader Isolation Support - -toc::[] - -[[Remote]] -== Tamaya Classloader Aware ServiceContext (Extension Module) -=== Overview - -The Tamaya classloader support provides an alternative implementation of +java.util.ServiceLoader+, which is aware -of classloaders, hereby preventing multiple loading of components within a classloader hierarchy. - - -=== Compatibility - -The module is based on Java 7, so it will not run on Java 7 and beyond. - - -=== Installation - -To benefit from configuration server support you only must add the corresponding dependency to your module: - -[source, xml] ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-classloader-support</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - -The component will auto.register its components and override the default +ServicceContext+ in use by default -with an instance of type +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+. This implementation returns -a priority of +10+. - -=== How it works - -Basically the component manages a +Map+ of all classloaders encountered. When services are accessed, the component -will evaluate the services as follows: - -* the component walks up the class loader hierarchy. -* in a next step the hierarchy is traversed down from the parent to the current classloader. Hereby it is checked - if the service list for the required type has been loaded already. If not the service configuration files are - evaluated. -* This configuration file evaluation will ignore all resources already loaded by any of the already traversed parent - classloaders. -* For each configuration file newly visible to the classloader currently traversed, the corresponding services are - loaded unleyy, the same service class already has been loaded by one its parent classloaders or another file - loaded with this classloader. -* Finally all services found are returned as the full collection of services valid for the given context (classloader). - -This ensures no service is loaded multiple times, even when it is referenced multiple times in several service -configurations. Additionally every service is loaded on the classloader where it is also declared the first time. - - -=== Control Logging - -The service component by default only logs errors. But it is possible to change this by reconfiguring the logging -levels on the following logging names/path: +org.apache.tamaya.clsupport.internal.CLAwareServiceContext+ - -* _INFO_ logs additional info on the services accessed. -* _FINEST_ logs additional info on the services scanned and selected. - - -=== Classloader Aware Configuration - -The mechanism above is used to provide a classloader aware implementation of +ConfigurationContext+ -(+org.apache.tamaya.clsupport.internal.CLAwareConfigurationContext+). Similarly to the service variants -this class provides a context implementation that manages the core configuration aspects considering classloading -hierarchies: - -* +PropertySource+, +PropertySourceProviders+ -* +PropertyFilters+, +PropertyCombinationPolicy+ http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_collections.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_collections.adoc b/content/extensions/mod_collections.adoc deleted file mode 100644 index e758756..0000000 --- a/content/extensions/mod_collections.adoc +++ /dev/null @@ -1,232 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: Collection Support - -toc::[] - -[[Optional]] -== Tamaya Collection Support (Extension Module) -=== Overview - -All configuration in Tamaya is expressed as simple key, value pairs. Nevertheless this concept allows similarly -the modelling of collection typed values such as lists, sets, maps or simple collections of things. The Tamaya -Collections extension adds this functionality to the Tamaya eco-system. - -=== Compatibility - -The module is based on Java 7, so it will not run on Java 7 and beyond. - - -=== Installation - -To use Tamaya collection support you only must add the corresponding dependency to your module: - -[source, xml] ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-collections</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - - -=== Overview - -Tamaya Collections adds +PropertyConverter+ implementations that are able to access configuration data -as lists, maps or sets. By default this works out of the box as easy as accessing any other type of -configuration data, e.g. - -[source, java] ------------------------------------------------ -Configuration config = ConfigurationProvider.getConfiguration(); - -// Without any content specification, a list of String is returned. -List<String> simpleList = config.get("my.list.config.entry", List.class); - -// Using a TypeLiteral allows to use every convertible sub type supported by the system. -List<Integer> intList = config.get("my.list.config.entry", new TypeLiteral<List<Integer>>(){}); ------------------------------------------------ - -Configuration in that case, by default, is a simple comma-separated list of entries, e.g. - -[source, properties] ------------------------------------------------ -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 String to be used to split the items (default is {{','}}. -* specifying a custom separator String to be used to split key/value paris when parsing map entries. -* specifying the implementation type of the collection instance to be returned. -* specifying if the resulting collection should be returned as a modifiable collection. - -=== Supported Types - -This module supports the following types: - -* +java.util.Collection+ -* +java.util.List+ -* +java.util.ArrayList+ -* +java.util.LinkedList+ -* +java.util.Set+ -* +java.util.SortedSet+ -* +java.util.TreeSet+ -* +java.util.HashSet+ -* +java.util.Map+ -* +java.util.SortedMap+ -* +java.util.HashMap+ -* +java.util.TreeMap+ - -Hereby the type is determined primarly by the parameter type accessed, e.g. -+config.get("mylist", ArrayList.class)+ will always return an +ArrayList+ -as result. - -==== Configuring the target implementation type - -Tamaya Collections allows you to configure the target collection type by adding the -following meta-configuration entry (shown for the +mylist+ entry). Hereby the package part +java.util.+ -can be ommitted: - -[ source, properties] ------------------------------------------------ -mylist=a,b,c -_mylist.collection-type=LinkedList ------------------------------------------------ - -When calling +config.get("mylist", ArrayList.class)+ this parameter does not have any effect, so you will still -get an +ArrayList+ as a result. However when you call +config.get("mylist", List.class)+ you will -get a +LinkedList+ as implementation type. - -This mechanism similarly applies to all kind of collections, so you can use it similarly to define the implementation -type returned when accessing +List+, +Map+ or +Collection+. - - -=== Collecting Configuration Entries instead of Overriding - -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. - -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: - -[source, properties] ------------------------------------------------ -# from PropertSource 1 -my.list=1,2,3 - -# from PropertSource 2 -my.list=4,5,6 - -# without any additional meta-info these entries would be combined to -my.list=4,5,6 ------------------------------------------------ - -With Tamaya Collections you can now configure the combination policy as follows: - -[source, properties] ------------------------------------------------ -# use one of the default policies: override / collect -_my.list.combination-policy=collect - -# use an custom CombinationPolicy to combine the values -_my.list.combination-policy=com.mycomp.app.MyCombincationPolicy ------------------------------------------------ - -So declaring the +collect+ policy the resulting raw output of the entry looks as follows: - -[source, properties] ------------------------------------------------ -# result when applying the collect policy: -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 - -By default collections are modelled as simple String values, that are 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. - -[source, properties] ------------------------------------------------ -# a list, using the default format -list=1,2,3,4,5,6 - -# a map, using the default format -map=a::b, c::d ------------------------------------------------ - -==== Trimming of entries - -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 -+list1,list2+ and +map1,map2+: - -[source, properties] ------------------------------------------------ -# a list, using the default format -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 ------------------------------------------------ - -Nevertheless 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] ------------------------------------------------ -# a list, with a ' ' value at the end -list3=1, 2, 3, 4, 5, [ ] - -# a map, with a ' ' value for key '0' -map3=1 :: a, 2 :: b, 0::[ ] ------------------------------------------------ - -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: - -[source, properties] ------------------------------------------------ -# a list, with a ' ' value at the end -list3=1__2__3__ 4__ 5__[ ] -_list3.item-separator=__ - -# a map, with a ' ' value for key '0' -map3=1->a, 2->b, 0->[ ] -_map3.map-entry-separator=-> ------------------------------------------------ - -Of course these settings also can be combined: - -[source, properties] ------------------------------------------------ -# a reformatted map -redefined-map=0==none | 1==single | 2==any -_redefined-map.map-entry-separator=== -_redefined-map.item-separator=| ------------------------------------------------ http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_consul.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_consul.adoc b/content/extensions/mod_consul.adoc deleted file mode 100644 index 4407ed3..0000000 --- a/content/extensions/mod_consul.adoc +++ /dev/null @@ -1,59 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: Integration with consul (Hashicorp) - -toc::[] - - -[[Optional]] -== Integration with consul (Extension Module) -=== Overview - -The Tamaya consul integration module provides different artifacts which allows integration of Apachae Tamaya -configuration with consul. Basically the module supports read-only integration (as a +ConsulPropertySource+ as well -as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension module. - - -=== 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-consul</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - - -=== The Extensions Provided - -Consul integration comes basically with 2 artifacts: - -* The +org.apache.tamaya.etcd.ConsulPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name - 'consul', which is automatically registered. -* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster, - by accessing a +MutableConfiguration+ using the URI +config:consul+. - - -=== The ConsulPropertySource - -The +ConsulPropertySource+ is automatically registered and allows the consul servers to be used to be configured. This -enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running -in microservice containers to connect with the according consul cluster: - -* The property source reads the +tamaya.consul.urls+ system and environment property to evaluate possible etcd servers - (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of - configured servers. Without any configuration +http://127.0.0.1:2400+ is used. If no connection to any consul - server can be established a warning will be logged, but deployment will not fail. -* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped to prefixed - context. This can be activated by setting the +-Dtamaya.consul.prefix=<PREFIX>+ system property. E.g. when the prefix is - set to +cluster-config.+ a consul key of +host:known/all+ is mapped to +cluster-config.host:known/all+. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_environment.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_environment.adoc b/content/extensions/mod_environment.adoc deleted file mode 100644 index c0224a1..0000000 --- a/content/extensions/mod_environment.adoc +++ /dev/null @@ -1,42 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: Classloader Isolation Support - -toc::[] - - -[[Remote]] -== Tamaya Environment Model (Extension Module) -=== Overview - -The Tamaya Environment extension adds a simple PropertySourceProvider that evaluates a List of environment context and -combines them in the given order into an (optional) root context within the system's configuration. - - -=== Compatibility - -The module is based on Java 7, so it will not run on Java 7 and beyond. - - -=== Installation - -To benefit from Tamaya Environment Model you only must add the corresponding dependency to your module: - -[source, xml] ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-envionment</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - - -=== How it Works - -tbd - -=== Reusable Base Classes - -tbd http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_etcd.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_etcd.adoc b/content/extensions/mod_etcd.adoc deleted file mode 100644 index 149d843..0000000 --- a/content/extensions/mod_etcd.adoc +++ /dev/null @@ -1,189 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: Integration with etcd (Core OS) - -toc::[] - - -[[Optional]] -== Integration with etcd (Extension Module) -=== Overview - -The Tamaya etcd integration module provides different artifacts which allows integration of Apachae Tamaya -configuration with etcd. Basically the module supports read-only integration (as a +EtcdPropertySource+ as well -as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension module. - - -=== 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-etcd</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - - -=== The Extensions Provided - -ETcd integration comes basically with 2 artifacts: - -* The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint root. - (+org.apache.tamaya.etcd.EtcdAccessor+). The accessor basically provides a simple Java API for communicating - with etcd server. The accessor hereby allows reading of single properties, or whole subtrees. Also the basic non - atomic write methods are implemented. -* The +org.apache.tamaya.etcd.EtcdPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name - 'etcd', which is automatically registered. -* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the etcd cluster, - by accessing a +MutableConfiguration+ using the URI +config:etcd+. - -=== The EtcdAccessor - -The accessor mentioned implements the basic read and write API for communicating with an etcd configuration cluster. -Hereby the accessor also provides etcd specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+ -returned. Hereby the concept of etcd is used where keys starting with an '_' will be hidden from the overall -properties map, being only directly/explicitly accessible: - -[source, java] ------------------------------------------------ -public class EtcdAccessor { - - /** - * Creates a new instance with the basic access url. - * @param server server url, e.g. {@code http://127.0.0.1:4001}. - * @throws MalformedURLException - */ - public EtcdAccessor(String server) throws MalformedURLException; - - /** - * Get the etcd server version. - * @return the etcd server version, never null. - */ - public String getVersion(); - - /** - * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd: - * <pre> - * key=value - * _key.source=[etcd]http://127.0.0.1:4001 - * _key.createdIndex=12 - * _key.modifiedIndex=34 // optional - * _key.ttl=300 // optional - * _key.expiration=... // optional - * </pre> - * @param key the requested key - * @return the mapped result, including meta-entries. - */ - public Map<String,String> get(String key); - - /** - * Creates/updates an entry in etcd without any ttl set. - * The response is as follows: - * <pre> - * key=value - * _key.source=[etcd]http://127.0.0.1:4001 - * _key.createdIndex=12 - * _key.modifiedIndex=34 // optional - * _key.prevNode.createdIndex=12 // optional - * _key.prevNode.modifiedIndex=34 // optional - * </pre> - * @param key the property key, not null - * @param value the value to be set - * @return the result map as described above. - */ - public Map<String,String> set(String key, String value); - - /** - * Creates/updates an entry in etcd. The response is as follows: - * <pre> - * key=value - * _key.source=[etcd]http://127.0.0.1:4001 - * _key.createdIndex=12 - * _key.modifiedIndex=34 // optional - * _key.ttl=300 // optional - * _key.expiry=... // optional - * _key.prevNode.createdIndex=12 // optional - * _key.prevNode.modifiedIndex=34 // optional - * _key.prevNode.ttl=300 // optional - * _key.prevNode.expiration=... // optional - * </pre> - * @param key the property key, not null - * @param value the value to be set - * @param ttlSeconds the ttl in seconds (optional) - * @return the result map as described above. - */ - public Map<String,String> set(String key, String value, Integer ttlSeconds); - - - /** - * Deletes a given key. The response is as follows: - * <pre> - * _key.source=[etcd]http://127.0.0.1:4001 - * _key.createdIndex=12 - * _key.modifiedIndex=34 - * _key.ttl=300 // optional - * _key.expiry=... // optional - * _key.prevNode.createdIndex=12 // optional - * _key.prevNode.modifiedIndex=34 // optional - * _key.prevNode.ttl=300 // optional - * _key.prevNode.expiration=... // optional - * _key.prevNode.value=... // optional - * </pre> - * @param key the key to be deleted. - * @return the response mpas as described above. - */ - public Map<String,String> delete(String key); - - - /** - * Access regular Tamaya properties map as follows: - * <pre> - * key1=myvalue - * _key1.source=[etcd]http://127.0.0.1:4001 - * _key1.createdIndex=12 - * _key1.modifiedIndex=34 // optional - * _key1.ttl=300 // optional - * _key1.expiration=... // optional - * - * key2=myvaluexxx - * _key2.source=[etcd]http://127.0.0.1:4001 - * _key2.createdIndex=12 - * - * key3=val3 - * _key3.source=[etcd]http://127.0.0.1:4001 - * _key3.createdIndex=12 - * _key3.modifiedIndex=2 - * </pre> - */ - public Map<String,String> getProperties(String directory, boolean recursive); - -} ------------------------------------------------ - - -=== The EtcdPropertySource - -The +EtcdPropertySource+ is automatically registered and allows to configure the etcd servers to be used. This -enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running -in microservice containers to connect with the according etcd cluster: - -* The property source reads the +tamaya.etcd.server.urls+ system and environment property to evaluate possible etcd servers - (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of - configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd - server can be established a warning will be logged, but deployment will not fail. -* Additinoally also the - accessor allows to configure the socket/connection timeouts by setting +tamaya.etcd.timeout+ in seconds either as - system or environment property. -* The +EtcdPropertySource+ finally also allows the values read from the etcd cluster to be mapped to prefixed - context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is - set to +cluster-config.+ a etcd key of +host:known/all+ is mapped to +cluster-config.host:known/all+. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_events.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_events.adoc b/content/extensions/mod_events.adoc deleted file mode 100644 index c0a3809..0000000 --- a/content/extensions/mod_events.adoc +++ /dev/null @@ -1,278 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: Events - -toc::[] - - -[[Core]] -== Tamaya Events (Extension Module) -=== Overview - -Tamaya Events is an extension module. Refer to the link:modules.html[extensions documentation] for further details -about modules. - -Tamaya Events provides an abstraction for events like change events, when configuration has been changed. - -=== Compatibility - -The module is based on Java 7, so it can be used with Java 7 and beyond. - -=== Installation - -To benefit from configuration event support you only must add the corresponding dependency to your module: - -[source, xml] ------------------------------------------------ -<dependency> - <groupId>org.apache.tamaya.ext</groupId> - <artifactId>tamaya-events</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - -=== Core Architecture - -The core of the module are the +ConfigEventListener+ interface and the +ConfigEvent+ class, which defines an abstraction -for event handling and observation: - -[source,java] -.ConfigEvent --------------------------------------------- -public final interface ConfigEvent<T> { - - Class<T> getResourceType(); - T getResource(); - String getVersion(); - long getTimestamp(); -} - -// @FunctionalInterface -public interface ConfigEventListener { - - void onConfigEvent(ConfigEvent<?> event); - -} --------------------------------------------- - -This mechanism can now be used to propagate configuration changes to all interested stakeholders. Hereby the payload -can be basically arbitrary as long as it implements the +ConfigEvent+ interface. The next sections -give more details on the the provided event types and their usage. - - -=== Modelling Configuration Changes - -This module provides a serializable and thread-safe abstraction modlling a configuration change. A change hereby may -be - -* additional configuration entries -* removed configuration entries -* changes on entries - - -The most important event modelled is the +ConfigurationChange+ class, which implements the event sent for a changed -+Configuration+: - -[source,java] -------------------------------------------------------- -public final class ConfigurationChange implements ConfigEvent<Configuration>, Serializable{ - - public static ConfigurationChange emptyChangeSet(Configuration configuration); - - @Override - public Configuration getResource(); - @Override - public Class<Configuration> getResourceType(); - @Override - public String getVersion(); - @Override - public long getTimestamp(); - - // Event specific methods - - public Collection<PropertyChangeEvent> getChanges(); - public int getRemovedSize(); - public int getAddedSize(); - public int getUpdatedSize(); - - public boolean isKeyAffected(String key); - public boolean isRemoved(String key); - public boolean isAdded(String key); - public boolean isUpdated(String key); - public boolean containsKey(String key); - public boolean isEmpty(); -} - -------------------------------------------------------- - -New instances of this class hereby can be created using a fluent builder: - -[source,java] -------------------------------------------------------- -Configuration config = ...; -ConfigurationChange change = ConfigurationChangeBuilder.of(config) - .addChange("MyKey", "newValue") - .removeKeys("myRemovedKey").build(); -------------------------------------------------------- - -Also it is possible to directly compare 2 instances of configurations to create +ConfigurationChange+ that -reflect the differences between the two configurations: - -[source,java] -Comparing 2 configurations -------------------------------------------------------- -Configuration config = ...; -Configuration changedConfig = ...; -ConfigurationChange change = ConfigurationChangeBuilder.of(config) - .addChanges(changedConfig).build(); -------------------------------------------------------- - -So a +ConfigurationChange+ allows you to evaluate the changes on a configuration. This allows you to listen to changes -and react in your client code as useful, once you encounter changes that are relevant to you, e.g. by reconfiguring -your component. For listening to configuration changes you must implement the -+ConfigEventListener+ functional interface: - -[source,java] -.Implementing a ConfigChangeListener -------------------------------------------------------- -public final class MyConfigChangeListener implements ConfigChangeListener<ConfigurationChange>{ - - private Configuration config = ConfigurationProvider.getConfiguration(); - - public void onConfigEvent(ConfigEvent<?> event){ - if(event.getResourceTspe()==Configuration.class){ - if(event.getConfiguration()==config){ - // do something - } - } - } - -} -------------------------------------------------------- - -You can *register* your implementation in 2 ways: - -. Manually by calling +ConfigEventManager.addListener(new MyConfigChangeListener())+ -. Automatically by registering your listener using the +ServiceLoader+ under - +META-INF/services/org.apache.tamaya.events.ConfigEventListener+ - - -=== Modelling PropertySource Changes - -Beside that a whole configuration changes, also +PropertySource+ instances can change, e.g. by a configuration file -edited on the fly. This is similarly to a +ConfigurationChange+ reflected by the classes +PropertySourceChange, -PropertySourceChangeBuilder+. - - -=== The ConfigEventManager Singleton - -Main entry point of the events module is the +ConfigEventManager+ singleton class, which provides static accessor -methods to the extension's functionality: - -* Adding/removing of +ConfigChangeListener+ instances, either globally or per event type. -* Firing configuration events synchronously or asyncronously (mostly called by framework code). -* Configuring the monitor that periodically checks for changes on the global +Configuration+ provided - by +ConfigurationProvider.getConfiguration()+. - -[source,java] -------------------------------------------------------- -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> - Collection<? extends ConfigEventListener> getListeners(); - public static <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 static void enableChangeMonitoring(boolean enable); - public static boolean isChangeMonitoring(); - public long getChangeMonitoringPeriod(); - public void setChangeMonitoringPeriod(long millis); - -} -------------------------------------------------------- - - -==== Monitoring of configuration changes - -The +ConfigEventManager+ also supports active monitoring of the current configuration to trigger corresponding change -events to listeners registered. This feature is deactivated by default, but can be enabled by calling -+ConfigEventManager.enableChangeMonitoring(true);+. This feature avoids regularly polling your local +Configuration+ for -any kind of changes. If a change has been encountered Tamaya identifies it and triggers corresponding -+ConfigurationChange+ events automatically. - - -=== Freezing Configurations and PropertySources - -+Configuration+ instances as well as +PropertySources+ are explicitly not required to be serializable. To enable easy -serialization of these types a +Configuration+'s *current state can be frozen* (e.g. for later comparison with a newly -loaded version). Freezing hereby means - -* all key/values are read-out by calling the +getProperties()+ method. -* a meta data entry is added of the form +_frozenAt=223273777652325677+, whichdefines the UTC timestamp in - milliseconds when this instance was frozen. -* if not already defined an +_id+ property will be added to the +Configuration+ containing the - identifier of the configuration. - -In code freezing is a no-brainer: - -[source,java] -.Freezing the current Configuration --------------------------------------------------- -Configuration config = ConfigurationProvider.getConfiguration(); -Configuration frozenConfig = FrozenConfiguration.of(config); --------------------------------------------------- - -... and similarly for a +PropertySource+: - -[source,java] -.Freezing the current Configuration --------------------------------------------------- -PropertySource propertySource = ...; -PropertySource frozenSource = FrozenPropertySource.of(propertySource); --------------------------------------------------- - - - -=== SPIs - -This component also defines an additional SPI, which allows to adapt the implementation of the main +ConfigEventManager+ -singleton. This enables, for example, using external eventing systems, such as CDI, instead of the default provided -simple SE based implementation. As normal, implementation must be registered using the current +ServiceContext+ -active, by default using the Java +ServiceLoader+ mechanism. - -[source,java] -.SPI: ConfigEventSpi --------------------------------------------------- -public interface ConfigEventManagerSpi { - - <T> void addListener(ConfigEventListener l); - <T extends ConfigEvent> void addListener(ConfigEventListener l, Class<T> eventType); - void removeListener(ConfigEventListener l); - <T extends ConfigEvent> void removeListener(ConfigEventListener l, Class<T> eventType); - Collection<? extends ConfigEventListener> getListeners(); - Collection<? extends ConfigEventListener> getListeners(Class<? extends ConfigEvent> eventType); - - void fireEvent(ConfigEvent<?> event); - void fireEventAsynch(ConfigEvent<?> event); - - long getChangeMonitoringPeriod(); - void setChangeMonitoringPeriod(long millis); - boolean isChangeMonitorActive(); - void enableChangeMonitor(boolean enable); -} --------------------------------------------------- - - -Summarizing with the events module you can easily observe configuration changes, record the -state of any configuration and compare configuration states to create and publish related -change events. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/extensions/mod_filter.adoc ---------------------------------------------------------------------- diff --git a/content/extensions/mod_filter.adoc b/content/extensions/mod_filter.adoc deleted file mode 100644 index 670faa0..0000000 --- a/content/extensions/mod_filter.adoc +++ /dev/null @@ -1,119 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya -- Extension: User Filtering - -toc::[] - - -[[Optional]] -== User Filtering (Extension Module) -=== Overview - -The Tamaya filter module provides a simple singleton accessor that allows to explicitly add +PropertyFilter+ instances -active on the current thread only. This can be very useful in many scenarios. Additionally this module adds -standard filters that hide metadata entries when the full configuration map is accessed. When keys are accessed -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. - - -=== 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-filter</artifactId> - <version>{tamaya_version}</version> -</dependency> ------------------------------------------------ - - -=== The Extensions Provided - -Tamaya Filter comes basically with 3 artifacts: - -* The +org.apache.tamaya.filter.ConfigurationFilter+ 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 - an underscore ('_'), when a full property map is accessed. - - -=== The ConfigurationFilter - -The accessor mentioned implements the API for for adding +PropertyFilters+ to the current thread (as thread local): - -[source, java] ------------------------------------------------ -public final class ConfigurationFilter implements PropertyFilter{ - - ... - - /** - * Seactivates metadata filtering also on global map access for this thread. - * @see #clearFilters() - * @param active true,to enable metadata filtering (default). - */ - public static void setFilterMetadata(boolean active); - - /** - * Access the filtering configuration that is used for filtering single property values accessed. - * @return the filtering config, never null. - */ - public static FilterContext getSingleFilterContext(); - - /** - * Access the filtering configuration that is used for filtering configuration properties accessed as full - * map. - * @return the filtering config, never null. - */ - public static FilterContext getMapFilters(); - - /** - * Removes all programmable filters active on the current thread. - */ - public static void clearFilters(); - - ... - -} ------------------------------------------------ - -For using regular expression when filtering configuration keys a corresponding implementation of a +PropertyFilter+ -is part of this module, So you can add a customized filter as follows: - -[source, java] ------------------------------------------------ -try { - ConfigurationFilter.getMapFilters().addFilter(new myFilter()); - - // do your code with filtering active -} -finally { - // cleanup - ConfigurationFilter.clearFilters(); -} ------------------------------------------------ - -The +FilterContext+ 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 void addIncludes(PropertyFilter filter); - public void addExcludes(int pos, PropertyFilter filter); - public PropertyFilter removeFilter(int pos); - public void clearFilters(); - public void setIncludes(PropertyFilter... filters); - public void setExcludes(Collection<PropertyFilter> filters); - public List<PropertyFilter> getFilters(); - -} ------------------------------------------------
