tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject [1/8] incubator-tamaya git commit: TAMAYA-14: added resource support. TAMAYA-15: Moved PropertyProviders to API, added SPI. TAMAYA-8: Added/improved Javadoc.
Date Mon, 01 Dec 2014 09:43:44 GMT
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;


Mime
View raw message