content/documentation/extensions/mod_hazelcast.adoc

: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 8.


=== Installation

To use _tamaya-hazelcast_ you only must add the corresponding dependency to your module:

[source, xml, subs=attributes+]
-----------------------------------------------
<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. It provides:

* a Hazelcast based property source implementation.
* configurable caching of key/values.
* configuraing a dedicated Hazelcast map ID to be used.

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 backend configuration
can be easily created as illustrated 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
ConfigurationBuilder b = Configuration.createConfigurationBuilder();
b.addDefaultPropertyConverters().addDefaultPropertyFilter().addDefaultPropertySources();
// Add the hazelcast property source (as most significant)
b.addPropertySource(ps);
// build and use the configuration
Configuration config = b.build();
-----------------------------------------------


=== The AbstractHazelcastPropertySource

The +AbstractHazelcastPropertySource+ is the baseclass used by +HazelcastPropertySource+. Use it to implement your own
Hazelcast based property source.