Merge branch 'master' of https://gitbox.apache.org/repos/asf/incubator-tamaya-site
diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc
index 3186910..e065308 100644
--- a/content/documentation/extensions.adoc
+++ b/content/documentation/extensions.adoc
@@ -21,6 +21,8 @@
|+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-hazelcast+ |Integration with Hazelcast datagrids. |link:extensions/mod_hazelcast.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-hocon+ |Provides format support for HOCON based configuration. |link:extensions/mod_hocon.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-hjson+ |Provides format support for HJSON based configuration. |link:extensions/mod_hjson.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 configuration 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]
@@ -46,18 +48,20 @@
[width="100%",frame="1",options="header",grid="all"]
|=======
-|_Artifact_ |_Description_ |_Links_
-|+org.apache.tamaya.ext:tamaya-camel_beta+ |Integration with Apache Camel. | link:extensions/mod_camel.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-commons_beta+ |Integration Support for Apache Commons. | -
-|+org.apache.tamaya.ext:tamaya-configured-sysprops_beta+ | Tamaya configuration to be provided as +System.getProperties()+. | link:extensions/mod_sysprops.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-jodatime_beta+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-management_alpha+ |Provides JMX support for inspecting configuration. |link:extensions/mod_management.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-metamodel_alpha+ |Provides an XML API for building configuration. |link:extensions/mod_metamodel-staged.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-remote_alpha+ |Remote configuration support using the server API. |link:extensions/mod_remote.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-server_alpha+ |Publishes configuration as a REST service. |link:extensions/mod_server.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-ui_alpha+ |Provides a web UI for a VM running Tamaya. |link:extensions/mod_ui.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-uom_beta+ |Provides additional converters based on the Units of Measurement JSR. |link:extensions/mod_uom.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-usagetracker_beta+ |Allows tracking of configuration usage. |link:extensions/mod_usagetracker.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-validation-alpha+ |Provides an XML API for validating configuration. |link:extensions/mod_validation.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-vertx-alpha+ |Provides Vertx integration. |link:extensions/mod_vertx.html[Documentation]
+|_Artifact_ |_Description_ |_Links (if available)_
+|+org.apache.tamaya.ext:tamaya-camel_beta+ |Integration with Apache Camel. | link:extensions/mod_camel.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-commons-config_beta+ |Integration Support for Apache Commons. | -
+|+org.apache.tamaya.ext:tamaya-doc_alpha+ |Provides support for generating Configuration Documentation. | -
+|+org.apache.tamaya.ext:tamaya-jodatime_beta+ |Provides support for JodaTime. | link:extensions/mod_jodatime.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-jsr382+ |Implementation of the current JSR 382 API. | - (Checkout the JSR's documentation)
+|+org.apache.tamaya.ext:tamaya-management_alpha+ |Provides JMX support for inspecting configuration. | link:extensions/mod_management.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-metamodel_alpha+ |Provides an XML API for building configuration. | link:extensions/mod_metamodel-staged.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-propertysources+ |Provides different property source base classes. | -
+|+org.apache.tamaya.ext:tamaya-remote_alpha+ |Remote configuration support using the server API. | link:extensions/mod_remote.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-server_alpha+ |Publishes configuration as a REST service. | link:extensions/mod_server.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-ui_alpha+ |Provides a web UI for a VM running Tamaya. | link:extensions/mod_ui.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-uom_beta+ |Provides additional converters based on the Units of Measurement JSR. | link:extensions/mod_uom.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-usagetracker_beta+ |Allows tracking of configuration usage. | link:extensions/mod_usagetracker.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-validation-alpha+ |Provides an XML API for validating configuration. | link:extensions/mod_validation.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-vertx-alpha+ |Provides Vertx integration. | link:extensions/mod_vertx.html[Documentation]
|=======
diff --git a/content/documentation/extensions/mod_hjson.adoc b/content/documentation/extensions/mod_hjson.adoc
new file mode 100644
index 0000000..6ff79ce
--- /dev/null
+++ b/content/documentation/extensions/mod_hjson.adoc
@@ -0,0 +1,85 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya - Extension: HJSON Format
+
+toc::[]
+
+
+[[HJSON]]
+== Tamaya HJSON (Extension Module)
+Tamaya _HJSON_ is an extension module. Refer also to the link:../extensions.html[extensions documentation] for further details.
+
+=== What functionality this module provides ?
+
+Tamaya _HJSON_ provides support for reading configuration in HJSON, a JSP similar format better
+suited for humans:
+
+[source, hjson]
+-----------------------------------------------
+{
+ a : A
+ b : {
+ o : O
+ p : P
+ }
+ c : C
+}
+-----------------------------------------------
+
+Hereby the hierarchical structure of the JSON document will be mapped to a
+corresponding `PropertyValue` tree structure. This strucuture can be mapped
+to flat key-value pairs of type `String`, e.g. the bove will be mapped to
+
+[source, properties]
+-----------------------------------------------
+a=A
+b.o=O
+b.p=P
+c=C
+-----------------------------------------------
+
+This extension implements the SPI defined by the +tamaya.formats+ extension module.
+
+
+=== Compatibility
+
+The module is based on Java 8.
+
+
+=== Installation
+
+To use the HJSON extension module you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-hjson</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+This extension also transitively requires the +tamaya.formats+ module.
+
+
+=== Reading configuration in HJSON
+
+For reading HJSON based onfiguration most easily a +HJSONFormat+ can be
+used:
+
+[source, java]
+-----------------------------------------------
+ConfigurationData dataRead = ConfigurationFormats.getInstance().readConfig(
+ getClassLoader().getResource("myFileConfig.json"), new HJSONFormat()));
+-----------------------------------------------
+
+Or, if you are fine with the _default_ mapping you can directly create a
++PropertySource+ using the _formats_ API (this works since this module
+registers the _json_ format automatically using the `ServiceContext`):
+
+[source, java]
+-----------------------------------------------
+PropertySource ps = ConfigurationFormats.getInstance().createPropertySource(
+ getClassLoader().getResource("myFileConfig.hjson"));
+-----------------------------------------------
diff --git a/content/documentation/extensions/mod_hocon.adoc b/content/documentation/extensions/mod_hocon.adoc
new file mode 100644
index 0000000..15aa87e
--- /dev/null
+++ b/content/documentation/extensions/mod_hocon.adoc
@@ -0,0 +1,85 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya - Extension: HOCON Format
+
+toc::[]
+
+
+[[JSON]]
+== Tamaya JSON (Extension Module)
+Tamaya _JSON_ is an extension module. Refer also to the link:../extensions.html[extensions documentation] for further details.
+
+=== What functionality this module provides ?
+
+Tamaya _HOCON_ provides support for reading configuration using Human Optimized Configuration) HOCON
+format as defined by http://https://lightbend.github.io/config/[Lightbend Typesafe Config]:
+
+[source, hcon]
+-----------------------------------------------
+{
+ a : A
+ b : B
+ c {
+ o: O
+ p: P
+ }
+}
+-----------------------------------------------
+
+Hereby the hierarchical structure of the HOCON document will be mapped
+into an according `PropertyValue` tree structure. By default this structure can be
+mapped to flat key-value pairs of type `String`, e.g. the bove will be mapped to
+
+[source, properties]
+-----------------------------------------------
+a=A
+b=B
+c.o=O
+c.p=P
+-----------------------------------------------
+
+This extension implements the SPI defined by the +tamaya.formats+ extension module.
+
+
+=== Compatibility
+
+The module is based on Java 8.
+
+
+=== Installation
+
+To use the JSON extension module you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-hocon</artifactId>
+ <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+This extension also transitively requires the +tamaya.formats+ module.
+
+
+=== Reading configuration in HOCON
+
+For reading HOCON based onfiguration most easily a +HOCONFormat+ can be
+used:
+
+[source, java]
+-----------------------------------------------
+ConfigurationData dataRead = ConfigurationFormats.getInstance().readConfig(
+ getClassLoader().getResource("myFileConfig.hocon"), new HOCONFormat()));
+-----------------------------------------------
+
+Or, if you are fine with the _default_ mapping you can directly create a
++PropertySource+ using the _formats_ API (this works since this module
+registers the _hocon_ format automatically in the `ServiceContext`):
+
+[source, java]
+-----------------------------------------------
+PropertySource ps = ConfigurationFormats.getInstance().createPropertySource(
+ getClassLoader().getResource("myFileConfig.hocon"));
+-----------------------------------------------
diff --git a/content/documentation/extensions/mod_json.adoc b/content/documentation/extensions/mod_json.adoc
index a7bb7e5..adb2ecb 100644
--- a/content/documentation/extensions/mod_json.adoc
+++ b/content/documentation/extensions/mod_json.adoc
@@ -1,19 +1,18 @@
:jbake-type: page
:jbake-status: published
-= Apache Tamaya - Extension: Builder
+= Apache Tamaya - Extension: JSON Format
toc::[]
[[JSON]]
== Tamaya JSON (Extension Module)
-Tamaya _JSON_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
+Tamaya _JSON_ is an extension module. Refer also to the link:../extensions.html[extensions documentation] for further details.
=== What functionality this module provides ?
-Tamaya _JSON_ provides support for reading configuration using JSON
-format:
+Tamaya _JSON_ provides support for reading configuration in JSON (Java Serializued Object Notation):
[source, json]
-----------------------------------------------
@@ -26,7 +25,8 @@
-----------------------------------------------
Hereby the hierarchical structure of the JSON document will be mapped to a
-flat key-value pairs of type `String`, e.g. the bove will be mapped to
+corresponding `PropertyValue` tree structure. This strucuture can be mapped
+to flat key-value pairs of type `String`, e.g. the bove will be mapped to
[source, properties]
-----------------------------------------------
@@ -34,7 +34,7 @@
a.b.key2=true
-----------------------------------------------
-This extension uses SPI defined by the +tamaya.formats+ extension module.
+This extension implements the SPI defined by the +tamaya.formats+ extension module.
=== Compatibility
diff --git a/content/documentation/extensions/mod_spring.adoc b/content/documentation/extensions/mod_spring.adoc
index c429012..d95eb0d 100644
--- a/content/documentation/extensions/mod_spring.adoc
+++ b/content/documentation/extensions/mod_spring.adoc
@@ -14,15 +14,11 @@
=== What functionality this module provides ?
-Tamaya _Spring_ currently provides full integration with Spring and Spring Boot:
+Tamaya _Spring_ allows to use Tamaya as a configuration backend for Spring or Spring Boot:
-* A Spring +@Configuration+ implementation that also provides a Tamaya based version of
- +org.springframework.context.support.PropertySourcesPlaceholderConfigurer+.
-* +org.apache.tamaya.integration.spring.TamayaEnvironment+ is the Tamaya based implementation of the Spring
- +Environment+ interface.
-* +TamayaSpringPropertySource+ implements an additional Spring +PropertySource+.
+* Tamaya is added via a +TamayaSpringPropertySource+ as an additional Spring +PropertySource+.
* Finally +org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor+ implements a Bean +PostProcessor+,
- which adds all the fully fledged Tamaya configuration capabilities to Spring.
+ which adds all the fully fledged Tamaya configuration injection capabilities to Spring.
=== Compatibility
@@ -45,15 +41,15 @@
-----------------------------------------------
-=== Registering Tamaya Spring Configuration
+=== Configuring Tamaya Spring Configuration
-Basically to activate the Tamaya Spring support the most simple thing is to a enable the Tamaya package for being
-scanned for Spring components, e.g. using by annotation:
+Tamaya leverages standard Spring functionality of Spring. To activate and configure Tamaya just add the
+corresponding Tamaya annotation to your Spring Configuration:
[source, java]
--------------------------------------------------------
@SpringBootApplication
-@ComponentScan({"org.apache.tamaya.integration.spring"})
+@EnableTamayaConfig
public class SampleWebFreeMarkerApplication {
public static void main(String[] args) throws Exception {
@@ -63,54 +59,27 @@
}
--------------------------------------------------------
-Of course, you can still use Spring's XML configuration in a similar way:
-[source, xml]
+
+=== Extending or Overriding existing Spring Configuration
+
+By default Tamaya is overriding any existing Spring configuration. But you can also configure Tamaya to extend
+Spring configuration only as follows:
+
+[source, java]
--------------------------------------------------------
-<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:context="http://www.springframework.org/schema/context"
- xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">
-
- <context:annotation-config />
- <context:component-scan base-package="org.apache.tamaya.integration.spring"/>
-
- ...
-
-</beans>
---------------------------------------------------------
-
-
-Though not recommended you can explicitly register the Tamaya related beans in your context configuration by hand:
-files:
-
-[source, xml]
---------------------------------------------------------
-<bean id="tamayaInjectionProcessor" name="tamayaInjectionProcessor" class="org.apache.tamaya.integration.spring.SpringConfigInjectionPostProcessor"/>
-<bean id="tamayaConfigProvider" name="tamayaConfigProvider" class="org.apache.tamaya.integration.spring.TamayaSpringConfig"/>
---------------------------------------------------------
-
-
-=== Configuring your Context
-
-After activation you can use Tamaya as a backend for property resolution, e.g. +propertyValue+
-is resolved from the current Tamaya configuration. See example below:
-
-[source, xml]
---------------------------------------------------------
-<bean id="configuredBean" name="configuredBean" class="org.apache.tamaya.integration.spring.ConfiguredSpringBean">
- <property name="message" value="${propertyValue}"/>
-</bean>
+@EnableTamayaConfig(extendOnly=true)
--------------------------------------------------------
=== Configuring your Beans
-Similarly you can inject any kind of configuration as supported by Tamaya into your Spring managed beans:
+Similarly you can inject any kind of configuration as supported by Tamaya into your Spring managed beans.
+Hereby both, Spring injection and Tamaya injection mechanisms are supported:
[source, java]
--------------------------------------------------------
-@ConfigDefaultSections("app.root") // optional <1>
+@ConfigSection("app.root") // optional <1>
@Component
public class ConfiguredSpringBean {
@@ -150,27 +119,16 @@
Summarizing you get all the nice features of Tamaya out of the box running
with your Spring code.
-=== Working with Dynamic Values
-
-Integration into Spring also includes for support for _dynamic values_:
-
-[source, java]
---------------------------------------------------------
-@Config(value = "foreground.color", required = false, defaultValue = "#DDDDDD")
-private DynamicValue<Color> foregroundColor;
---------------------------------------------------------
-
-Dynamic values are a very flexible mechanism for managing configuration changes.
-You can even use an update policy to define how you want to handle configuration
-changes for your configuration parameter:
-
-[source, java]
---------------------------------------------------------
-foregroundColor.setUpdatePolicy(UpdatePolicy.IMMEDEATE);
-foregroundColor.addPropertyChangeListener(() -> {
- System.out.println("New forground color: " + foregroundColor.get();
-});
---------------------------------------------------------
-
-IMPORTANT: For a full description of Tamaya's injection API please
+NOTE: For a full description of Tamaya's injection API please
refer to the link:extensions/mod_injection.html[corresponding documentation].
+
+
+=== Disabling Tamaya Injection
+
+If you dont like Tamaya injection, you can simply disable it:
+
+[source, java]
+--------------------------------------------------------
+@EnableTamayaConfig(disableTamayaInjection=true)
+--------------------------------------------------------
+
diff --git a/content/tamayaasastandard.adoc b/content/tamayaasastandard.adoc
new file mode 100644
index 0000000..8d6a3a8
--- /dev/null
+++ b/content/tamayaasastandard.adoc
@@ -0,0 +1,74 @@
+:jbake-type: page
+:jbake-status: published
+
+= Tamaya as a Standard
+
+Apache Tamaya (incubating) actually supports several configuration standards to
+provide a long term stable configuration solution.
+
+
+== JSR 382
+
+Tamaya implements a recent state of the Configuration JSR. The exact commit
+version of the JSR API implemented (the JSR has not yet released any version
+as of now) can be evaluated looing at the _tamaya-jsr382_ `pom.xml` in the
+sandbox repository.
+
+To use Tamaya aS a JSR-382 Configuration provider you must add the following
+dependency:
+
+[source,xml]
+---------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-jsr382</artifactId>
+ <version>${tamaya.version}</version>
+</dependency>
+---------
+
+Since this component is not yet officially released you must use the current snapshot
+version +0.4-incubating-SNAPSHOT+. You also must add the Apache Snapshot
+Repository to your build:
+
+[source,xml]
+---------
+<repository>
+ <id>apache.snapshots</id>
+ <name>Apache Development Snapshot Repository</name>
+ <url>https://repository.apache.org/content/repositories/snapshots/</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+</repository>
+---------
+
+
+== Microprofile
+
+Tamaya implements the Microprofile Configuration API Version 1.1. To use Tamaya
+as a Micropropfile Configuration provider you must add the following dependency:
+
+[source,xml]
+---------
+<dependency>
+ <groupId>org.apache.tamaya.ext</groupId>
+ <artifactId>tamaya-microprofile</artifactId>
+ <version>${tamaya.version}</version>
+</dependency>
+---------
+
+
+== OSGI ConfigAdmin
+
+Tamaya's OSGI Support leverages the OSGI +org.osgi.service.cm.ConfigurationAdmin+
+configuration manager as defined in OSGI Compendiumn Version +4.3.1+. Hereby
+Tamaya can add or modify Configuration in OSGI, which may trigger change events.
+The exact behaviour can be controlled in many ways. By default Tamaya, does not change
+anything, when deployed in OSGI, without being configured todo so. For details
+check link:documentation/extensions/mod_osgi.html[Tamaya's OSGI Documentation].
+
+
+
