org.apache.tamaya.format

## Interface ConfigurationFormat

- All Known Implementing Classes:
    IniConfigurationFormat, PropertiesFormat, PropertiesXmlFormat

      public interface ConfigurationFormat

  Implementations current this class encapsulate the mechanism how to read a resource including interpreting the format correctly (e.g. xml vs. properties vs. ini). In most cases file only contains entries of the same priority, which would then result in only one `PropertySource`. Complex file formats, however, may contain entries of different priorities. In this cases, each ordinal type found typically is returned as a separate section so the consuming `PropertySourceProvider` implementation can distribute the different part to individual `PropertySource`s.

  ### Implementation Requirements

  Implementations of this type must be
  - thread-safe

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `accepts(URL url)` Allows the format to examine the given resource, e.g. for a matching file ending.
    `String` | `getName()` Get a unique name of the format.
    `ConfigurationData` | `readConfiguration(String resource, InputStream inputStream)` Reads a configuration from an URL, hereby parsing the given `InputStream`.

- - ### Method Detail

    - #### getName

          String getName()

      Get a unique name of the format. This name can be used to access the format.
      Returns:
        the (unique) format's name, never null and not empty.

    - #### accepts

          boolean accepts(URL url)

      Allows the format to examine the given resource, e.g. for a matching file ending. Only, if a format accepts an URL, it will be tried for reading the configuration.
      Parameters:
        `url` - the url to read the configuration data from (could be a file, a remote location, a classpath resource or something else, not null.
      Returns:
        true, if this format accepts the given URL for reading.

    - #### readConfiguration

          ConfigurationData readConfiguration(String resource,
                                              InputStream inputStream)

      Reads a configuration from an URL, hereby parsing the given `InputStream`. Dependening on the capabilities of the format the returned `ConfigurationData` may contain different levels of data:
      - Only a default section is returned, since the configuration format does not support hierarchies. This is the case for properties and xml properties.
      - Hierarchical formats such as INI, XML and JSON can map each node to a section. Each section can have its own key/value pairs. This allows to map also complex formats in a generic way. A format implementation should then additionally flatten the whole data and store it in a accessible as `ConfigurationData.getCombinedProperties()`. This allows to use the properties as inout to a default mapping, which is always appropriate as long as no other semnatics are defined in the concrete target scenario.
      - More complex custom scenarios should map their configuration data read into different sections. Typically the data will be mapped into different `PropertySource` instances with different ordinal levels. As an example imagine a custom format that contains sections 'defaults', 'global-defaults', 'application', 'server-overrides'.
      - Alternate formats
      Summarizing implementations common formats should always provide
      - the data organized in sections as useful for the given format. If data is organized in one section, it should be mapped into the DEFAULT section.
      - Formats that do provide multiple sections, should always provide a FLATTENED section as well, where all the data is organized as a flattened key/value pairs, enabling a generic mapping to a `PropertySource`.
      If the configuration format only contains entries of one ordinal type, normally only one single instance of PropertySource is returned (the corresponding key/values should end up in the DEFAULT section). Nevertheless custom formats may contain different sections or parts, where each part maps to a different target ordinal (eg defaults, domain config and app config). In the ladder case multiple PropertySources can be returned, each one with its own ordinal and the corresponding entries.
      Parameters:
        `resource` - a descriptive name for the resource, since an InputStream does not have any)
        `inputStream` - the inputStream to read the configuration data from (could be a file, a remote location, a classpath resource or something else.
      Returns:
        the corresponding `ConfigurationData` containing sections/properties read, never `null`.
      Throws:
        `ConfigException` - if parsing of the input fails.
      See Also:
        `PropertySource`

Copyright © 2014–2015 Apache Software Foundation. All rights reserved.