Repository: incubator-tamaya Updated Branches: refs/heads/master bed10573d -> a55d1c973
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a55d1c97/docs/design/0_UseCases.adoc ---------------------------------------------------------------------- diff --git a/docs/design/0_UseCases.adoc b/docs/design/0_UseCases.adoc index a7719ab..8177c14 100644 --- a/docs/design/0_UseCases.adoc +++ b/docs/design/0_UseCases.adoc @@ -2,20 +2,132 @@ [[UseCases]] == Use Cases -This section describes some, but not all, of the use cases that should be covered with this JSR. +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 created that is preconfigured by some property files contained in the -Java archive. Using the command line it is possible to redefine/override some of the properties, e.g. by using system properties. -Typical example are small command line tools. - --> It must be possible to define default configuration and package it with the (SE) application. +In this most simple usage scenario an application is configured by some property files contained in the +Java archive. --> It must be possible to consider system properties or other command line arguments for usage with configuration. +* 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. --> It must be possible that command line arguments can override defaults configured. [[UCAdvancedPropertyBasedConfiguration]] === Advanced Property Based Configuration @@ -25,35 +137,30 @@ 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. -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. - --> Environment properties must be considered as well. - --> It must be possible to control overriding. - --> It must be possible to dynamically add configuration locations to be considered. - --> It must be possible to define customized configuration formats. [[UCModularizedConfiguration]] === Modularized Configuration -When systems grow they must be modularized to keep control. Whereas that sounds not really fancy, it leads to additional things -to be considered by a configuration system: +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. -* The different modules must have access to their own "module configuration". -* Modules may want to define a contract, which properties may be overriden. +* 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. -Consequently --> Parts of Configuration must be identifiable and accessible in a isolated way. +[[UCTypeSupport]] +=== Extended Type Support --> Module configuration requires partial isolation or other mechanisms to ensure only configuration aspects - that are allowed to be overriden can be overriden. +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 @@ -155,67 +262,7 @@ to be configured is managed: * 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. -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; - - // complex algorithm based on the currency -} ----------------------------------------------------- - -The instance then can be passed for being configured: - -[source, java] -.Configuring a POJO ----------------------------------------------------- -MyPojo instance = new MyPojo(); -Configuration.configure(instance); ----------------------------------------------------- - -Another way of accessing configuration would be by defining a type safe template -providing access to the configured values and let the configuration system implement -the interface: - -[source, java] -.Type Safe Configuration Template Example ----------------------------------------------------- -public interface MyConfig { - @ConfigProperty("myCurrency") - @DefaultValue("CHF") - String getCurrency(); - - @ConfigProperty("myCurrencyRate") - Long getCurrencyRate(); - -} ----------------------------------------------------- - -The configuration system will then implement the -interface using configuration as follows: - -[source, java] -.Accessing a type safe Configuration Template ----------------------------------------------------- -MyConfig config = Configuration.of(MyConfig.class); ----------------------------------------------------- - -Finally there is a generic +Configuration+ type that can be used as well, which -provides full access to all features: -[source, java] -.Accessing Configuration ----------------------------------------------------- -Configuration config = Configuration.of(Configuration.class); ----------------------------------------------------- [[UCTesting]] http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a55d1c97/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfig.java ---------------------------------------------------------------------- diff --git a/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfig.java b/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfig.java index 0f7c651..681c02b 100644 --- a/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfig.java +++ b/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfig.java @@ -19,7 +19,7 @@ package org.apache.tamaya.management; import org.apache.tamaya.ConfigException; -import org.apache.tamaya.core.properties.AggregationPolicy; +import org.apache.tamaya.AggregationPolicy; import java.util.Map; import java.util.Set; http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a55d1c97/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfigMBean.java ---------------------------------------------------------------------- diff --git a/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfigMBean.java b/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfigMBean.java index 5e57111..0555697 100644 --- a/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfigMBean.java +++ b/modules/managed/src/main/java/org/apache/tamaya/management/ManagedConfigMBean.java @@ -20,7 +20,7 @@ package org.apache.tamaya.management; import org.apache.tamaya.ConfigException; -import org.apache.tamaya.core.properties.AggregationPolicy; +import org.apache.tamaya.AggregationPolicy; import java.util.Map; import java.util.Set;
