Updated docs.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/4271e2a1 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/4271e2a1 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/4271e2a1 Branch: refs/heads/master Commit: 4271e2a14481c22ad0579c97c40aa54cdab93a6e Parents: 91a1b45 Author: anatole <[email protected]> Authored: Thu Feb 23 01:24:12 2017 +0100 Committer: anatole <[email protected]> Committed: Thu Feb 23 01:24:12 2017 +0100 ---------------------------------------------------------------------- content/documentation/api.adoc | 3 +- content/documentation/core.adoc | 150 +++++++------ content/documentation/extensions.adoc | 34 +-- .../documentation/extensions/mod_resources.adoc | 2 +- .../documentation/extensions/mod_server.adoc | 211 ++++--------------- content/documentation/quickstart.adoc | 86 ++++++-- 6 files changed, 206 insertions(+), 280 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/4271e2a1/content/documentation/api.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/api.adoc b/content/documentation/api.adoc index c895ef0..9761a5f 100644 --- a/content/documentation/api.adoc +++ b/content/documentation/api.adoc @@ -293,7 +293,8 @@ identified to be necessary: [source,java] -------------------------------------------- public interface PropertySource{ - int getOrdinal(); // This feature is under discussion + // This feature is under discussion + // int getOrdinal(); String getName(); String get(String key); boolean isScannable(); http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/4271e2a1/content/documentation/core.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/core.adoc b/content/documentation/core.adoc index 424818a..496bf07 100644 --- a/content/documentation/core.adoc +++ b/content/documentation/core.adoc @@ -10,111 +10,122 @@ and building blocks for supporting SPI implementations. Tamaya Core contains the following artifacts: -* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder+ ConfigurationProviderSpi+ +* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder, ConfigurationProviderSpi+ * A +java.util.ServiceLoader+ based +ServiceContext+ implementation. Hereby it implements component priorization based on the +@Priority+ annotations. -* A PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances -hereby providing type conversion for all important types. +* A +PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances + hereby providing type conversion for all important types. * A simple default configuration setup using the current classpath and an optional staging variable. * It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and registers them in the global +ConfigurationContext+ -* It provides a +ConfigurationContextBuilder+ implementation (class +DefaultConfigurationContextBuilder+) and allows +* It provides a +ConfigurationContextBuilder+ implementation (+DefaultConfigurationContextBuilder+) and allows changing the current +ConfigurationContext+. The overall size of the library is very small. All required components are implemented and registered, so basically the Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible enough to be extended/accommodated with additional features as needed, such as -* placeholder and resolution mechanisms -* dynamic resource path lookup, e.g. with ant styled patterns -* configuration injection and configuration templates -* abstraction for reusable formats -* integration with other existing solutions -* configuration and configuration isolation targeting Java EE -* dynamic configuration and configuration updates -* Configuration management extensions -* remote configuration +* placeholder and resolution mechanisms (+org.apache.tamaya.ext:tamaya-resolver+) +* dynamic resource path lookup, e.g. with ant styled patterns (+org.apache.tamaya.ext:tamaya-resources+) +* configuration injection and configuration templates (+org.apache.tamaya.ext:tamaya-injcetion-api+) +* abstraction for reusable formats (+org.apache.tamaya.ext:tamaya-formats+) +* integration with other existing solutions (e.g. +org.apache.tamaya.ext:tamaya-spring+) +* configuration and configuration isolation targeting Java EE (+org.apache.tamaya.ext:tamaya-injection-ee+) +* dynamic configuration and configuration updates (+org.apache.tamaya.ext:tamaya-events+) +* remote configuration (+org.apache.tamaya.ext:tamaya-etcd, org.apache.tamaya.ext:tamaya-consul, + org.apache.tamaya.ext:tamaya-hazelcast+) * and more For details about the extension modules available and their functionality refer to the link:extensions.html[extension user guide]. [[CorePropertyConverters]] -=== Default PropertyConverters in Core +=== Default PropertyConverters -As mentioned the Core module delivers several default +PropertyConverter+ instances out of the box. Find below the +The _Core_ module provides several +PropertyConverter+ implementations by default. Find below the listing of converters automatically registered with the Core module: [width="100%",frame="1",options="header",grid="all"] |======= -|_Target Type_ |_Class Name_ |_Supported Formats_ -|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF -|java.math.BigInteger |BigIntegerConverter |0xFF, 1234 -|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0 -|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123 -|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123 -|java.ui.lang.Class |ClassConverter |<fully qualified class name> -|java.util.Currency |CurrencyConverter |CHF, 123 -|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE -|_Enums_ |EnumConverter |<Enum item name> -|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE -|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE -|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String) -|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String) -|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)> -|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE -|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY -|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE -|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true -|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true -|ZoneId |ZoneIdConverter |Europe/Zurich +|_Target Type_ |_Class Name_ |_Supported Formats_ +|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF +|java.math.BigInteger |BigIntegerConverter |0xFF, 1234 +|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0 +|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123 +|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123 +|java.ui.lang.Class |ClassConverter |<fully qualified class name> +|java.util.Currency |CurrencyConverter |CHF, 123 +|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE +|_Enums_ |EnumConverter |<Enum item name> +|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE +|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE +|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String) +|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String) +|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)> +|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE +|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY +|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE +|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true +|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true +|ZoneId |ZoneIdConverter |Europe/Zurich |======= === Registering PropertyConverters -Additional +PropertyConverters+ can be implemented easily. It is recommended to register then using the +java.util.ServiceLoader+, -meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified -class names of the converters to be registered (one line per each). +Additional +PropertyConverters+ can be implemented easily. It is recommended to register them using +the +java.util.ServiceLoader+, meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified +class names of the converters to be registered (one line each). -Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters programmatically. - -NOTE: API Implementations can be read-only thus not allowing adding additional converters programmatically. +Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters +programmatically. [[ComponentLoadingAndPriorization]] === Component Loading and Priorization -Tamaya Core in general loads all components using the +java.util.ServiceLoader+ mechanism. This means that new components -must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing the fully qualified -implementation class names of the components to be registered (one line per each). -The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of components. Tamaya -core adds this functionality by the possibility to add +@Priority+ annotations to the components registered. -By default, and if no annotation is added +0+ is used as priority. Hereby higher values preceed lower values, meaning +Tamaya _Core_ in general loads all components by default using the +java.util.ServiceLoader+ mechanism. This means that new components +must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing the fully +qualified implementation class names of the components to be registered (one line per each). +The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of +components. Tamaya _Core_ adds such a functionality with the possibility to add +@Priority+ +annotations to the components registered. By default, and if no annotation is added +0+ is assumed +as priority. Hereby higher values preceed lower values, meaning -* if a singleton component is accessed from the current +ServiceContext+ the component with the higher value - effectively _overrides/replaces_ any component with lower values. -* if a collection of components is obtained from the +ServiceContext+ the components are ordered in order, where the - ones with higher priority are before components with lower priority. -* if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is - still defined and predictable in almost all scenarios. +* if a _singleton_ component is accessed from the current +ServiceContext+ the component with the + higher value effectively _overrides/replaces_ any component with lower values. +* if a _collection_ of components is obtained from the +ServiceContext+ the components are _ordered_ + based on their priorities, where the ones with higher priority are before components with lower + priority. +* if priorities _match_ Tamaya _Core_ additionally sorts them using the _simple class name_. + This ensures that ordering is still defined and predictable in all scenarios. -NOTE: Sorting the property sources based on their ordinal value is only the default ordering principle applied. By implementing - your own implementation of +ConfigurationProviderSpi+ you can apply a different logic: +NOTE: Sorting the property sources based on their ordinal value is only the default ordering + principle applied. By implementing your own implementation of +ConfigurationProviderSpi+ + you can apply a different logic: [[RegisteringPropertySources]] === Registering Property Sources -PropertySources that provide configuration properties are registered as ordinary components as described in the previous -section. Nevertheless the priority is not managed based on +@Priority+ annotations, but based on an explicit -+int getOrdinal()+ method. This allows to define the ordinal/priority of a +PropertySource+ explicitly. This is useful -due to several reasons: ++PropertySource+ implementations that provide configuration properties are registered as components as described in the previous +section. Hereby the precedence (ordering) of property sources is not hard-coded. Instead a +Comparator<PropertySource>+ +can be passed to a +ConfigurationContextBuilder+ to perform automatic ordering of the property sources +registered. The default implementation hereby implements the following logic: + +. It checks for an property entry +tamaya.ordinal+ if present the value is parsed into an +int+ value and used as + the ordinal val value. +. It checks for an explicit method +int getOrdinal()+, if found its value is taken as an ordinal. +. It checks for a +@Priority+ annotation, if present the priority value is used as an ordinal. +. If none of the above works, +0+ is assumed as ordinal value. +. If multiple +PropertySource+ instances share the same ordinal value, they are ordered based on their fully qualified + class names. + +Custom implementations of the property source comparator can be applied by calling ++ConfigurationContextBuilder.sortPropertySources(Comparator<PropertySource>)+. The default comparator can be replaced +by passing the fully qualified comparator class name as system property: -* it allows to define the ordinal as part of the configuration, thus allowing new overriding property sources being - added easily. -* it allows to define the ordinal dynamically, e.g. based on the configuration location, the time of loading or - whatever may be appropriate. ++-Dproperty-source-comparator=a.b.c.MyComparatorClass+ [[CorePropertySources]] @@ -191,23 +202,24 @@ public class MyPropertySource extends BasePropertySource{ } -------------------------------------------- -By default the ordinal of the property sources will be 1000, unless the key +tamaya.ordinal+ asdefined in -+PropertySource.TAMAYA_ORDINAL+ is present in the current +PropertySource+. Of course it is also possible to override -the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, or directly +int getOrdinal()+. +By default the ordinal of the property sources will be 1000, unless the key +tamaya.ordinal+ +as defined in +PropertySource.TAMAYA_ORDINAL+ is present in the current +PropertySource+. Of course +it is also possible to override the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, +or directly +int getOrdinal()+. [[CorePropertySourceProviders]] === Default PropertySourceProvider in Core With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also a default +PropertySourceProvider+ -present that loads all .properties files found at +META-INF/javaconfiguration.properties+ +present that loads all +.properties+ files found at +META-INF/javaconfiguration.properties+ and +META-INF/javaconfiguration.xml+. [[Extensions]] == Adding Extensions -The Core module only implements the link:api.html[API]. Many users require/wish additional functionality from a +Tamaya _Core_ only implements the link:api.html[API]. Many users require/wish additional functionality from a configuration system. Fortunately there are numerous extensions available that add further functionality. Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/4271e2a1/content/documentation/extensions.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc index 31af83e..0c643f1 100644 --- a/content/documentation/extensions.adoc +++ b/content/documentation/extensions.adoc @@ -13,23 +13,25 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati |======= |_Artifact_ |_Description_ |_Links_ | | N/A: currently no extensions have reached that maturity level. | - +|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation] +|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation] +|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. |link:extensions/mod_filter.html[Documentation] +|+org.apache.tamaya.ext:tamaya-features+ |Provides a simple feature check for loaded extensions. |link:extensions/mod_features.html[Documentation] |+org.apache.tamaya.ext:tamaya-formats+ |Provides an abstract model for configuration formats |link:extensions/mod_formats.html[Documentation] |+org.apache.tamaya.ext:tamaya-functions+ |Provides several functional extension points. |link:extensions/mod_functions.html[Documentation] -|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation] -|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation] -|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation] -|+org.apache.tamaya.ext:tamaya-events+ |Provides support for publishing configuration changes |link:extensions/mod_events.html[Documentation] -|+org.apache.tamaya.ext:tamaya-filter+ |Provides a programmatic filter for config entries. | link:extensions/mod_filter.html[Documentation] |+org.apache.tamaya.ext:tamaya-injection-api+ |Provides Tamaya's injection annotations API. |link:extensions/mod_injection.html[Documentation] |+org.apache.tamaya.ext:tamaya-injection+ |Provides configuration injection services and congiruation template support. |link:extensions/mod_injection.html[Documentation] |+org.apache.tamaya.ext:tamaya-injection-cdi+ | Java EE/standalone compliant CDI integration using CDI for injection. | link:extensions/mod_cdi.html[Documentation] |+org.apache.tamaya.ext:tamaya-injection-cdi-se+ | Java EE/standalone compliant CDI integration using Tamaya SE injection mechanism. | link:extensions/mod_cdi.html[Documentation] +|+org.apache.tamaya.ext:tamaya-jndi+ |Provides a JNDI based PropertySource. |link:extensions/mod_jndi.html[Documentation] +|+org.apache.tamaya.ext:tamaya-json+ |Provides format support for JSON based configuration. |link:extensions/mod_json.html[Documentation] |+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration |link:extensions/mod_mutable_config.html[Documentation] -|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.html[Documentation] +|+org.apache.tamaya.ext:tamaya-optional+ |Lets a Tamaya configuration to be used as an optional project extension only. |link:extensions/mod_optional.html[Documentation] +|+org.apache.tamaya.ext:tamaya-resolver+ |Provides placeholder and dynamic resolution functionality for configuration values. |link:extensions/mod_resolver.html[Documentation] |+org.apache.tamaya.ext:tamaya-resources+ |Provides ant-style resource path resolution |link:extensions/mod_resources.html[Documentation] -|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation] -|+org.apache.tamaya.ext:tamaya-collections+ |Collections support. |link:extensions/mod_collections.html[Documentation] +|+org.apache.tamaya.ext:tamaya-spi-support+ |Tamaya support module for SPI implementation. |link:extensions/mod_spi-support.html[Documentation] |+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:extensions/mod_spring.html[Documentation] +|+org.apache.tamaya.ext:tamaya-yaml+ |Support for using yaml as a configuration format. |link:extensions/mod_yaml.html[Documentation] |======= NOTE: The former Tamaya _Builder_ extension module has been removed. The corresponding methods were integrated into @@ -46,20 +48,20 @@ NOTE: All extensions currently run on Java 7 as well as on Java 8. [width="100%",frame="1",options="header",grid="all"] |======= |_Artifact_ |_Description_ |_Links_ +|+org.apache.tamaya.ext:tamaya-camel+ |Integration with Apache Camel. | link:extensions/mod_camel.html[Documentation] +|+org.apache.tamaya.ext:tamaya-classloader-support+ |Configuration services considering classloaderas. |link:extensions/mod_classloader_support.html[Documentation] |+org.apache.tamaya.ext:tamaya-commons+ |Integration Support for Apache Commons. | - +|+org.apache.tamaya.ext:tamaya-configured-sysprops+ | Tamaya configuration to be provided as +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation] +|+org.apache.tamaya.ext:tamaya-consul+ |Integration with consul clusters. | link:extensions/mod_consul.html[Documentation] +|+org.apache.tamaya.ext:tamaya-etcd+ |Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation] +|+org.apache.tamaya.ext:tamaya-hazelcast+ |Integration with Hazelcast datagrids. | link:extensions/mod_hazelcast.html[Documentation] |+org.apache.tamaya.ext:tamaya-jodatime+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation] -|+org.apache.tamaya.ext:tamaya-classloader-support+ |Configuration services considering classloaderas. |link:extensions/mod_classloader_support.html[Documentation] |+org.apache.tamaya.ext:tamaya-management+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation] |+org.apache.tamaya.ext:tamaya-metamodel+ |Provides an XML API for building configuration. |link:extensions/mod_metamodel-staged.html[Documentation] -|+org.apache.tamaya.ext:tamaya-validation+ |Provides an XML API for validating configuration. |link:extensions/mod_validation.html[Documentation] -|+org.apache.tamaya.ext:tamaya-usagetracker+ |Allows tracking of configuration usage. |link:extensions/mod_usagetracker.html[Documentation] -|+org.apache.tamaya.ext:tamaya-camel+ |Integration with Apache Camel. | link:extensions/mod_camel.html[Documentation] |+org.apache.tamaya.ext:tamaya-osgi+ |Integration with OSGI containers. | link:extensions/mod_osgi.html[Documentation] -|+org.apache.tamaya.ext:tamaya-consul+ |Integration with consul clusters. | link:extensions/mod_consul.html[Documentation] -|+org.apache.tamaya.ext:tamaya-etcd+ |Integration with etcd clusters. | link:extensions/mod_etcd.html[Documentation] -|+org.apache.tamaya.ext:tamaya-hazelcast+ |Integration with Hazelcast datagrids. | link:extensions/mod_hazelcast.html[Documentation] -|+org.apache.tamaya.ext:tamaya-configured-sysprops+ | Tamaya configuration to be provided as +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation] |+org.apache.tamaya.ext:tamaya-remote+ |Remote configuration support using the server API. |link:extensions/mod_remote.html[Documentation] |+org.apache.tamaya.ext:tamaya-server+ |Publishes configuration as a REST service. |link:extensions/mod_server.html[Documentation] |+org.apache.tamaya.ext:tamaya-ui+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.html[Documentation] +|+org.apache.tamaya.ext:tamaya-usagetracker+ |Allows tracking of configuration usage. |link:extensions/mod_usagetracker.html[Documentation] +|+org.apache.tamaya.ext:tamaya-validation+ |Provides an XML API for validating configuration. |link:extensions/mod_validation.html[Documentation] |======= http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/4271e2a1/content/documentation/extensions/mod_resources.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_resources.adoc b/content/documentation/extensions/mod_resources.adoc index 6c26cdd..cf25471 100644 --- a/content/documentation/extensions/mod_resources.adoc +++ b/content/documentation/extensions/mod_resources.adoc @@ -114,7 +114,7 @@ public class PathBasedPropertySourceProvider implements PropertySourceProvider { @Override public Collection<PropertySource> getPropertySources() { List<PropertySource> propertySources = new ArrayList<>(); - Collection<URL> resources = Resources.getResourceResolver().getResources("META-INF/cfg/**/*.properties"); + Collection<URL> resources = ConfigResources.getResourceResolver().getResources("META-INF/cfg/**/*.properties"); for(URL url:resources){ Properties props = new Properties(); try(InputStream is = url.openStream()){ http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/4271e2a1/content/documentation/extensions/mod_server.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/extensions/mod_server.adoc b/content/documentation/extensions/mod_server.adoc index 4c15704..cbf9a16 100644 --- a/content/documentation/extensions/mod_server.adoc +++ b/content/documentation/extensions/mod_server.adoc @@ -39,75 +39,54 @@ To benefit from configuration server support you only must add the corresponding === Providing configuration using the Tamaya Built-in Configuration Server -THe most simple way for providing onfiguration ist to start the internal server: +The most simple way for providing configuration is to start the internal server: [source, java] ----------------------------------------------- -Server server = org.apache.tamaya.server.ConfigServer.createServer(); -server.start(port); +// using context path: '/', port 8085 +org.apache.tamaya.server.Server.start(); + +// optionally pass the root context path and/or port: +// org.apache.tamaya.server.Server.start(8088); +// org.apache.tamaya.server.Server.start("/appconf", 7787); ----------------------------------------------- This will start a simple server instance that serves the following URL patterns: -* +GET /config+ provides access to the full configuration tree. -* +GET /config/filtered/${path}+ let you filter the configuration returned using regular expression (comma separated). - E.g. +/config/filtered/java,sun+ will return all configuration entries starting with _java_ and _sun_. +* +GET ${CONTEXT}/config+ provides access to the full configuration tree. +* +GET ${CONTEXT}/config/filtered/${path}+ let you filter the configuration returned using regular expression (comma separated). + E.g. +${CONTEXT}/config/filtered/java,sun+ will return all configuration entries starting with _java_ and _sun_. Additionally the server module has the following options implemented, which can be passed as additional, optional parameters: * +format+ allows to define the target format. By default the +ACCEPT+ header of the http request is checked, but this - setting can be explicitly controlled by passing tis parameter explicitly. The value is the expected MIME type to be - returned. By default the service supports the following types (refer to the SPI section later in this document for - options to adapt this): + setting can be explicitly controlled by passing this parameter explicitly. The value is the expected MIME type to be + returned. By default the service supports the following types: ** text/html ** text/plain ** application/xml - ** text/json - -* +scope,scopeId+ allows to use a server-side preconfigured filter/combination policy to be applied for - evaluating the entries to be returned. Hereby the +scopeId+ paramter allows to address a certain scope. - As an example think of a scope +?scope=CLIENT&scopeId=client1+ to be passed as request parameters. This - tells the server module to lookup a configured scope named 'CLIENT' and access a +ConfigOperator+ for the - given scopeId 'client1'. The returned operator then can filter and combine any kind of entries to the - required client configuration (for client1). Refer to the scopes section for more details. + ** application/json === Using the Configuration Servlets -Additionally to the fully built-in solution, it is also possible to integrate the Tamaya server module with a standard -Java EE servlet container. Tamaya provides 2 servlet implementations: - -* the servlet +org.apache.tamaya.server.FilteredConfigServlet+ can be used to register access to configurations - that also support filtering of the keys. The URL looks like - ----------------------------------------------------------- -http(s)://HOST/SERVLET_CONTEXT/PATHS?params - -where - HOST = host name incl port, e.g. 127.0.0.2:234 - SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered - PATHS = A comma separated number of key paths to be filtered for being returned, e.g. - java,sun,client - params = the optional parameters (scope, scopeId and format) ----------------------------------------------------------- - -* the servlet +org.apache.tamaya.server.FullConfigServlet+ can be used to register access to configurations - that alwyas returns all items known. The URL looks like +You can also register a servlet, e.g. as follows; ---------------------------------------------------------- -http(s)://HOST/SERVLET_CONTEXT?params - -where - HOST = host name incl port, e.g. 127.0.0.2:234 - SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered - params = the optional parameters (scope, scopeId and format) +<servlet> + <servlet-name>config-servlet</servlet-name> + <servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class> + <init-params> + <init-param key="javax.ws.rs.Application">org.apache.tamaya.server.Server$ResourceLoader</init-param> + </init-params> +</servlet> ---------------------------------------------------------- ==== Formatting used by Default -The server module formats the configuration returned by default in thw following variants: +The server module formats the configuration returned by default in the following variants: .Formatting for +text/json+ @@ -135,12 +114,12 @@ The server module formats the configuration returned by default in thw following "sun.jnu.encoding": "Cp1252", "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers", "sun.os.patch.level": "", - "{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" + "_class": "org.apache.tamaya.functions.FilteredConfiguration", + "_info.filter": "java.v,sun", + "_info.format": "application/json", + "_info.timestamp": "1441463200571", + "_timestamp": "1441463200571", + "_type": "Configuration" } ----------------------------------------------- @@ -171,12 +150,12 @@ The server module formats the configuration returned by default in thw following <entry key="sun.jnu.encoding">Cp1252</entry> <entry key="sun.management.compiler">HotSpot 64-Bit Tiered Compilers</entry> <entry key="sun.os.patch.level"></entry> - <entry key="{meta}class">org.apache.tamaya.functions.FilteredConfiguration</entry> - <entry key="{meta}info.filter">java.v,sun</entry> - <entry key="{meta}info.format">application/xml</entry> - <entry key="{meta}info.timestamp">1441463383687</entry> - <entry key="{meta}timestamp">1441463383687</entry> - <entry key="{meta}type">Configuration</entry> + <entry key="_class">org.apache.tamaya.functions.FilteredConfiguration</entry> + <entry key="_info.filter">java.v,sun</entry> + <entry key="_info.format">application/xml</entry> + <entry key="_info.timestamp">1441463383687</entry> + <entry key="_timestamp">1441463383687</entry> + <entry key="_type">Configuration</entry> </configuration> ----------------------------------------------- @@ -208,12 +187,12 @@ Configuration: sun.jnu.encoding: Cp1252, sun.management.compiler: HotSpot 64-Bit Tiered Compilers, sun.os.patch.level: , - {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 + _class: org.apache.tamaya.functions.FilteredConfiguration, + _info.filter: java.v,sun, + _info.format: text/plain, + _info.timestamp: 1441463082020, + _timestamp: 1441463082021, + _type: Configuration ----------------------------------------------- @@ -254,120 +233,10 @@ Configuration: _info.timestamp: 1441463459653, _timestamp: 1441463459654, _type: Configuration - </pre> </body> </html> ----------------------------------------------- -=== SPI -==== Scopes - -As mentioned earlier in this document scopes can be used to define the exact configuration tree to be returned, e.g. -as a result of combining multiple sub trees. Following an example of the code to be written to return a configuration -that combines common client default entries with client specific entries: -[source, java] ------------------------------------------------ -public class ClientScopeProvider implements ScopeProvider{ - - /** - * Access the unique scope name. - * @return the unique scope name. - */ - public String getScopeType(){ - return "CLIENT"; - } - - @Override - public ConfigOperator getScope(String scopeId) { - return c -> - ConfigurationFunctions.combine("Scoped Config CLIENT="+scopeId, - c.with(ConfigurationFunctions.sectionRecursive(true, "client.default")), - c.with(ConfigurationFunctions.sectionRecursive(true, "client." + scopeId)) - ); - } -} ------------------------------------------------ - -This class can be registered using the +ServiceContext+ in place. By default the +ServiceLoader+ is used, so you will -have to add the following to +META-INF/services/org.apache.tamaya.server.spi.ScopeProvider+: - -[source, listing] ------------------------------------------------ -my.full.packagename.ClientScopeProvider ------------------------------------------------ - - -==== Adapting the Way Configuration is Derived - -Finally the effective reading and configuration handling logic can also be replaced or improved. This can be -done by registering your own implementation of the interface +ConfigProviderService+: - -[source, java] ------------------------------------------------- -public interface ConfigProviderService { - String getConfigurationWithPath(String path, String format, String scope, String scopeId, HttpServletRequest request); - String getConfiguration(String format, String scope, String scopeId, HttpServletRequest request); - void updateConfiguration(String payload, HttpServletRequest request); - void deleteConfiguration(String paths, HttpServletRequest request); -} ------------------------------------------------- - -By default the +ServiceContextManager+ uses the +java.util.ServiceLoader+ for component loading, so to replace the -default server code you must register a higher +@Priority+ implementation. - - -==== Replacing the Built-In Server - -We have seen earlier that starting a configuration server is pretty easy: - -[source, java] ------------------------------------------------ -Server server = org.apache.tamaya.server.ConfigServer.createServer(); -server.start(port); ------------------------------------------------ - -Nevertheless one may want to replace the used implementation of +Server+. This can be done easily by simply -registering an overriding implementation if the corresponding interface: - -[source, java] ------------------------------------------------ -public interface Server { - void start(int port); - boolean isStarted(); - void stop(); - void destroy(); -} ------------------------------------------------ - - -==== The ScopeManager Singleton - -Finally whe implementing your own server, you might also benefit from the +ScopeManager+ singleton. Basically this -class loads all registered +ScopeProvider+ and manages the configured scope instances: - -[source, java] ------------------------------------------------ -public final class ScopeManager { - ... - - private ScopeManager(){} - - /** - * Get the scope given its name. - * @param scopeId the scope name - * @return the scope matching - * @throws ConfigException, if nos such scope is defined. - */ - public static ConfigOperator getScope(String scopeId, String target); - - /** - * Get the defined scope names. - * @return the defined scope names, never null. - */ - public static Set<String> getScopes(); - -} ------------------------------------------------ http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/4271e2a1/content/documentation/quickstart.adoc ---------------------------------------------------------------------- diff --git a/content/documentation/quickstart.adoc b/content/documentation/quickstart.adoc index 14ab438..8648e74 100644 --- a/content/documentation/quickstart.adoc +++ b/content/documentation/quickstart.adoc @@ -5,9 +5,10 @@ The fastest way to start with Tamaya is just using the _Core_ implementation, -implementing the **API** in small, minimalistic way. For that add the following +implementing the **API** in a minimalistic way. For that add the following Maven dependency to your project: +=== Adding the Tamaya Dependency [source,xml,subs="verbatim,attributes"] ---- @@ -18,65 +19,106 @@ Maven dependency to your project: </dependency> ---- -Given that you can add your configuration properties to the following locations in your classpath: +=== Start Coding + +In your Java code you can directly access configuration from the API. In most cases it is recommended +to provide the default values when accessing the configuration: + +[source,java] +---- +Configuration config = ConfigurationProvider.getConfiguration(); + +String aTextValue = config.getOrDefault("my.value.key", "N/A"); +int aNumericValue = config.getOrDefault("my.numValueKey", Integer.class, 15 /* default */); +BigDecimal bdValue = config.getOrDefault("my.BD.value", BigDecimal.class, BigDecimal.valueOf(120)); +---- + +With Java 8 you can, of course, also use +Optional+, e.g. + +[source,java] +---- +Configuration config = ConfigurationProvider.getConfiguration(); + +String aTextValue = Optional.ofNullable(config.getOrDefault("my.value.key").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: [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): +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 . `META-INF/javaconfiguration.properties` -There many modules that extend the capabilities of Tamaya. -These modules doe not depend on core, so alternative -implementations of the Tamaya API should work similarly. +== Advanced Topics === Multiple configuration files By default you can provide multiple `javaconfig.properties` files, e.g. as part -of multiple jars loaded into your system. The system internally creates one +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 ordinal value (an int). +instances created are ordered by their precedence. + +By default the precendence of a +PropertySource+ is evaluated based on an _ordinal_ value +calculated as follows: -Tamaya Core defines the following default ordinals (used, if no custom ordinal is defined): +. the systems checks for a `tamaya.ordinal` configuration value and tries to convert to + an `int` ordinal value. +. the systems checks if the property source has a method +int getOrdinal()+. If present + the result is used as ordinal. +. the systems checks if the property source has a `@Priority` annotation and uses the + annotation's value as ordinal. +. if all of the above fails, +0+ is assumed as ordinal. + +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: [width=70] [cols="3,1", option="headers"] |=== -| Source | Ordinal -| System Properties | 400 -| Environment Variables | 300 -| Java Configuration Properties | 100 +| Source | Ordinal +| System Properties | 400 +| Environment Properties | 300 +| Properties from `META-INF/javaconfiguration.properties` | 100 |=== That means that the value of a configuration variable `x` overhanded via `-Dx=yes` has -a higher precedence then the entry for configuration variable `x` specified in a `javaconfig.properties` -as `x=no`. +a higher precedence then the entry for configuration variable `x` specified in +`META-INF/javaconfig.properties` as `x=no`. These ordinal values can be either hardcoded, or be dynamically configurable as key within each configuration resource. The ladder can be done by defining a special Tamaya ordinal value as follows: - [source] ---- # override default Tamaya ordinal for property files tamaya.ordinal=123 ---- -This assigns an ordinal of 123 to each entry in that configuration resource. +This assigns an ordinal of 123 to each entry in that property source providing this configuration +properties. === Using additional features of Tamaya There many modules that extend the capabilities of Tamaya. These modules doe not depend on core, so alternative implementations of the Tamaya API should work similarly. Following a -small extract of most important modules available (or available soon): +small extract of most important modules available (or available soon). +Refer to link:extensions/extensions.html[this list] for a complete +overview. ==== Dynamic Resolution and Value Placeholders @@ -89,7 +131,7 @@ small extract of most important modules available (or available soon): </dependency> ---- -// @todo Auf Modulliste verweisen für vollständigen Ãberblick + With that it is possible to define values with Unix styled placeholders that are resolved on configuration access, e.g. `mykey=my${dynamicValue}´. For further details refer to the module documentation. @@ -145,7 +187,7 @@ Corresponding configuration: [source,xml,subs="verbatim,attributes"] ---- public class MyType { - @ConfiguredProperty("name") + @Config("my.key") private String typeName; public String getName() { @@ -162,7 +204,7 @@ Or the same as template: [source,xml,subs="verbatim,attributes"] ---- public interface MyTypeTemplate { - @ConfiguredProperty("name") + @Config("my.key") public String getName(); }
