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 <[email protected]> Authored: Sun Feb 26 22:53:39 2017 +0100 Committer: anatole <[email protected]> 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(); +----------------------------------------------- +
