[4/4] incubator-tamaya-site git commit: TAMAYA-195: Added initial docs.

[an...@apache.org]

TAMAYA-195: Added initial 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/98574522
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/98574522
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/98574522

Branch: refs/heads/master
Commit: 98574522d066da525a85190476d5a94cb6066ccd
Parents: 9aaf034
Author: anatole <an...@apache.org>
Authored: Sun Feb 26 22:53:39 2017 +0100
Committer: anatole <an...@apache.org>
Committed: Sun Feb 26 22:53:39 2017 +0100

----------------------------------------------------------------------
 .../documentation/extensions/mod_hazelcast.adoc | 120 +++++++++++++++++++
 1 file changed, 120 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/98574522/content/documentation/extensions/mod_hazelcast.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_hazelcast.adoc b/content/documentation/extensions/mod_hazelcast.adoc
new file mode 100644
index 0000000..13c2d6f
--- /dev/null
+++ b/content/documentation/extensions/mod_hazelcast.adoc
@@ -0,0 +1,120 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya -- Extension: Integration with Hazelcast
+
+toc::[]
+
+
+[[Consul]]
+== Integration with Hazelcast (Extension Module)
+
+Tamaya _Hazelcast_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
+
+
+=== What functionality this module provides ?
+
+Tamaya _Hazelcast_ provides a property source which uses
+link:http://www.hazelcast.org[Hazelcast] as configuration backend. Hereby the
+module supports read-only integration (as a +HazelcastPropertySource+ as well
+as a writing configuration changes back (based on Tamaya's +MutableConfiguration+ API
+defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension module.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will not run on Java 7 and beyond.
+
+
+=== Installation
+
+To use _tamaya-hazelcast_ you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+  <groupId>org.apache.tamaya.ext</groupId>
+  <artifactId>tamaya-hazelcast</artifactId>
+  <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+Hazelcast integration comes basically with 2 artifacts:
+
+* The +org.apache.tamaya.hazelcast.HazelcastPropertySource+ is a +PropertySource+. The property source is not automatically
+  registered. Either register it using the _ServiceLoader_ yourself or implement
+  and register a corresponding `PropertySourceProvider`.
+* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
+  by accessing a +MutableConfiguration+ using the URI +config:hazelcast+.
+
+Access of consul key/value pairs is through the normal Tamaya API.
+
+
+=== The HazelcastPropertySource
+
+The +HazelcastPropertySource+ is not automatically registered and provides different options how to integrate
+Tamaya with Hazelcast.
+
+[source, java]
+-----------------------------------------------
+/**
+ * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and
+ * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}.
+ */
+public HazelcastPropertySource();
+
+/**
+ * Creates a new instance, hereby using {@code "Hazelcast"} as property source name and the
+ * given hazelcast instance.
+ * @param hazelcastInstance the hazelcast instance, not null.
+ */
+public HazelcastPropertySource(HazelcastInstance hazelcastInstance);
+
+/**
+ * Creates a new instance, hereby using the given property source name and
+ * a default hazelcast backend created by calling {@link Hazelcast#newHazelcastInstance()}.
+ * @param name the property source name, not null.
+ */
+public HazelcastPropertySource(String name);
+
+/**
+ * Creates a new instance, hereby using the given property source name and
+ * a creating a new hazelcast backend using the given Hazelcast {@link Config}.
+ * @param config the hazelcast config, not null.
+ * @param name the property source name, not null.
+ */
+public HazelcastPropertySource(String name, Config config);
+
+/**
+ * Creates a new instance, hereby using the given property source name and the
+ * hazelcast instance.
+ * @param name
+ * @param hazelcastInstance
+ */
+public HazelcastPropertySource(String name, HazelcastInstance hazelcastInstance);
+-----------------------------------------------
+
+To use hazelcast as a configuration backend, you simply create the corresponding Hazelcast instance
+and use it to initialize the Tamaya property source. Given that a hazelcast backedn configuration
+can be easily created asillustrated below:
+
+[source, java]
+-----------------------------------------------
+Config hazelcastConfig = new Config();
+// define config settings
+HazelcastInstance hazelcastInstance = Hazelcast.newInstance(hazelcastConfig);
+HazelcastPropertySource ps = new HazelcastPropertySource(hazelcastInstance);
+ps.setName("myHazelcast-config");
+ps.setOrdinal(2000);
+// Build your own configuration context
+ConfigurationContextBuilder b = ConfigurationProvider.createNewConfigurationContextBuilder();
+b.addDefaultPropertyConverters().addDefaultPropertyFilter().addDefaultPropertySources();
+// Add the hazelcast property source (as most significant)
+b.addPropertySource(ps);
+// build and use the configuration
+Configuration config = b.build();
+-----------------------------------------------
+