http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_injection.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_injection.adoc b/content/documentation/extensions/mod_injection.adoc index 97508db..3074a5d 100644 --- a/content/documentation/extensions/mod_injection.adoc +++ b/content/documentation/extensions/mod_injection.adoc @@ -134,10 +134,10 @@ Tamaya inject the configuration (or throw a +ConfigException+, if this is not po .Configuring the +ConfiguredClass+ Instance -------------------------------------------- ConfiguredClass classInstance = new ConfiguredClass(); -ConfigurationInjector.configure(configuredClass); +ConfigurationInjector.getInstance().configure(configuredClass); Tenant tenant = new Tenant(); -ConfigurationInjector.configure(tenant); +ConfigurationInjector.getInstance().configure(tenant); -------------------------------------------- NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used @@ -194,7 +194,7 @@ pubic class ConfiguredItem{ When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+, the following is happening: -* The current valid +Configuration+ is evaluated by calling +Configuration cfg = ConfigurationProvider.getConfiguration();+ +* The current valid +Configuration+ is evaluated by calling +Configuration cfg = Configuration.current();+ * The current property value (String) is evaluated by calling +cfg.get("aValue");+ for each possible key (mutliple keys are possible). * if not successful, an error is thrown (+ConfigException+) @@ -385,32 +385,31 @@ public interface DynamicValue<T> { boolean isPresent(); T orElse(T other); - // Enabled with Java 8 - // T orElseGet(ConfiguredItemSupplier<? extends T> other); - // <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X; + T orElseGet(ConfiguredItemSupplier<? extends T> other); + <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X; } public enum UpdatePolicy{ IMMEDIATE, - EXPLCIT, + EXPLICIT, NEVER, LOG_AND_DISCARD } -------------------------------------------- -//Summarizing +DynamicValue+ looks somehow similar to the new +Optional+ class added with Java 8. It provides -//a wrapper class around a configured instance. Additionally this class provides functionality that gives -//active control, to manage a configured value based on a ++LoadingPolicy+: -// -//* +IMMEDEATE+ means that when the configuration system detects a change on the underlying value, the new value -// is automatically applied without any further notice. -//* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+ property. if +getNewValue()+ -// returns a non null value, the new value can be applied by calling +commit()+. You can always access the newest value, -// hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible ti ignore a change by calling -// +discard()+. -//* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded. -//* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded. +Summarizing +DynamicValue+ looks somehow similar to the new +Optional+ class added with Java 8. It provides +a wrapper class around a configured instance. Additionally this class provides functionality that gives +active control, to manage a configured value based on a ++LoadingPolicy+: + +* +IMMEDIATE+ means that when the configuration system detects a change on the underlying value, the new value + is automatically applied without any further notice. +* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+ property. if +getNewValue()+ + returns a non null value, the new value can be applied by calling +commit()+. You can always access the newest value, + hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible ti ignore a change by calling + +discard()+. +* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded. +* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded. Summarizing a +DynamicValue+ allows you @@ -422,35 +421,6 @@ Dynamic values also allow on-the-fly reevaluation of the value by calling +evalu instance is not changed. -===== The Loading policy enum - -The +LoadPolicy+ enum defines different configuration loading behaviour -to be applied: - -[source,java] --------------------------------------------- -@Deprecated -public enum LoadPolicy { - /** - * The configuration keys is evaluated once, when the owning component is loaded/configured, but never updated later. - */ - INITIAL, - /** - * The configuration keys is evaluated exactly once on its first access/use lazily, but never updated later. - * @see DynamicValue#get() - * @see DynamicValue#commitAndGet() - */ - LAZY, - /** - * The configuration value is evaluated every time it is accessed. - */ - ALWAYS -} --------------------------------------------- - -This enum type currently is used only internally, so avoid using it as of -now in your code is recommended. - === Configuration Events
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_jndi.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_jndi.adoc b/content/documentation/extensions/mod_jndi.adoc index c3f12f8..74b98bc 100644 --- a/content/documentation/extensions/mod_jndi.adoc +++ b/content/documentation/extensions/mod_jndi.adoc @@ -18,7 +18,7 @@ JNDI context. === Compatibility -The module is based on Java 7, so it will not run on Java 7 and beyond. +The module is based on Java 8. === Installation http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_jodatime.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_jodatime.adoc b/content/documentation/extensions/mod_jodatime.adoc index a49fa7b..13d5035 100644 --- a/content/documentation/extensions/mod_jodatime.adoc +++ b/content/documentation/extensions/mod_jodatime.adoc @@ -38,7 +38,7 @@ Joda-Time based values directly from a given configuration. [source,java] ----------------------------------------------- -Configuration configuration = ConfigurationProvider.getConfiguration(); +Configuration configuration = Configuration.current(); DateTime pit = configuration.get("pointInTime", DateTime.class) ----------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_json.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_json.adoc b/content/documentation/extensions/mod_json.adoc index d22ad2f..ee2323c 100644 --- a/content/documentation/extensions/mod_json.adoc +++ b/content/documentation/extensions/mod_json.adoc @@ -39,7 +39,7 @@ This extension uses SPI defined by the +tamaya.formats+ extension module. === Compatibility -The module is based on Java 7, so it will run on Java 7 and beyond. +The module is based on Java 8. === Installation @@ -65,7 +65,7 @@ used: [source, java] ----------------------------------------------- -ConfigurationData dataRead = ConfigurationFormats.readConfig( +ConfigurationData dataRead = ConfigurationFormats.getInstance().readConfig( getClassLoader().getResource("myFileConfig.json"), new JSONFormat())); ----------------------------------------------- @@ -75,6 +75,6 @@ registers the _json_ format automatically using the `ServiceContext`): [source, java] ----------------------------------------------- -PropertySource ps = ConfigurationFormats.createPropertySource( +PropertySource ps = ConfigurationFormats.getInstance().createPropertySource( getClassLoader().getResource("myFileConfig.json")); ----------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_metamodel.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_metamodel.adoc b/content/documentation/extensions/mod_metamodel.adoc index d1dec94..3cec143 100644 --- a/content/documentation/extensions/mod_metamodel.adoc +++ b/content/documentation/extensions/mod_metamodel.adoc @@ -71,7 +71,7 @@ as the system's _default_ configuration (accessible from `ConfigurationProvider. === Compatibility -The module is based on Java 7, so it will not run on Java 7 and beyond. +The module is based on Java 8. === Installation http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_microprofile.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_microprofile.adoc b/content/documentation/extensions/mod_microprofile.adoc index b6d8bb0..c9cfe3e 100644 --- a/content/documentation/extensions/mod_microprofile.adoc +++ b/content/documentation/extensions/mod_microprofile.adoc @@ -25,7 +25,7 @@ Tamaya _Microprofile_ currently provides full integration for the Microprofile C === Compatibility -Both modules are based on Java 8, so they will run on Java 8 and beyond. The implemented Microprofile API is currently +Both modules are based on Java 8. The implemented Microprofile API is currently version 1.1. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_mutable_config.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_mutable_config.adoc b/content/documentation/extensions/mod_mutable_config.adoc index 237572c..4a61426 100644 --- a/content/documentation/extensions/mod_mutable_config.adoc +++ b/content/documentation/extensions/mod_mutable_config.adoc @@ -21,7 +21,7 @@ functionality. === Compatibility -The module is based on Java 7, so it can be used with Java 7 and beyond. +The module is based on Java 8. === Installation @@ -42,7 +42,7 @@ To benefit from configuration mutability support you only must add the correspon ==== Accessing MutableConfiguration -The core of the module is the +MutableConfigurationProvider+ singleton, which provides access to +MutableConfiguration+ +The core of the module is the +MutableConfiguration+ interface, which provides access to +MutableConfiguration+ instance, which extends +Configuration+. This interface adds additional methods to add/update or remove property values. Hereby each +MutableConfiguration+ manages a transaction like context, which includes a UUID that identifes a change. @@ -56,8 +56,7 @@ finally changes written back to the backend: [source,java] .Accessing and changing configuration -------------------------------------------- -MutableConfiguration config = MutableConfigurationProvider - .createMutableConfiguration(); +MutableConfiguration config = MutableConfiguration.create(); config.put("newKey", "newValue") .put("anotherKey", "updatedValue") .remove("valueNotValid") @@ -71,8 +70,7 @@ We can also pass any +Configuration+ to render it into a mutable instance, e.g. .Explicitly passing the backing configuration -------------------------------------------- Configuration config = ...; -MutableConfiguration config = MutableConfigurationProvider - .createMutableConfiguration(config); +MutableConfiguration config = MutableConfiguration.create(config); -------------------------------------------- NOTE: If a configuration does not contain any +MutablePropertySource+ instances, @@ -85,38 +83,26 @@ We will show in the following sections more details on the options provided... [source, java] --------------------------------------------- -public final class MutableConfigurationProvider { - - private MutableConfigurationProvider(){} - - public static MutableConfiguration createMutableConfiguration(); - public static MutableConfiguration createMutableConfiguration( - ChangePropagationPolicy changePropgationPolicy); - public static MutableConfiguration createMutableConfiguration(Configuration configuration); - public static MutableConfiguration createMutableConfiguration( - Configuration configuration, - ChangePropagationPolicy changePropgationPolicy); - - [...] -} ---------------------------------------------- - -As we have not yet shown it, +MutableConfiguration+ is defined as follows: - -[source, java] ---------------------------------------------- public interface MutableConfiguration extends Configuration { void store(); - ConfigChangeRequest getConfigChangeRequest(); ChangePropagationPolicy getChangePropagationPolicy(); - MutableConfiguration put(String key, String value); MutableConfiguration putAll(Map<String, String> properties); MutableConfiguration remove(Collection<String> keys); MutableConfiguration remove(String... keys); + public static MutableConfiguration create(); + public static MutableConfiguration create(ClassLoader classLoader); + public static MutableConfiguration create(ChangePropagationPolicy changePropgationPolicy); + public static MutableConfiguration create(ChangePropagationPolicy changePropgationPolicy, + ClassLoader classLoader); + public static MutableConfiguration create(Configuration configuration); + public static MutableConfiguration create(Configuration configuration, + ChangePropagationPolicy changePropgationPolicy); + + [...] } --------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_optional.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_optional.adoc b/content/documentation/extensions/mod_optional.adoc index 0b7d948..cc3e58b 100644 --- a/content/documentation/extensions/mod_optional.adoc +++ b/content/documentation/extensions/mod_optional.adoc @@ -24,7 +24,7 @@ Additionally an +EvaluationPolicy+ lets you define the precedence of configured === Compatibility -The module is based on Java 7, so it will not run on Java 7 and beyond. +The module is based on Java 8. === Installation http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_resolver.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_resolver.adoc b/content/documentation/extensions/mod_resolver.adoc index ad95d14..1bf6b86 100644 --- a/content/documentation/extensions/mod_resolver.adoc +++ b/content/documentation/extensions/mod_resolver.adoc @@ -21,7 +21,7 @@ cycles to loop endlessly. === Compatibility -The module is based on Java 7, so it can be used with Java 7 and beyond. +The module is based on Java 8. === Installation @@ -71,6 +71,25 @@ Currently the module defines the following resolvers: |======= +=== Explicit Expression Resolution + +The resolvers registered are normall running implicitly, when corresponding placeholders are used in configuration +values. Additionally the expression resolution functionality can also used explcitly: + +[source,java] +--------------- +public final class Resolver { + + public static Resolver getInstance(); + public static Resolver getInstance(ClassLoader classLoader); + + public String evaluateExpression(String key, String value); + public String evaluateExpression(String key, String value, ClassLoader classLoader); + public String evaluateExpression(String value); + public String evaluateExpression(String value, boolean maskNotFound); +} +--------------- + === SPI: Implementing your own Resolvers The module also provides a small but powerful SPI for adding your own resolver implementations. Basically the http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_resources.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_resources.adoc b/content/documentation/extensions/mod_resources.adoc index 2e06053..5ee5657 100644 --- a/content/documentation/extensions/mod_resources.adoc +++ b/content/documentation/extensions/mod_resources.adoc @@ -17,7 +17,7 @@ descriptive ant-styled resource patterns. === Compatibility -The module is based on Java 7, so it can be used with Java 7 and beyond. +The module is based on Java 8. === Installation @@ -47,10 +47,12 @@ ResourceResolver resolver = ConfigResources.getResourceResolver(); [source,java] ----------------------------------------------- public interface ResourceResolver { + + static ResourceResolver getInstance(); + static ResourceResolver getInstance(ClassLoader classLoader); + Collection<URL> getResources(Collection<String> expressions) {...} Collection<URL> getResources(String... expressions) {...} - Collection<URL> getResources(ClassLoader classLoader, String... expressions){...} - Collection<URL> getResources(ClassLoader classLoader, Collection<String> expressions); } ----------------------------------------------- @@ -114,7 +116,7 @@ public class PathBasedPropertySourceProvider implements PropertySourceProvider { @Override public Collection<PropertySource> getPropertySources() { List<PropertySource> propertySources = new ArrayList<>(); - Collection<URL> resources = ConfigResources.getResourceResolver().getResources("META-INF/cfg/**/*.properties"); + Collection<URL> resources = ResourceResolver.getInstance().getResources("META-INF/cfg/**/*.properties"); for(URL url:resources){ Properties props = new Properties(); try(InputStream is = url.openStream()){ @@ -159,9 +161,6 @@ public class PathBasedPropertySourceProvider implements PropertySourceProvider { === SPI -The +ResourceResolver+ that is returned by the +ConfigResources+ singleton is determined by the -current +ServiceContext+, by default you can replace the default implementation by registering an +The +ResourceResolver+ that is returned is determined by the +current +ServiceContext+. You can replace the default implementation by registering an alternate implementation with an overriding +@Priority+ annotation added using the +ServiceLoader+. - -Additionally a +BaseResourceResolver+ class can be used to reduce the amount of code to be written -on your own. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_server.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_server.adoc b/content/documentation/extensions/mod_server.adoc index 52081b6..2d38221 100644 --- a/content/documentation/extensions/mod_server.adoc +++ b/content/documentation/extensions/mod_server.adoc @@ -114,12 +114,12 @@ The server module formats the configuration returned by default in the following "sun.jnu.encoding": "Cp1252", "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers", "sun.os.patch.level": "", - "_class": "org.apache.tamaya.functions.FilteredConfiguration", - "_info.filter": "java.v,sun", - "_info.format": "application/json", - "_info.timestamp": "1441463200571", - "_timestamp": "1441463200571", - "_type": "Configuration" + "[META]class": "org.apache.tamaya.functions.FilteredConfiguration", + "[META]info.filter": "java.v,sun", + "[META]info.format": "application/json", + "[META]info.timestamp": "1441463200571", + "[META]timestamp": "1441463200571", + "[META]type": "Configuration" } ----------------------------------------------- @@ -187,12 +187,12 @@ Configuration: sun.jnu.encoding: Cp1252, sun.management.compiler: HotSpot 64-Bit Tiered Compilers, sun.os.patch.level: , - _class: org.apache.tamaya.functions.FilteredConfiguration, - _info.filter: java.v,sun, - _info.format: text/plain, - _info.timestamp: 1441463082020, - _timestamp: 1441463082021, - _type: Configuration + [META]class: org.apache.tamaya.functions.FilteredConfiguration, + [META]info.filter: java.v,sun, + [META]info.format: text/plain, + [META]info.timestamp: 1441463082020, + [META]timestamp: 1441463082021, + [META]type: Configuration ----------------------------------------------- @@ -227,12 +227,12 @@ Configuration: sun.jnu.encoding: Cp1252, sun.management.compiler: HotSpot 64-Bit Tiered Compilers, sun.os.patch.level: , - _class: org.apache.tamaya.functions.FilteredConfiguration, - _info.filter: java.v,sun, - _info.format: text/html, - _info.timestamp: 1441463459653, - _timestamp: 1441463459654, - _type: Configuration + [META]class: org.apache.tamaya.functions.FilteredConfiguration, + [META]info.filter: java.v,sun, + [META]info.format: text/html, + [META]info.timestamp: 1441463459653, + [META]timestamp: 1441463459654, + [META]type: Configuration </pre> </body> </html> http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_usagetracker.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_usagetracker.adoc b/content/documentation/extensions/mod_usagetracker.adoc index e0bd8c7..4cd0579 100644 --- a/content/documentation/extensions/mod_usagetracker.adoc +++ b/content/documentation/extensions/mod_usagetracker.adoc @@ -20,7 +20,7 @@ VM. === Compatibility -The module is based on Java 7, so it can be used with Java 7 and beyond. +The module is based on Java 8. === Installation @@ -93,16 +93,19 @@ singleton for configuration statistics is defined as follows: [source,java] ----------------------------------------------------------- -public final class ConfigUsageStats{ - public static Set<String> getIgnoredUsagePackages(); - public static void addIgnoredUsagePackages(String... packageName); - public static void enableUsageTracking(boolean enabled); - public static Usage getUsage(String key); - public static Collection<Usage> getUsages(); - public static void clearUsageStats(); - public static Usage getUsageAllProperties(); - public static boolean isUsageTrackingEnabled(); - public static String getUsageInfo(); +public final class ConfigUsage{ + public static ConfigUsage getInstance(); + public static ConfigUsage getInstance(ClassLoader classLoader); + + public Set<String> getIgnoredUsagePackages(); + public void addIgnoredUsagePackages(String... packageName); + public void enableUsageTracking(boolean enabled); + public Usage getUsage(String key); + public Collection<Usage> getUsages(); + public void clearUsageStats(); + public Usage getUsageAllProperties(); + public boolean isUsageTrackingEnabled(); + public String getUsageInfo(); } ----------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_validation.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_validation.adoc b/content/documentation/extensions/mod_validation.adoc index 5b239cb..897bb56 100644 --- a/content/documentation/extensions/mod_validation.adoc +++ b/content/documentation/extensions/mod_validation.adoc @@ -20,7 +20,7 @@ defined in a Tamaya Metaconfiguration XML file. === Compatibility -The module is based on Java 7, so it will run on Java 7 and beyond. +The module is based on Java 8. === Installation http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_vertx.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_vertx.adoc b/content/documentation/extensions/mod_vertx.adoc index eef576b..906367d 100644 --- a/content/documentation/extensions/mod_vertx.adoc +++ b/content/documentation/extensions/mod_vertx.adoc @@ -22,7 +22,7 @@ Tamaya _Vertx_ provides configuration services that can be used in a Vertx envir === Compatibility -The module requires Java 8, so it will not run on Java 7. +The module requires Java 8. === Installation @@ -62,7 +62,7 @@ public abstract class AbstractConfiguredVerticle extends AbstractVerticle{ public Configuration getConfiguration(){ if(this.configuration==null){ - this.configuration = ConfigurationProvider.getConfiguration(); + this.configuration = Configuration.current(); } return this.configuration; } @@ -73,7 +73,7 @@ public abstract class AbstractConfiguredVerticle extends AbstractVerticle{ } protected void configure(){ - ConfigurationInjection.getConfigurationInjector().configure(this, getConfiguration()); + ConfigurationInjector.getInstance().configure(this, getConfiguration()); } protected final String getConfigProperty(String key); http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/extensions/mod_yaml.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_yaml.adoc b/content/documentation/extensions/mod_yaml.adoc index ceef59a..da76eba 100644 --- a/content/documentation/extensions/mod_yaml.adoc +++ b/content/documentation/extensions/mod_yaml.adoc @@ -20,7 +20,7 @@ use intendation for expressing hierarchy, which makes yaml configuration files v === Compatibility -The YAML module is based on Java 7, so it will run on Java 7 and beyond. +The YAML module is based on Java 8. === Installation @@ -45,7 +45,7 @@ For reading YAML based onfiguration most easily a +YAMLFormat+ can be provided: [source, java] ----------------------------------------------- -PropertySource ps = ConfigurationFormats.createPropertySource( +PropertySource ps = ConfigurationFormats.getInstance().createPropertySource( getClassLoader().getResource("myFileConfig.yaml"), new YAMLFormat())); ----------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/quickstart.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/quickstart.adoc b/content/documentation/quickstart.adoc index e396bcc..edd6757 100644 --- a/content/documentation/quickstart.adoc +++ b/content/documentation/quickstart.adoc @@ -4,11 +4,9 @@ == Apache Tamaya: Quickstart -The fastest way to start with Tamaya is just using the _Core_ implementation, -implementing the **API** in a minimalistic way. For that add the following -Maven dependency to your project: - -=== Adding the Tamaya Dependency +The fastest way to start with Tamaya is just using the _Core_ module, which +provides a simple configuration API. To start add the folloeing +dependency to your project: [source,xml,subs="verbatim,attributes"] ---- @@ -29,34 +27,30 @@ to provide the default values when accessing the configuration: Configuration config = Configuration.current(); String aTextValue = config.getOrDefault("my.value.key", "N/A"); -int aNumericValue = config.getOrDefault("my.numValueKey", Integer.class, 15 /* default */); +int aNumericValue = config.getOrDefault("my.numValueKey", Integer.class, 15); BigDecimal bdValue = config.getOrDefault("my.BD.value", BigDecimal.class, BigDecimal.valueOf(120)); +List<URL> urls = config.get("servers.url", new TypeLiteral<List<URL>>()); ---- -With Java 8 you can, of course, also use +Optional+, e.g. +Of course, you can also use +Optional+ values: [source,java] ---- -Configuration config = Configuration.current(); - String aTextValue = config.getOptional("my.value.key", String.class).orElse("N/A"); ---- === Add/define your configuration data -As seen you can immedeatly start working with your configuration backend, without adding any kind of -default configuration. Nevertheless the _core_ implementation also comes with a _default_ mechanism, -where you can store your configuration as +.properties+ in your classpath: +As seen you can start working with your configuration backend, without adding any kind of +default configuration. Nevertheless Tamaya also comes with a _default_ mechanism: +simply store your configuration into +META-INF/javaconfiguration.properties+ in your classpath! -[source] ----- -META-INF/javaconfiguration.properties ----- Additionally also system properties are taken into account, hereby overriding the _default_ properties. Overall Tamaya by default defines the following configuration model per default (most significant first): . System Properties +. Environment Properties . `META-INF/javaconfiguration.properties` @@ -64,7 +58,7 @@ Overall Tamaya by default defines the following configuration model per default === Multiple configuration files -By default you can provide multiple `javaconfig.properties` files, e.g. as part +By default you can provide multiple `javaconfiguration.properties` files, e.g. as part of multiple jars loaded into your system. The system creates one `PropertySource` for each file found on the classpath. All `PropertySource` instances created are ordered by their precedence. @@ -83,7 +77,7 @@ calculated as follows: NOTE: Since evaluation of the `tamaya.ordinal` is always done first, it is possible to change the ordinal value by adding a corresponding configuration entry to a property source. -Tamaya Core uses the following default ordinals: +Tamaya's Core PropertySources uses the following default ordinals: [width=70] [cols="3,1", option="headers"] @@ -140,7 +134,7 @@ This module also provides a `Resolver` singleton: [source,java] ---- String myExpression = ...; -String resolved = Resolver.evaluateExpression(myExpression); +String resolved = Resolver.getInstance().evaluateExpression(myExpression); ---- @@ -162,7 +156,7 @@ description, e.g. [source,xml,subs="verbatim,attributes"] ---- -Collection<URL> urls = ResourceResolver.getResources("META-INF/cfg/**/*.properties"); +Collection<URL> urls = Resolver.getInstance().getResources("META-INF/cfg/**/*.properties"); ---- For further details refer to the module documentation. @@ -196,7 +190,7 @@ public class MyType { } MyType type = new MyType(); -ConfigurationInjector.configure(type); +ConfigurationInjector.getInstance().configure(type); ---- Or the same as template: @@ -208,7 +202,7 @@ public interface MyTypeTemplate { public String getName(); } -MyTypeTemplate type = ConfigurationInjector.createTemplate(MyTypeTemplate.class); +MyTypeTemplate type = ConfigurationInjector.getInstance().createTemplate(MyTypeTemplate.class); ---- Currently the following resolvers are available: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/7fc31c0a/content/documentation/spisupport.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/spisupport.adoc b/content/documentation/spisupport.adoc index 1f727e4..82c4cec 100644 --- a/content/documentation/spisupport.adoc +++ b/content/documentation/spisupport.adoc @@ -9,39 +9,38 @@ toc::[] [[SPISupport]] == Tamaya SPI Support -Tamaya _SPI Support_ is a core module only depending on the API. It implements lots of API and SPI related -artifacts in a portable way. Tamaya's core module reuses this functionality to build up a fully fledged -Tamaya API implementatation. +Tamaya _SPI Support_ is a module only depending on the API. It implements lots of API and SPI related +artifacts in a portable way. Tamaya's core module completes this functionality to implement the +full Tamaya API. This module can be reused also with alternate implementations of the Tamaya API. + === What functionality this module provide? -Tamaya _SPI Support_ provides a few helpful base classes that can be used to implement aspects of Tamaya: +Tamaya _SPI Support_ provides several base classes that can be used to implement the Tamaya Configuration API: -* +BasePropertySource+ provides an abstract *base class* for implementation of your own PropertySources. +* +BasePropertySource+ provides an abstract *base class* for implementation of your own `PropertySource`. * +DefaultConfiguration+ provides you with a simple implementation of the +Configuration+ interface based on a +ConfigurationContext+ provided. This is also very useful for mocking configuration during test execution, but not only constraint to that use case. -* +DefaultConfigurationContext+ provides you with a working implementation of the +ConfigurationContext+. -* Numerous *converters*, including an +EnumConverter+,that is a converter implementation that can automatically select the currect enumeration values based - on a configured entry. +* +DefaultConfigurationContext+ provides an implementation of the +ConfigurationContext+ API. * +MapPropertySource+ implements a property source based on +java.util.Map+. * +PriorityServiceComparator+ compares arbitrary services based on their +@Priority+ annotations (also handling the case, where no such annotation is present). * +PropertiesResourcePropertySource+ is an implementation of a +PropertySource+ based on a +Properties+ instance, loadable from any +URL+. + +PropertyConverterManager+ is a useful service class, when implementing instances of +ConfigurationContext+. - It manages registered instances of +PropertyConverter+ and provides easy to use type conversion logic. -+ +PropertyFiltering+ provides another helpful class that manages +PropertyFilter+ instances and provides an - easy to use high level API. + It manages registered instances of +PropertyConverter+ and provides easy to use type conversion logic based on + the registered converters. ++ +PropertyFiltering+ provides a similar class, which manages +PropertyFilter+ instances and provides an + easy to use high level filtering API. + +PropertySourceComparator+ provides an implementation that compares +PropertySources+ based on their +getOrdinal()+ - values and their class names. + values and their class names. It is used to establish the default loading (significance) of property sources. + The default configuration implementation also allows to replace the raw value evaluation logic using a +ConfigValueEvaluator+, similar to Tamaya's core implementation. NOTE: It is highly recommended that you also read the link:../core.html[documentation] of Tamaya's - core implementation, since this describes the abstrations in use in more - detail. This module allows to reuse Tamaya's implementation artifacts but - still allows alternate implementations of the core API to be used. + core implementation, since this describes the abstractions in use in more + detail. === Compatibility
