org.apache.tamaya.format.formats

## Class PropertiesFormat

- java.lang.Object
- - org.apache.tamaya.format.formats.PropertiesFormat

- All Implemented Interfaces:
    ConfigurationFormat

      public class PropertiesFormat
      extends Object
      implements ConfigurationFormat

  Implementation of a `ConfigurationFormat` for -properties files.
  See Also:
    `Properties.load(java.io.InputStream)`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PropertiesFormat()`

  - ### Method Summary

    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`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PropertiesFormat

          public PropertiesFormat()

  - ### Method Detail

    - #### getName

          public String getName()

      Description copied from interface: `ConfigurationFormat`
      Get a unique name of the format. This name can be used to access the format.
      Specified by:
        `getName` in interface `ConfigurationFormat`
      Returns:
        the (unique) format's name, never null and not empty.

    - #### accepts

          public boolean accepts(URL url)

      Description copied from interface: `ConfigurationFormat`
      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.
      Specified by:
        `accepts` in interface `ConfigurationFormat`
      Parameters:
        `url` - the url to read the configuration data from (could be a file, a server location, a classpath resource or something else, not null.
      Returns:
        true, if this format accepts the given URL for reading.

    - #### readConfiguration

          public ConfigurationData readConfiguration(String resource,
                                            InputStream inputStream)

      Description copied from interface: `ConfigurationFormat`
      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.
      Specified by:
        `readConfiguration` in interface `ConfigurationFormat`
      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 server location, a classpath resource or something else.
      Returns:
        the corresponding `ConfigurationData` containing sections/properties read, never `null`.
      See Also:
        `PropertySource`

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