content/documentation/extensions/mod_hocon.adoc

:jbake-type: page
:jbake-status: published

= Apache Tamaya - Extension: HOCON Format

toc::[]


[[JSON]]
== Tamaya HOCON (Extension Module)
Tamaya _HOCON_ is an extension module. Refer also to the link:../extensions.html[extensions documentation] for further details.

=== What functionality does this module provide?

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 above 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 HOCON extension module you only must add the corresponding dependency to your module:

[source, xml, subs=attributes+]
-----------------------------------------------
<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"));
-----------------------------------------------