content/extensions/mod_yaml.adoc

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

= Apache Tamaya -- Extension: Builder

toc::[]


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

The Tamaya YAML module 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 7, so it will run on Java 7 and beyond.


=== Installation

To benefit from configuration builder support you only must add the corresponding dependency to your module:

[source, xml]
-----------------------------------------------
<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]
-----------------------------------------------
ConfigurationData dataRead = ConfigurationFormats.readConfig(
    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.
----------------------------------------------------------------