Apache Tamaya — Extension: Formats

ConfigurationData

Configuration formats can be very different. Some are simpley key/value pairs, whereas other also consist of multiple sections (e.g. ini-files) or hierarchical data (e.g. yaml, xml). This is solved in Tamaya by mapping the configuration read into a normalized intermediary format called ConfigurationData:

public final class ConfigurationData {

    public ConfigurationFormat getFormat();
    public String getResource();

    public Set<String> getSectionNames();
    public Map<String,String> getSection(String name);
    public Map<String,Map<String,String>> getSections();

    public boolean hasDefaultProperties();
    public Map<String,String> getDefaultProperties();

    public Map<String,String> getCombinedProperties();
    public boolean hasCombinedProperties();

    public boolean isEmpty();
}

In detail the data read from a file is organized into sections as follows:

• with getResource() and getFormat() the underlying resource and the format that read this data can be accessed.

• properties can be owned by

  • named sections

  • an (unnamed) default section

• each section section contains a map of properties. Hereby the same key can be part of the default section and multiple named sections, depending on the configuration format.

• The method getSectionNames() returns a set of all section names.

• With getSection(String name) a named section can be accessed.

• With getDefaultSection() the default section can be accessed.

• With getCombinedProperties() a flattened entry map can be accessed built up (by default) out of

  • all entries from the default section, without any changes.

  • all entries from named sections, where the key for each entry is prefix with the section name and a dot separator.

• The configuration format used determines the mapping of configuration data read into this structure. The format implementation can as well provide alternate implementations of how the data read should be mapped into the combined properties map.

Now for the conversion of ConfigurationData into a PropertySource different default approaches are used:

1. The ConfigurationFormat that read the data can provide the (combined) properties accessible from getProperties() explcitly, which can be used to initialize a single PropertySource containing the data read.

2. If the format did not set the final properties, but only a default section is present this default section can be directly returned as combined properties.

3. In all other cases a properties can be uniquely mapped into one single properties Map, by prefixing all keys of each section present with the (unique) section name and a '.' separator.

Nevertheless, depending on the context, where a configuration source was read (classloader, time, source etc.) the resulting PropertySource can have different semnatics, especially for the PropertySources ordinal. Also section names may be mapped into different ordinals instead of using them as key prefixes (e.g. imagine configuration formats with a 'default', 'main', and 'overrides' sections). For such more complex or custom cases no useful default mapping can be defined. In such cases this functionality must be implemented in a mapData method, which converts the normalized ConfigData read to the appropriate collection of PropertySource instances:

ConfigurationFormat

A ConfigurationFormat is basically an abstraction that reads a configuration resource (modelled by an InputStream) and creates a corresponding ConfigurationData instance.

public interface ConfigurationFormat {

    public String getName();
    boolean accepts(URL url);
    ConfigurationData readConfiguration(String resource, InputStream inputStream);
}

Normally you need to map the resulting ConfigurationData to one or multiple PropertySources. In case, where the properties provided match exactly the extected properties a FlattenedDefaultPropertySource is provided out-of-the-box. If the exact mapping must be overridden, you can simply override the property source’s initialize method to adapt the mapping:

ConfigurationData data = ...;
FlattenedDefaultPropertySource ps = new FlattenedDefaultPropertySource(data){
  protected Map<String, String> populateData(ConfigurationData data) {
    ...
  }
};

Mapping ini-Files

Consider the following ini-file:

a=valA
a.b=valB

[section1]
aa=sectionValA
aa.b.c=SectionValC

[section2]
a=val2Section2

This file content coud be mapped to the following structure:

a=valA
a.b=valB
section1.valA=sectionValA
section1.a.b.c=SectionValC
section2.a=val2Section2

Nevertheless from the ConfigurationData instance a more complex algorithm can access all the different parts:

• the_default_ properties (a, a.b)

• the section section1, with properties aa, aa.b.c

• the section section2, qith properties a

Mapping xml-Files

The same concept can also be applied to xml-files. Consider the following configuration file:

<config>
  <default>
    <a>valA</a>
    <a.b>valB</a.B>
  </default>

  <section id="section1">
    <param id="aa">sectionValA</aa>
    <param id="aa.b.c">SectionValC</aa.b.c>
  </section>
  <section id="section2">
    <param id="a">val2Section2</aa>
  </section>
</config>

This file basically describes the same configuration as the ini-based version we have seen before. The formats module hereby ships with 3 format classes:

• PropertiesFormat providing support for .properties files.

• PropertiesXmlFormat providing support for xml.property files.

• IniConfiguratonFormat providing support for xml.property files.