content/documentation/extensions/mod_yaml.adoc

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

= Apache Tamaya - Extension: Builder

toc::[]


[[YAML]]
== Tamaya YAML (Extension Module)

Tamaya _YAML_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.


=== Overview

Tamaya _YAML_ provides support for reading configuration using the YAML format (yaml.org). YAML hereby
use intendation for expressing hierarchy, which makes yaml configuration files very easily readable and compact.


=== Compatibility

The YAML module is based on Java 8.


=== Installation

To use YAML as configuration format you must add the corresponding dependency to your module:

[source, xml, subs=attributes+]
-----------------------------------------------
<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-yaml</artifactId>
  <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------

This extension also transitively requires the +tamaya.formats+ module.


=== Reading configuration in YAML

For reading YAML based onfiguration most easily a +YAMLFormat+ can be provided:

[source, java]
-----------------------------------------------
PropertySource ps = ConfigurationFormats.getInstance().createPropertySource(
    getClassLoader().getResource("myFileConfig.yaml"), new YAMLFormat()));
-----------------------------------------------


=== Examples

The YAML module adds instances of +ConfigurationFormat+ so YAML configuration can be read and mapped to the
according property values. E.g. the following file is a simple and correct YAML configuration:

[source,yaml]
----------------------------------------------------------------
invoice: 34843
date   : 2001-01-23
bill-to: &id001
    given  : Chris
    family : Dumars
    address:
        lines: |
            458 Walkman Dr.
            Suite #292
        city    : Royal Oak
        state   : MI
        postal  : 48046
ship-to: *id001
product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00
    - sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00
tax  : 251.42
total: 4443.52
comments:
    Late afternoon is best.
    Backup contact is Nancy
    Billsmer @ 338-4338.
----------------------------------------------------------------

Hereby the above file, by default is mapped as follows into +Map<String,String>+ typed properties:

[source,listing]
----------------------------------------------------------------
invoice -> 34843
date -> Tue Jan 23 01:00:00 CET 2001
bill-to.family -> Dumars
bill-to.given -> Chris
bill-to.address.state -> MI
bill-to.address.postal -> 48046
bill-to.address.city -> Royal Oak
bill-to.address.lines -> 458 Walkman Dr.
Suite #292

ship-to.given -> Chris
ship-to.address.state -> MI
ship-to.family -> Dumars
ship-to.address.postal -> 48046
ship-to.address.city -> Royal Oak
ship-to.address.lines -> 458 Walkman Dr.
Suite #292

product -> {sku=BL394D, quantity=4, description=Basketball, price=450.0},{sku=BL4438H, quantity=1, description=Super Hoop, price=2392.0}
_product.collection-type -> List

tax -> 251.42
total -> 4443.52
comments -> Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
----------------------------------------------------------------