TAMAYA-29: Removed stage. TAMAYA-19: Simplified environment model. -> Updated docs.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/cd513bf3 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/cd513bf3 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/cd513bf3 Branch: refs/heads/master Commit: cd513bf36b7da240fef80b5660ff3399693b8954 Parents: 0b3b963 Author: anatole <anat...@apache.org> Authored: Wed Dec 17 00:26:20 2014 +0100 Committer: anatole <anat...@apache.org> Committed: Wed Dec 17 00:26:20 2014 +0100 ---------------------------------------------------------------------- docs/Design.adoc | 117 --- docs/design/0_UseCases.adoc | 319 ------- docs/design/1_Requirements.adoc | 50 -- docs/design/2_CoreConcepts.adoc | 843 ------------------ docs/design/3_Extensions.adoc | 841 ------------------ docs/design/4_ImplementationCore.adoc | 47 - docs/pom.xml | 2 +- .../main/asciidoc/PossibleContributions.adoc | 388 +++++++++ docs/src/main/asciidoc/design/0_UseCases.adoc | 319 +++++++ .../main/asciidoc/design/1_Requirements.adoc | 50 ++ .../main/asciidoc/design/2_CoreConcepts.adoc | 849 +++++++++++++++++++ docs/src/main/asciidoc/design/3_Extensions.adoc | 841 ++++++++++++++++++ .../asciidoc/design/4_ImplementationCore.adoc | 47 + docs/src/main/asciidoc/design/Design.adoc | 117 +++ docs/tasks.adoc | 388 --------- 15 files changed, 2612 insertions(+), 2606 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/cd513bf3/docs/Design.adoc ---------------------------------------------------------------------- diff --git a/docs/Design.adoc b/docs/Design.adoc deleted file mode 100644 index 403b4ff..0000000 --- a/docs/Design.adoc +++ /dev/null @@ -1,117 +0,0 @@ -Apache Tamaya -- Design Documentation -===================================== -:name: Tamaya -:rootpackage: org.apache.tamaya -:title: Apache Tamaya -:revnumber: 0.1-SNAPSHOT -:revremark: Incubator -:revdate: November 2014 -:longversion: {revnumber} ({revremark}) {revdate} -:authorinitials: ATR -:author: Anatole Tresch, Anatole Tresch -:email: <atsti...@gmail.com> -:source-highlighter: coderay -:website: http://tamaya.incubator.apache.org/ -:iconsdir: {imagesdir}/icons -:toc: -:toc-placement: manual -:icons: -:encoding: UTF-8 -:numbered: - -''' - -<<< - --> add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg[] - -toc::[] - -<<< -:numbered!: ------------------------------------------------------------ -Licensed to the Apache Software Foundation (ASF) under one -or more contributor license agreements. See the NOTICE file -distributed with this work for additional information -regarding copyright ownership. The ASF licenses this file -to you under the Apache License, Version 2.0 (the -"License"); you may not use this file except in compliance -with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, -software distributed under the License is distributed on an -"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -KIND, either express or implied. See the License for the -specific language governing permissions and limitations -under the License. ------------------------------------------------------------ - -:numbered: - -<<< - -== Introduction -This document describes the {name} API for Configuration. The technical objective is to provide a -unified configuration model in Java, targeting Java ME, SE as well as the EE platform. -The API will provide support for key/value based application configuration. It will provide -as well higher level APIs that are based on the low level ke</value pairs. Finally it will -provide extension points for adding additional features and additional modules for extension -or adaption. - -=== Working Group -This work is being conducted as part of a community lead joint effort under the Apache Software Foundation. This -specification is the result of the collaborative work of the members of the {name} Users Group and the community at -large. Currently the project is lead by Anatole Tresch (atsticks at gmail.dot com). - -=== Goals -Configuration is a key feature in all kind of programming languages. Basically configuration is the parametrization of -well defined aspects of a software product without having to recompile/rebuild the code. - -==== Targets -{name} targets to support all general configuration aspects, e.g. - -* spplication configuration -** plugins -** modules -** components -* Configuration of Java EE related aspects for Java enterprise application portability and dynamic provisioning, such as -** Configuration of CDI (interceptors, decorators and alternatives) -** Configuration of Bean Validation, JSF, web applications etc. -* Configuration of instances within Java SE, e.g. by passing instances to a method that injects configured values, or by providing - accessors to evaluate current configuration vlues. This can be used explicitly or transparently by client code. - -Additionally the solution should support - -* multiple configuration locations, including remote locations -* multiple configuration formats, including custom formats -* multiple configuration loading mechanisms, including custom mechanisms. By default reading the classpath, files und URIs are supported by default. -* type conversion -* configuration of collections - - -=== Required Java version -The API is based on Java SE 8.0 language features. - -=== How this document is organized -There are five main section in this document: - -* Use cases. -* Requirements. -* Specification. -* Implementation Recommendations. -* An appendix. - -<<< -include::design/0_UseCases.adoc[] - -<<< -include::design/1_Requirements.adoc[] - -<<< -include::design/2_CoreConcepts.adoc[] - -:numbered!: -== APPENDIX - http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/cd513bf3/docs/design/0_UseCases.adoc ---------------------------------------------------------------------- diff --git a/docs/design/0_UseCases.adoc b/docs/design/0_UseCases.adoc deleted file mode 100644 index 8ec833e..0000000 --- a/docs/design/0_UseCases.adoc +++ /dev/null @@ -1,319 +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. - -<<< -[[UseCases]] -== Use Cases - -This section describes some, but not all, of the use cases that should be covered by Tamaya. - - -[[UCSimpleAccess]] -=== Simple Property Access (UC 1) - -Tamaya should provide a simple Java API for accessing configuration. Hereby - -* Configuration is organized as key/value pairs. This basically can be modeled as +Map<String,String>+ -* Configuration should be as simple as possible. A +Map<String,String>+ instance has methods that may not - be used in many use cases and/or are not easy to implement. Currently the following functionality - must be supported: - ** access a value by key (+get+) - ** check if a value is present (+containsKey+) - ** get a set of all defined keys (+keySet+) - ** a property provider must be convertable to a +Map+, by calling +toMap()+ - ** a property provider must get access to its meta information. -* The API must never return null. -* The API should 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. -* Properties can be stored in properties, xml-properties or ini-format. -* Properties can also be provided as properties, or as a Map<String,String> - - -[[UCAutoConfig]] -=== Automatic Configuration - -* Tamaya should provide a feature for automatic configuration, where properties can be annotated. -* Hereby the lifecycle of the instances configured should not be managed by Tamaya. -* String as well as other types should be supported. -* It should be possible to define default values to be used, if no valid value is present. -* It should be possible to define dynamic expressions, at least for default values. -* The values configured should be reinjected, if the underlying configuration changes. -* Reinjection should be controllable by an injection policy. -* It should be possible to evaluate multiple keys, e.g. current keys, and as a backup deprecated keys - from former application releases. -* The type conversion of the properties injected should be configurable. -* The value evaluated for a property (before type conversion) may be adaptable as well. -* It should be possible to observe configuration changes. - -The most simplest way is using injection, e.g. a POJO can be written as follows: - -[source, java] -.Configured POJO Example ----------------------------------------------------- -public class MyPojo { - @ConfigProperty("myCurrency") - @DefaultValue("CHF") - private String currency; - - @ConfigProperty("myCurrencyRate") - private Long currencyRate; -} ----------------------------------------------------- - -The instance then can be passed for being configured: - -[source, java] -.Configuring a POJO ----------------------------------------------------- -MyPojo instance = new MyPojo(); -Configuration.configure(instance); ----------------------------------------------------- - -[[UCTemplates]] -=== Configuration Templates - -For type safe configuration clients should be able to define an interface that is implemented by the -configuration system: - -* clients define an interface and annotate it as required -* 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 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. - -A template hereby is modelled by annotating an interface with the same annotations as for -configured classes: - -[source, java] -.Type Safe Configuration Template Example ----------------------------------------------------- -public interface MyConfig { - @ConfiguredProperty("myCurrency") - @DefaultValue("CHF") - String getCurrency(); - - @ConfiguredProperty("myCurrencyRate") - Long getCurrencyRate(); - -} ----------------------------------------------------- - -The configuration system will then provide the interface as follows: - -[source, java] -.Accessing a type safe Configuration Template ----------------------------------------------------- -MyConfig config = Configuration.of(MyConfig.class); ----------------------------------------------------- - -Finally a +Configuration+ itself can be accessed as template as well, which -provides full access to all features: - -[source, java] -.Accessing a Configuration ----------------------------------------------------- -Configuration config = Configuration.of(Configuration.class); ----------------------------------------------------- - - -[[UCSimpleConfiguration]] -=== Simple Property Based Configuration - -In this most simple usage scenario an application is configured by some property files contained in the -Java archive. - -* It provides default property files in the formats defined by the JDK within its application archive. -* It allows to override settings by system properties. -* It is able to consider command line arguments as well. - - -[[UCAdvancedPropertyBasedConfiguration]] -=== Advanced Property Based Configuration - -Enhancing the previous scenario, we might as well consider the current environment. Saying that our overriding mechanisms -must be improved, since - -* some environment settings should not be overridable -* some defaults should be overridden by environment or system properties, whereas others may not -* Additionally the user may have an option, where he is allowed to define an external configuration file that should be used to configure - the application. This is especially useful for applications with lots of command line options (under windows even command - execution may fail die to exceeding command length). -* Finally application developers may have their own formats in place, so the system should be able to support these formats. - - -[[UCModularizedConfiguration]] -=== Modularized Configuration - -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 want to have their own "module configuration". -* Some modules require a certain subset of keys to be read at once into a Map. -* Products contain multiple modules, which per product are configured separately. - - -[[UCTypeSupport]] -=== Extended Type Support - -Application configuration must also support non String types such as primitives, wrapper types, math types -and date/time values. Basically each type that can be created from a String in more standardized way should -supported. This should be even possible for types not known at build time of possible. Type conversion hereby -should be flexible. - -[[UCDynamicProvisioning]] -=== Dynamic Provisioning - -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. - -Consequently: - --> Ensure Configuration can be transferred over the network easily. - --> Whereas many people will no think serializability is the solution, it would be much more useful to define - a text based format for serialization, e.g. in +XML+ or +JSON+. - --> Similarly a management API should be defined, which allows to inspect the configuration in place, e.g. using - JMX or REST services. - -[[UCJavaEE]] -=== Java EE - -Considering Java EE different aspects should be considered: - -* Java EE is a complex multi-layered architecture with different levels of runtime contexts: -** application server boot level (system classloader), -** (optional) deployment/undeployment of ears (ear classloader), -** (optional) deployment/undeployment of web applications (war classloader), -** different runtime setups, e.g. EJB calls, MDB execution, Servlet Requests, scheduled and timed executions. -* Configuring administrative resources (e.g. datasources, users, security etc) is typically vendor specific. -* The environment is inherently multi-threaded. - -Given that a couple of additional requirements araise: - --> 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. - -[[UCMultiTenancy]] -=== Scenario MultiTenancy -In multi tenancy setups a hierarchical/graph model of contexts for configurations is required. For example there might -be some kind of layering as follows: - -* Layer 0: Low level system configuration -* Layer 1: Domain configuration -* Layer 2: Default App configuration -* Layer 3: Tenant specific configuration -* Layer 4: User specific configuration - -Configurations made in the tenant or user layer override the default app configuration etc. - --> 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. - -[[UCJavaAPI]] -=== Accessing Configuration - -So far we described much how configuration must be organized and managed, but we got not concrete, how it is accessed. -Basically there are two basic scenarios to be distinguished, which mainly depend on the way how the lifecycle of a component -to be configured is managed: - -* If the lifecycle is managed manually by the developer, the configuration system -** can inject configuration values, when explicitly called to to so -** can provide an accessor for configuration. -* If the lifecycle is managed by some container such as a DI container, the configuration - system should leverage the functionality of the container, where possible. - - - - -[[UCTesting]] -=== Testing -When testing a Java solution, it must be possible to easily control the configuration provided, so isolated -component tests can be written effectively. Also it should be possible to control/isolate the configuration level for -each test case. - --> isolation of configuration services is required - --> API for controlling the configuration provided, required for according implementations in the testing frameworks. - -[[UCStaging]] -=== Staging -Different companies go through different staging levels during the development of software components. Currently only -rarely the EE frameworks support staging aspects, nevertheless no broader, well modelled staging concept is defined. -Different companies also have different staging or sub-staging levels in place, which also must be reflected. -Especially with sub-stages inheritance of stage related configuration is common sense and should be supported. - --> Main stages available and to be supported must be defined. - --> Enable additional stages to be added, so also custom stages can be supported. - - -[[UCCotsIntegration]] -=== Custom of the Shelf (COTS) Integration -When buying software from an external software company it is often very cumbersome to integrate, adapt and customize -third party software to the internal operational requirements. Especially, when software is delivered as ear modules -portability is often very difficult and time consuming. Configuration should enable COTS providers to define a -customization contract, which also can be part of the COTS software interface and integration specifications. This -would allow operations to better control and configure third party solutions as possible, whereas in the evaluation -phase the integration and configuration options can explicitly be defined. - --> It must be possible to document configuration aspects supported. - --> Configuration must be overridable from external sources (the operations which must operate the COTS solution). - http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/cd513bf3/docs/design/1_Requirements.adoc ---------------------------------------------------------------------- diff --git a/docs/design/1_Requirements.adoc b/docs/design/1_Requirements.adoc deleted file mode 100644 index 6367ed3..0000000 --- a/docs/design/1_Requirements.adoc +++ /dev/null @@ -1,50 +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. - -<<< -[[Requirements]] -== Requirements -=== Core Configuration Requirements -Based on the scope and use cases described above the following core requirements can be identified: - -* Configuration is modelled as String based key/value pairs. -* Configuration can be combined using the GoF composite pattern. Hereby different composition policies can be applied, such as - ** override: subsequent entries override existing ones. - ** substraction: keys present in the second configuration will be removed. - ** union-resolve: key/values were added, in case of conflicts a +ConfigException+ must be thrown. - ** union-ignore: similar to union, whereas duplicates are ignored (leaving the initial value loaded). - ** intersection: - -[[RequirementsServer]] -=== Server Configuration Requirements -shskjdhskhds sdkj ksjdks skjdskjd: - -. Req1 -. Req2 - -[[RequirementsExtensions]] -=== Extensions Requirements -shskjdhskhds sdkj ksjdks skjdskjd: - -. Req1 -. Req2 - -[[RequirementsNonFunctional]] -=== Non Functional Requirements -. Req1 -. Req2 - http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/cd513bf3/docs/design/2_CoreConcepts.adoc ---------------------------------------------------------------------- diff --git a/docs/design/2_CoreConcepts.adoc b/docs/design/2_CoreConcepts.adoc deleted file mode 100644 index 41c2311..0000000 --- a/docs/design/2_CoreConcepts.adoc +++ /dev/null @@ -1,843 +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. -<<< -[[CoreConcepts]] -== {name} Core Concepts -Though {name} 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: - -The API contains the following core concepts/artifacts: - -* Literal Key/Value Pairs -* _PropertySource:_ is the the SPI for a source that provides configuration data. A +PropertySource+ - hereby defines - ** a minimalistic SPI to be implemented by the config data source - ** provides data key/value pairs in raw format as String key/values only - ** providers should not have any dependencies other than to the datasource - ** providers may read context dependent data, but basically providers themselves are not contextual. - Context management should be done by the ConfigurationProvider implementation that also is responsible - for combining a set of property providers to a Configuration. - _Configuration_ is the API that users of Tamaya will see, when they access configuration in raw format. Hereby +Configuration+ - ** adds type support for non String types - ** provides functional extension points (+with,query+) - ** allows registering/deregistering of change listeners - ** is the entry point for evaluating the current +Configuration+ - ** each +PropertySource+ can be easily converted into a +Configuration+ - ** allows configuration entries to be injected - ** to access configuration _templates_ (annotated interfaces). - ** Configuration may support mutability by allowing instances of +ConfigChangeSet+ to be passed. -* _PropertySourceBuilder_ allows to aggregate different property sources. Hereby property sources are - seen as sets, which can be combined to new sources using set styled operations (aggregation, intersection, subtraction). - This allows to model and create composite sources, to build up more complex configuration models - step by step. -* _MetaInfo_ is provided by each +Configuration, PropertySource+ and describes the configuration/provider and its entries. -* _Environment_ is the base model for modelling the environment and the accessor for getting the current +Environment+ instance. -* _Annotations_ a set of annotations allows to configure configuration injection on classes or interface (aka config templates). - -The SPI contains the following core concepts/artifacts: - -* _ServiceContext_ is the delegate singleton that is used by the framework to resolve components. The effective component - loading can be accessed by implementing and registering an instance of +ServiceContextProvider+ using +java.util.ServiceLoader+. -* All the singleton used explicitly (+PropertyAdapters,Configuration+ are backed up corresponding API interfaces. - To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded - by the current +ServiceContext+ setup (by default ServiceLoader based). -* Also the singleton used implicitly by +Configuration, Environment+ are backed up corresponding SPI interfaces. - To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded - by the current +ServiceContext+ setup (by default ServiceLoader based). - -This is also reflected in the main parts of the API, which is quite small: - -* +org.apache.tamaya+ contains the main abstractions +Configuration, ConfigQuery, PropertyAdapter, Stage, - Environment, PropertySource, MetaInfo+ -* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +ServiceContext+ mechanism. -+ +org.apache.tamaya.annot+ contains the annotations defined. - -In the implementation are there are additional projects: - -* +org.apache.tamaya.core+ contains the core implementation of the API. Deploying it together with the API results in a - flexible framework that can be easily used for configuration of different complexity. But out of the box this framework - will not do much more than exposing system and environment properties, its power comes when an additional meta-model - is defined and deployed. Hereby you can write your own, or use on e of the provided ones (see later). -* the core part is extended by multiple additional modules - ** CDI integration - ** Default configuration meta-models and providers for the most common usage scenarios - *** standalone applications - *** Java EE - *** ... - -These parts are explained in the following sections. It is recommended that user's of the API read through this part. -All subsequent parts are building upon this concepts and may be more difficult to understand without having read -this section. - - -[[APIKeyValues]] -=== Key/Value Pairs - -Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple -and similarly most commonly used are simple literal key/value pairs. So the core building block of {name} are key/value pairs. -You can think of a common +.properties+ file, e.g. - -[source,properties] -.A simple properties file --------------------------------------------- -a.b.c=cVal -a.b.c.1=cVal1 -a.b.c.2=cVal2 -a=aVal -a.b=abVal -a.b2=abVal --------------------------------------------- - -Now you can use +java.util.Properties+ to read this file and access the corresponding properties, e.g. - -[source,properties] -.Accessing some properties --------------------------------------------- -Properties props = new Properties(); -props.readProperties(...); -String val = props.getProperty("a.b.c"); -val = props.getProperty("a.b.c.1"); -... --------------------------------------------- - -This looks familiar to most of you. Nevertheless when looking closer to the above key/value pairs, -there are more concepts in place: looking at the keys +a.b.c+, +a.b.c.1+, +a.b.c.2+, +a+, +a.b+ we -see that the key names build up a flattened tree structure. So we can define the following: - -Given a key +p1.p2.p3.k=value+: - -* +p1.p2.p3.k+ is called the _qualified key_ -* +p1.p2.p3+ is the key's _area_ -* the child areas +p1.p2", "p1+ are called _areas_ as well -* +k+ is the _(unqualified) key_ - -Given that you can perform some very useful actions: - -* you can filter the keys with an area. E.g. in the example before you can query for all keys within the area +a.b.c+ - and map them to new properties set as follows: - -[source,properties] -.Accessing an area --------------------------------------------- -1=cVal1 -2=cVal2 --------------------------------------------- - -Similarly accessing the area +a+ results in the following properties: - -[source,properties] -.Accessing the area +a+ --------------------------------------------- -b=abVal -b2=abVal --------------------------------------------- - -Additionally you can access all values of an area recursively, so accessing +a+ recursively results in -the following properties: - -[source,properties] -.Accessing area +a+ recursively --------------------------------------------- -b.c=cVal -b.c.1=cVal1 -b.c.2=cVal2 -b=abVal -b2=abVal --------------------------------------------- - -Why this is useful? Well there are different use cases: - -* you can segregate your configuration properties, e.g. a module can access its module configuration by - querying all properties under the area +config.modules.myModule+ (or whatever would be appropriate). -* you can use this mechanism to configure maps (or more generally: collections). -* you can easily filter parts of configuration -* ...and more. - -==== Why Using Strings Only - -Using Strings as base representation of configuration comes with several huge advantages: - -* Strings are simple to understand -* Strings are human readable and therefore easy to prove for correctness -* Strings can easily be used within different language, different VMs, files or network communications. -* Strings can easily be compared and manipulated -* Strings can easily be searched, indexed and cached -* It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in - production as well in testing. -* and more - -On the other side there are also disadvantages: - -* Strings are inherently not type safe, they do not provide validation out of the box for special types, such as -numbers, - dates etc. -* Often you want not to work with Strings, but with according types. -* Strings are not hierarchical, so mapping hierarchical structures requires some extra efforts. - -Nevertheless most of these advantages can be mitigated easily, hereby still keeping all the benefits from above: - -* Adding type safe converters on top of String allow to add any type easily, that can be directly mapped out of Strings. - This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more. -* Even more complex mappings can be easily realized, by using String not as a direct representation of configuration, - but a reference that defines where the more complex configuration artifact is available. This mechanism is similarly - easy to understand as parsing Strings to numbers, but is powerful enough to provide e.g. all kind of deployment - descriptors in Java EE. -* Hierarchical and collection types can be mapped in different ways: -** The keys of configuration can have additional syntax/semantics. E.g. when adding dor-separating path semantics -*** trees/maps can also simply be mapped. - -[APIPropertySources] -=== PropertySource -==== Basic Model - -We have seen that constrain configuration aspects to simple literal key/value pairs provides us with an easy to -understand, generic, flexible, yet expendable mechanism. Looking at the Java language features a +java.util.Map<String, -String>+ and +java.util.Properties+ basically model these quite well out of the box. -So it would make sense to build configuration on top of the JDK's +Map+ interface. This creates immediately additional -benefits: - -* we inherit full Lambda and collection support -* Maps are widely known and well understood - -Nevertheless there are some severe drawbacks: - -* Configuration also requires meta-data, such as -** the origin of a certain configuration entry and how it was derived from other values -** the sensitivity of some data -** the provider that have read the data -** the time, when the data was read -** the timestamp, when some data may be outdated -** ... - -Basically the same is also the not related to some single configuration key, but also to a whole map. -The +PropertySource+ interface models exact these aspects and looks as illustrated below: - -[source,java] -.Interface PropertySource --------------------------------------------- -public interface PropertySource{ - - Optional<String> get(String key); - boolean containsKey(String key); - Map<String, String> toMap(); - MetaInfo getMetaInfo(); - - default Set<String> keySet(); - default ConfigChangeSet load(); - default boolean isMutable(); - default void apply(ConfigChangeSet change); -} --------------------------------------------- - -Hereby - -* +getMetaInfo()+ return the meta information for the property provider, as well as for individual property key/value pairs. -* +get+ look similar to the methods on +Map+, though +get+ uses the +Optional+ type introduced - with Java 8. This avoids returning +null+ or throwing exceptions in case no such entry is available and also - reduced the API's footprint, since default values can be easily implemented by calling +Optional.orElse+. -* +containsKey, keySet+ are as well methods similar to +java.util.Map+ though implementations may only returns - limited data, especially when the underlying map storage does not support iteration. -* +isMutable()+ allows to easy check, if a property provider is mutable, which is more elegant than catching - +NonSupportedOperation+ exception thrown on the according methods of +Map+. -* +load()+ finally allows to (re)load a property map. It depends on the implementing source, if this operation - has any effect. If the map changes an according +ConfigChange+ must be returned, describing the - changes applied. -* +toMap+ allows to extract thing to a +Map+. Similar to +containsKey, keySet+ implementations may only return - a limited data map, especially when the underlying map storage does not support iteration. - -This simple model will be used within the spi, where configuration can be injected/provided from external resources. -But we have seen, that we have to consider additional aspects, such as extendability and type safety. Therefore we -extend +PropertySource+ and hereby also apply the 'composite pattern', which results in the following key abstraction. - -==== Meta Information - -Each instance also provides an instance of +MetaInfo+, which provides meta information for the providers and its properties: - -[source,java] -.Accessing Meta Information --------------------------------------------- -PropertySource prov = ...; -MetaInfo metaInfo = prov.getMetaInfo(); -Set<String> keys = metaInfo.keySet(); // returns the attribute keys, for which meta-information is accessible. -String metaData = metaInfo.get("a.b.c.value"); // access meta information -String itemName = metaInfo.getName(); // access meta information for the provider --------------------------------------------- - -As we have seen above there is as well a +MetaInfoBuilder+, which must be used to create instances of -+MetaInfo+. - -==== Mutability - -Property sources optionally may be mutable. This can be checked by calling +boolean isMutable()+. If a source -is mutable a +ConfigChangeSet+ can be passed. This change set can then be applied by the source. On creation -of the +ConfigChangeSetBuilder+ a source can pass version information, so _optimistic locking_ can be implemented -easily: - -[source,java] -.Creating and applying a +ConfigChangeSet+ to a PropertySource --------------------------------------------- -PropertySource source = ...; -ConfigChangeSet changeSet = ConfigChangeSetBuilder.of(provider) // creating a default version - .remove("key1ToBeRemoved", +key2ToBeRemoved") - .put("key2", "key2Value") - .put("key3", 12345) - .put("key4", 123.45) - .build(); -source.apply(changeSet); --------------------------------------------- - -[[API PropertySourceBuilder]] -==== Building Property Sources - -Looking at the structures of configuration system used by large companies we typically encounter some kind of configuration -hierarchies that are combined in arbitrary ways. Users of the systems are typically not aware of the complexities in this -area, since they simply know the possible locations, formats and the overriding policies. Framework providers on the other -side must face the complexities and it would be very useful if Tamaya can support here by providing prebuilt functionality -that helps implementing these aspects. All this leads to the feature set of combining property sources. Hereby the following -strategies are useful: - -* aggregating providers, hereby later providers added - ** override any existing entries from earlier providers - ** combine conflicting entries from earlier providers, e.g. into a comma-separated structure. - ** may throw a ConfigExcepotion ig entries are conflicting - ** may only add entries not yet defined by former providers, preventing entries that are already present to be overwritte - ** any custom aggregation strategy, which may be a mix of above -* intersecting providers -* subtracting providers -* filtering providers - -These common functionality is provided by the +PropertySources+ singleton. Additionally to the base strategies above a +MetaInfo+ -instance can be passed optionally as well to define the meta information for the newly created provider instances. -Let's assume we have two property providers with the following data: - -[source,properties] -.Provider 1 --------------------------------------------- -a=a -b=b -c=c -g=g -h=h -i=i --------------------------------------------- - -[source,properties] -.Provider 2 --------------------------------------------- -a=A -b=B -c=C -d=D -e=E -f=F --------------------------------------------- - -Looking in detail you see that the entries +a,b,c+ are present in both providers, whereas +d,e,f+ are only present in provider 1, -and +g,h,i+ only in provider 2. - -[source,java] -.Example Combining PropertySources --------------------------------------------- -PropertySource provider1 = ... -PropertySource provider2 = ... - -// aggregate, hereby values from provider 2 override values from provider 1 -PropertySource unionOverriding = PropertySources.aggregate(AggregationPolicy.OVERRIDE(), provider1, provider2); -System.out.println("unionOverriding: " + unionOverriding); - -// ignore duplicates, values present in provider 1 are not overriden by provider 2 -PropertySource unionIgnoringDuplicates = PropertySources.aggregate(AggregationPolicy.IGNORE_DUPLICATES(), provider1, provider2); -System.out.println("unionIgnoringDuplicates: " + unionIgnoringDuplicates); - -// this variant combines/maps duplicate values into a new value -PropertySource unionCombined = PropertySources.aggregate(AggregationPolicy.COMBINE(), provider1, provider2); -System.out.println("unionCombined: " + unionCombined); - -// This variant throws an exception since there are key/value paris in both providers, but with different values -try{ - PropertySources.aggregate(AggregationPolicy.EXCEPTION(), provider1, provider2); -} -catch(ConfigException e){ - // expected! -} --------------------------------------------- - -The example above produces the following outpout: - -[source,listing] -.Example Combining PropertySources --------------------------------------------- -AggregatedPropertySource{ - (name = dynamicAggregationTests) - a = "[a][A]" - b = "[b][B]" - c = "[c][C]" - d = "[D]" - e = "[E]" - f = "[F]" - g = "[g]" - h = "[h]" - i = "[i]" -} -unionOverriding: AggregatedPropertySource{ - (name = <noname>) - a = "A" - b = "B" - c = "C" - d = "D" - e = "E" - f = "F" - g = "g" - h = "h" - i = "i" -} -unionIgnoringDuplicates: AggregatedPropertySource{ - (name = <noname>) - a = "a" - b = "b" - c = "c" - d = "D" - e = "E" - f = "F" - g = "g" - h = "h" - i = "i" -} -unionCombined: AggregatedPropertySource{ - (name = <noname>) - a = "a,A" - b = "b,B" - c = "c,C" - d = "D" - e = "E" - f = "F" - g = "g" - h = "h" - i = "i" -} --------------------------------------------- - -No +AggregationPolicy+ is also an interface that can be implemented: - -[source,java] -.AggregationPolicy Interface --------------------------------------------- -@FunctionalInterface -public interface AggregationPolicy { - String aggregate(String key, String value1, String value2); -} --------------------------------------------- - -So we can also define our own aggregation strategy using a Lambda expression: - -[source,java] -.Use a Custom AggregationPolicy --------------------------------------------- -PropertySource provider1 = ...; -PropertySource provider2 = ...; -PropertySource props = PropertySources.aggregate( - (k, v1, v2) -> (v1 != null ? v1 : "") + '[' + v2 + "]", - MetaInfo.of("dynamicAggregationTests"), - props1, props2); -System.out.println(props); --------------------------------------------- - -Additionally we also pass here an instance of +MetaInfo+. The output of this code snippet is as follows: - -[source,listing] -.Listing of dynamic aggregation policy --------------------------------------------- -AggregatedPropertySource{ - (name = dynamicAggregationTests) - a = "[a][A]" - b = "[b][B]" - c = "[c][C]" - d = "[D]" - e = "[E]" - f = "[F]" - g = "[g]" - h = "[h]" - i = "[i]" -} --------------------------------------------- - -Summarizing the +PropertySources+ singleton allows to combine providers in various forms: - -[source,listing] -.Methods provided on PropertySources --------------------------------------------- -public final class PropertySources { - - private PropertySources() {} - - public static PropertySource fromArgs(String... args) { - public static PropertySource fromArgs(MetaInfo metaInfo, String... args) { - public static PropertySource fromPaths(AggregationPolicy aggregationPolicy, String... paths) { - public static PropertySource fromPaths(String... paths) { - public static PropertySource fromPaths(List<String> paths) { - public static PropertySource fromPaths(AggregationPolicy aggregationPolicy, List<String> paths) { - public static PropertySource fromPaths(MetaInfo metaInfo, List<String> paths) { - public static PropertySource fromPaths(AggregationPolicy aggregationPolicy, MetaInfo metaInfo, List<String> paths) { - public static PropertySource fromUris(URI... uris) { - public static PropertySource fromUris(AggregationPolicy aggregationPolicy, URI... uris) { - public static PropertySource fromUris(List<URI> uris) { - public static PropertySource fromUris(AggregationPolicy aggregationPolicy, List<URI> uris) { - public static PropertySource fromUris(MetaInfo metaInfo, URI... uris) { - public static PropertySource fromUris(AggregationPolicy aggregationPolicy, MetaInfo metaInfo, URI... uris) { - public static PropertySource fromUris(MetaInfo metaInfo, List<URI> uris) { - public static PropertySource fromUris(AggregationPolicy aggregationPolicy, MetaInfo metaInfo, List<URI> uris) { - public static PropertySource fromMap(Map<String, String> map) { - public static PropertySource fromMap(MetaInfo metaInfo, Map<String, String> map) { - public static PropertySource empty() { - public static PropertySource emptyMutable() { - public static PropertySource empty(MetaInfo metaInfo) { - public static PropertySource emptyMutable(MetaInfo metaInfo) { - public static PropertySource fromEnvironmentProperties() { - public static PropertySource fromSystemProperties() { - public static PropertySource freezed(PropertySource provider) { - public static PropertySource aggregate(AggregationPolicy mapping, MetaInfo metaInfo, PropertySource... providers){ - public static PropertySource aggregate(PropertySource... providers) { - public static PropertySource aggregate(List<PropertySource> providers) { - public static PropertySource aggregate(AggregationPolicy mapping, PropertySource... propertyMaps) { - public static PropertySource aggregate(AggregationPolicy mapping, List<PropertySource> providers) { - public static PropertySource mutable(PropertySource provider) { - public static PropertySource intersected(AggregationPolicy aggregationPolicy, PropertySource... providers) { - public static PropertySource intersected(PropertySource... providers) { - public static PropertySource subtracted(PropertySource target, PropertySource... providers) { - public static PropertySource filtered(Predicate<String> filter, PropertySource provider) { - public static PropertySource contextual(Supplier<PropertySource> mapSupplier, - Supplier<String> isolationKeySupplier) { - public static PropertySource delegating(PropertySource mainMap, Map<String, String> parentMap) { - public static PropertySource replacing(PropertySource mainMap, Map<String, String> replacementMap) { -} --------------------------------------------- - - -[[API Configuration]] -=== Configuration -==== Basic Model - -Configuration inherits all basic features from +PropertySource+, but additionally adds functionality for -type safety and extension mechanisms: - -[source,java] -.Interface Configuration --------------------------------------------- -public interface Configuration extends PropertySource{ - - default OptionalBoolean getBoolean(String key); - default OptionalInt getInteger(String key); - default OptionalLong getLong(String key); - default OptionalDouble getDouble(String key); - default <T> Optional<T> getAdapted(String key, PropertyAdapter<T> adapter); - <T> Optional<T> get(String key, Class<T> type); - - // accessing areas - default Set<String> getAreas(); - default Set<String> getTransitiveAreas(); - default Set<String> getAreas(final Predicate<String> predicate); - default Set<String> getTransitiveAreas(Predicate<String> predicate); - default boolean containsArea(String key); - - // extension points - default Configuration with(ConfigOperator operator); - default <T> T query(ConfigQuery<T> query); - - // versioning - default String getVersion(){return "N/A";} - void addPropertyChangeListener(PropertyChangeListener l); - void removePropertyChangeListener(PropertyChangeListener l); - - // singleton accessors - public static boolean isDefined(String name); - public static <T> T current(String name, Class<T> template); - public static Configuration current(String name); - public static Configuration current(); - public static <T> T current(Class<T> type){ - public static void configure(Object instance); - public static String evaluateValue(String expression); - public static String evaluateValue(Configuration config, String expression); - public static void addGlobalPropertyChangeListener(PropertyChangeListener listener); - public static void removeGlobalPropertyChangeListener(PropertyChangeListener listener); -} --------------------------------------------- - -Hereby - -* +XXX getXXX(String)+ provide type safe accessors for all basic wrapper types of the JDK. -* +getAdapted+ allow accessing any type, hereby also passing a +PropertyAdapter+ that converts - the configured literal value to the type required. -* +getAreas()+, +getTransitiveAreas()+ allow to examine the hierarchical tree modeled by the configuration tree. - Optionally also predicates can be passed to select only part of the tree to be returned. -* +containsArea+ allows to check, if an area is defined. -* +with, query+ provide the extension points for adding additional functionality. - -* the static accessor methods define: - ** +current(), current(Class), current(String), current(String, Class)+ return the configuration valid for the current runtime environment. - ** +addPropertyChangeListener, removePropertyChangeListener+ allow to register or unregister - global config change listener instances. - ** evaluateValue allows to evaluate a configuration expression based on a given configuration. - ** +configure+ performs injection of configured values. - -[[TypeConversion]] -==== Type Conversion - -Configuration extend +PropertySource+ and add additional support for non String types. This is achieved -with the help of +PropertyAdapter+ instances: - -[source,java] -.PropertyAdapter --------------------------------------------- -@FunctionalInterface -public interface PropertyAdapter<T>{ - T adapt(String value); -} --------------------------------------------- - -PropertyAdapter instances can be implemented manually or registered and accessed from the -+PropertyAdapers+ singleton. Hereby the exact mechanism is determined by the API backing up the singleton. -By default corresponding +PropertyAdapter+ instances can be registered using the Java +ServiceLoader+ -mechanism, or programmatically ba calling the +register(Class, PropertyAdapter)+ method. - -[source,java] --------------------------------------------- -public final class PropertyAdapters{ - public static <T> PropertyAdapter<T> register(Class<T> targetType, PropertyAdapter<T> adapter); - public static boolean isTargetTypeSupported(Class<?> targetType); - public static <T> PropertyAdapter<T> getAdapter(Class<T> targetType); - public static <T> PropertyAdapter<T> getAdapter(Class<T> targetType, WithPropertyAdapter annotation); -} --------------------------------------------- - -Whereas this mechanism per se looks not very useful it's power shows up when combining it with the annotations -API provided, e.g. look at the following annotated class: - -[source,java] -.Annotated Example Class --------------------------------------------- -public class ConfiguredClass{ - - @ConfiguredProperty - private String testProperty; - - @ConfiguredProperty("a.b.c.key1") - @DefaultValue("The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.") - String value1; - - @ConfiguredProperty("a.b.c.key2") - private int value2; - - @ConfiguredProperty - @DefaultValue("http://127.0.0.1:8080/res/api/v1/info.json";) - private URL accessUrl; - - @ConfiguredProperty - @DefaultValue("5") - private Integer int1; - - @ConfiguredProperty("a.b.customType") - private MyCustomType myCustomType; - - @ConfiguredProperty("BD") - private BigDecimal bigNumber; - - ... -} --------------------------------------------- - -The class does not show all the possibilities that are provided, but it shows that arbitrary types can be supported easily. -This applied similarly to collection types, whereas collections are more advanced and therefore described in a separate section -later. - -Given the class above and the current configuration can provide the values required, configuring an instance of the -class is simple: - -[source,java] -.Configuring the Example Class --------------------------------------------- -ConfiguredClass classInstance = new ConfiguredClass(); -Configuration.configure(configuredClass); --------------------------------------------- - -Additional types can transparently be supported by implementing and registering corresponding SPI instances. This is explained -in the SPI documentation of {name}. - -==== Extension Points - -We are well aware of the fact that this library will not be able to cover all kinds of use cases. Therefore -we have added similar functional extension mechanisms that were used in other areas of the Java eco-system as well: - -* +ConfigOperator+ define unary operations on +Configuration+. They can be used for filtering, implementing - configuration views, security interception etc. -* +ConfigQuery+ defines a function returning any kind of result based on a configuration instance. Typical - use cases of queries could be the implementation of configuration SPI instances that are required - by other libraries or frameworks. - -Both interfaces hereby are defined as functional interfaces: - -[source,java] -.ConfigOperator and ConfigQuery --------------------------------------------- -@FunctionalInterface -public interface ConfigOperator{ - Configuration operate(Configuration config); -} - -@FunctionalInterface -public interface ConfigQuery<T>{ - T query(Configuration config); -} --------------------------------------------- - -Both interfaces can be applied on a +Configuration+ instance: - -[source,java] -.Applying Config operators and queries --------------------------------------------- -Configuration secured = Configuration.of().apply(ConfigSecurity::secure); -ConfigSecurity securityContext = Configuration.of().query(ConfigSecurity::targetSecurityContext); --------------------------------------------- - -NOTE: +ConfigSecurity+ is an arbitrary class. - -=== Configuration Injection - -The +Configuration+ interface provides static methods that allow to anykind of instances be configured -ny just passing the instances calling +Configuration.configure(instance);+. The classes passed hereby must -be annotated with +@ConfiguredProperty+ to define the configured properties. Hereby this annotation can be -used in multiple ways and combined with other annotations such as +@DefaultValue+, -+@WithLoadPolicy+, +@WithConfig+, +@WithConfigOperator+, +@WithPropertyAdapter+. - -To illustrate the mechanism below the most simple variant of a configured class is given: - -[source,java] -.Most simple configured class --------------------------------------------- -pubic class ConfiguredItem{ - @ConfiguredProperty - private String aValue; -} --------------------------------------------- - -When this class is configured, e.g. by passing it to +Configuration.configure(Object)+, -the following is happening: - -* The current valid +Configuration+ is evaluated by calling +Configuration cfg = Configuration.of();+ -* The current property value (String) is evaluated by calling +cfg.get("aValue");+ -* if not successful, an error is thrown (+ConfigException+) -* On success, since no type conversion is involved, the value is injected. -* The configured bean is registered as a weak change listener in the config system's underlying - configuration, so future config changes can be propagated (controllable by applying the - +@WithLoadPolicy+ annotation). - -In the next example we explicitly define the property value: -[source,java] --------------------------------------------- -pubic class ConfiguredItem{ - - @ConfiguredProperty - @ConfiguredProperty("a.b.value") - @configuredProperty("a.b.deprecated.value") - @DefaultValue("${env:java.version}") - private String aValue; -} --------------------------------------------- - -Within this example we evaluate multiple possible keys. Evaluation is aborted if a key could be successfully -resolved. Hereby the ordering of the annotations define the ordering of resolution, so in the example above -resolution equals to +"aValue", "a.b.value", "a.b.deprecated.value"+. If no value could be read -from the configuration, it uses the value from the +@DefaultValue+ annotation. Interesting here -is that this value is not static, it is evaluated by calling +Configuration.evaluateValue(Configuration, String)+. - -=== Environment - -The environment basically is also a kind of property/value provider similar to +System.getProperties()+ and +System -.getenv()+ in the JDK. Nevertheless it provides additional functionality: - -[source,java] -.Interface Environment --------------------------------------------- -public interface Environments { - - String getEnvironmentType(); - String getEnvironmentId(); - Environment getParentEnvironment(); - - Optional<String> get(String key); - boolean containsKey(String key); - Set<String> keySet(); - Map<String,String> toMap(); - - public static Environment current(){ - public static Environment getRootEnvironment(){ - public static List<String> getEnvironmentTypeOrder(){ - public static List<String> getEnvironmentHierarchy(){ - public static Optional<Environment> getInstance(String environmentType, String contextId){ - public static Set<String> getEnvironmentContexts(String environmentType){ - public static boolean isEnvironmentActive(String environmentType){ --------------------------------------------- - -* environments are hierarchical. Hereby all environments inherit from the root environment. The root environment - hereby must contain - ** all JDK's system properties, with same keys, values - ** all JDK's environment properties, prefixed with +env:+. - ** additional root properties are allowed as well. -* the root environment is always directly accessible by calling +Environment.getRootEnvironment()+ -* the current environment can be accessed by calling +Environment.of()+. -* each environment also defines a +Stage+ (implementing +StageSupplier+). Hereby, if not set explicitly the +Stage+ is inherited from the root - environment. Consequently the root environment must provide a +Stage+, which by default is +Stage.development()+. - -Additionally each environment instance is uniquely identified by the environment type (accessible from -+getEnvironmentType()+ and the environment id (accessible from +getEnvironmentId()+). So it is possible to access -an +Environment+ by calling +of(String environmentType, String environmentId)+. Implementations may restrict access -to environments depending on the current runtime environment (runtime context) active. The API does -not require further aspects. - -The call to +getEnvironmentIds(String)+ returns all context ids of the known +Environment+ instances -of a given type. E.g. assuming there is an environment type +war+ calling +Environment.getEnvironmentIds("war")+ -may return +"/web/app1", "/web/app2"+ (assuming the war context ids equal the web applications root contexts). - -All environments are basically ordered. The ordering can be accessed by calling +getEnvironmentTypeOrder()+. Hereby -not every environment type in a hierarchy must necessarily present. This is reflected by +getEnvironmentHierarchy()+ -which returns the environment type ids in order, but only containing the types of the environments -currently present and accessible in the hierarchy. As an example an environment type order in an advanced -use case could be something like +"root","ear","war","saas","user"+, whereas the concrete environment type hierarchy -may be +"root","war","saas"+, because the application was not included -in an additional ear archive and no user is currently active (anonymous). The call to +isEnvironmentActive(String)+ -allows to determine if an environment of the given type is currently active. -Finally the environment hierarchy is of course similarly reflected by the relationship (+getParentEnvironment()+). -The following code should illustrate some of these concepts: - -[source,java] -.Interface Environment --------------------------------------------- -List<String> envHierarchy = Environment.getEnvironmentHierarchy(); - // -> "root","war","saas" -Environment env = Environment.of(); -System.out.println(env.getEnvironmentContext()); // saas -System.out.println(env.getEnvironmentId()); // mysolution_pro -env = env.getParentEnvironment(); -System.out.println(env.getEnvironmentContext()); // war -System.out.println(env.getEnvironmentId()); // pro -env = env.getParentEnvironment(); -System.out.println(env.getEnvironmentContext()); // root -System.out.println(env.getEnvironmentId()); // system -env = env.getParentEnvironment(); -// env is null now! --------------------------------------------- - -
