PropertiesConfiguration (Apache Commons Configuration 2.15.1 API)
Description: declaration: package: org.apache.commons.configuration2, class: PropertiesConfiguration

Package org.apache.commons.configuration2

# Class PropertiesConfiguration

java.lang.Object
org.apache.commons.configuration2.event.BaseEventSource
org.apache.commons.configuration2.AbstractConfiguration
org.apache.commons.configuration2.BaseConfiguration
org.apache.commons.configuration2.PropertiesConfiguration

All Implemented Interfaces:
  `Cloneable`, `Configuration`, `EventSource`, `FileBasedConfiguration`, `ImmutableConfiguration`, `FileBased`, `FileLocatorAware`, `SynchronizerSupport`

public class PropertiesConfiguration extends BaseConfiguration implements FileBasedConfiguration, FileLocatorAware
This is the "classic" Properties loader which loads the values from a single or multiple files (which can be chained with "include =". All given path references are either absolute or relative to the file name supplied in the constructor.

In this class, empty PropertyConfigurations can be built, properties added and later saved. include statements are (obviously) not supported if you don't construct a PropertyConfiguration from a file.

The properties file syntax is explained here, basically it follows the syntax of the stream parsed by `Properties.load(java.io.Reader)` and adds several useful extensions:

- Each property has the syntax `key &lt;separator&gt; value`. The separators accepted are `'='`, `':'` and any white space character. Examples:

        key1 = value1
        key2 : value2
        key3   value3

- The key may use any character, separators must be escaped:

        key\:foo = bar

- value may be separated on different lines if a backslash is placed at the end of the line that continues below.
- The list delimiter facilities provided by `AbstractConfiguration` are supported, too. If an appropriate `ListDelimiterHandler` is set (for instance a `D efaultListDelimiterHandler` object configured with a comma as delimiter character), value can contain value delimiters and will then be interpreted as a list of tokens. So the following property definition

        key = This property, has multiple, values

  will result in a property with three values. You can change the handling of delimiters using the `AbstractConfiguration.setListDelimiterHandler(ListDelimiterHandler)` method. Per default, list splitting is disabled.
- Commas in each token are escaped placing a backslash right before the comma.
- If a key is used more than once, the values are appended like if they were on the same line separated with commas. Note: When the configuration file is written back to disk the associated `PropertiesConfigurationLayout` object (see below) will try to preserve as much of the original format as possible, i.e. properties with multiple values defined on a single line will also be written back on a single line, and multiple occurrences of a single key will be written on multiple lines. If the `addProperty()` method was called multiple times for adding multiple values to a property, these properties will per default be written on multiple lines in the output file, too. Some options of the `PropertiesConfigurationLayout` class have influence on that behavior.
- Blank lines and lines starting with character '#' or '!' are skipped.
- If a property is named "include" (or whatever is defined by setInclude() and getInclude() and the value of that property is the full path to a file on disk, that file will be included into the configuration. You can also pull in files relative to the parent configuration file. So if you have something like the following: include = additional.properties Then "additional.properties" is expected to be in the same directory as the parent configuration file. The properties in the included file are added to the parent configuration, they do not replace existing properties with the same key.
- You can define custom error handling for the special key `"include"` by using `setIncludeListener(ConfigurationConsumer)`.

Here is an example of a valid extended properties file:

          # lines starting with # are comments

          # This is the simplest property
          key = value

          # A long property may be separated on multiple lines
          longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
                      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

          # This is a property with many tokens
          tokens_on_a_line = first token, second token

          # This sequence generates exactly the same result
          tokens_on_multiple_lines = first token
          tokens_on_multiple_lines = second token

          # commas may be escaped in tokens
          commas.escaped = Hi\, what'up?

          # properties can reference other properties
          base.prop = /base
          first.prop = ${base.prop}/first
          second.prop = ${first.prop}/second

A `PropertiesConfiguration` object is associated with an instance of the `PropertiesConfigurationLayout` class, which is responsible for storing the layout of the parsed properties file (i.e. empty lines, comments, and such things). The `getLayout()` method can be used to obtain this layout object. With `setLayout()` a new layout object can be set. This should be done before a properties file was loaded.

Like other `Configuration` implementations, this class uses a `Synchronizer` object to control concurrent access. By choosing a suitable implementation of the `Synchronizer` interface, an instance can be made thread-safe or not. Note that access to most of the properties typically set through a builder is not protected by the `Synchronizer`. The intended usage is that these properties are set once at construction time through the builder and after that remain constant. If you wish to change such properties during life time of an instance, you have to use the `lock()` and `unlock()` methods manually to ensure that other threads see your changes.

As this class extends `AbstractConfiguration`, all basic features like variable interpolation, list handling, or data type conversions are available as well. This is described in the chapter Basic features and AbstractConfiguration of the user's guide. There is also a separate chapter dealing with Properties files in special.

As of version 2.15.0, by default, when including files, the only URL schemes allowed are `file` and `jar`. To override this default, you can either use the system property `org.apache.commons.configuration2.io.FileLocationStrategy.schemes` or build a subclass of `AbstractFileLocationStrategy`.

Using System Properties

The system property `org.apache.commons.configuration2.io.FileLocationStrategy.schemes` String value must be a comma-separated list of schemes, where the default is `"file,jar"`, and the complete list is `"file,http,https,jar"`.

Using a Builder

The root builder for `AbstractFileLocationStrategy` is `AbstractFileLocationStrategy.AbstractBuilder` where you define allowed schemes and hosts through its setter methods.

For example, to programatically enable the shemes "file", "http", "https", and "jar" for all strategies, see `AbstractFileLocationStrategy`.

See Also:
  - `Properties.load(java.io.Reader)`
  - `AbstractFileLocationStrategy`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `PropertiesConfiguration.DefaultIOFactory`
  A default implementation of the `IOFactory` interface.
  `static interface`
  `PropertiesConfiguration.IOFactory`
  Definition of an interface that allows customization of read and write operations.
  `static class`
  `PropertiesConfiguration.JupIOFactory`
  An alternative `PropertiesConfiguration.IOFactory` that tries to mimic the behavior of `Properties` (Jup) more closely.
  `static class`
  `PropertiesConfiguration.JupPropertiesReader`
  A `PropertiesConfiguration.PropertiesReader` that tries to mimic the behavior of `Properties`.
  `static class`
  `PropertiesConfiguration.JupPropertiesWriter`
  A `PropertiesConfiguration.PropertiesWriter` that tries to mimic the behavior of `Properties`.
  `static class`
  `PropertiesConfiguration.PropertiesReader`
  This class is used to read properties lines.
  `static class`
  `PropertiesConfiguration.PropertiesWriter`
  This class is used to write properties lines.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_ENCODING`
  The default encoding (ISO-8859-1 as specified by https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html)
  `static final ConfigurationConsumer<ConfigurationException>`
  `DEFAULT_INCLUDE_LISTENER`
  Defines default error handling for the special `"include"` key by throwing the given exception.
  `static final ConfigurationConsumer<ConfigurationException>`
  `NOOP_INCLUDE_LISTENER`
  Defines error handling as a noop for the special `"include"` key.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PropertiesConfiguration()`
  Creates an empty PropertyConfiguration object which can be used to synthesize a new Properties file by adding values and then saving().

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `clone()`
  Creates a copy of this object.
  `String`
  `getFooter()`
  Gets the footer comment.
  `String`
  `getHeader()`
  Gets the comment header.
  `static String`
  `getInclude()`
  Gets the property value for including other properties files.
  `ConfigurationConsumer<ConfigurationException>`
  `getIncludeListener()`
  Gets the current include listener, never null.
  `static String`
  `getIncludeOptional()`
  Gets the property value for including other properties files.
  `PropertiesConfiguration.IOFactory`
  `getIOFactory()`
  Gets the `IOFactory` to be used for creating readers and writers when loading or saving this configuration.
  `PropertiesConfigurationLayout`
  `getLayout()`
  Gets the associated layout object.
  `FileLocator`
  `getLocator()`
  Gets the file locator.
  `void`
  `initFileLocator(FileLocator locator)`
  Sets the current `FileLocator` for a following IO operation.
  `boolean`
  `isIncludesAllowed()`
  Reports the status of file inclusion.
  `void`
  `read(Reader in)`
  Reads the content of this object from the given reader.
  `void`
  `setFooter(String footer)`
  Sets the footer comment.
  `void`
  `setHeader(String header)`
  Sets the comment header.
  `static void`
  `setInclude(String inc)`
  Sets the property value for including other properties files.
  `void`
  `setIncludeListener(ConfigurationConsumer<ConfigurationException> includeListener)`
  Sets the current include listener, may not be null.
  `static void`
  `setIncludeOptional(String inc)`
  Sets the property value for including other properties files.
  `void`
  `setIncludesAllowed(boolean includesAllowed)`
  Controls whether additional files can be loaded by the `include = <xxx>` statement or not.
  `void`
  `setIOFactory(PropertiesConfiguration.IOFactory ioFactory)`
  Sets the `IOFactory` to be used for creating readers and writers when loading or saving this configuration.
  `void`
  `setLayout(PropertiesConfigurationLayout layout)`
  Sets the associated layout object.
  `protected static String`
  `unescapeJava(String str)`
  Unescapes any Java literals found in the `String` to a `Writer`.
  `protected static String`
  `unescapeJava(String str, boolean jupCompatible)`
  Unescapes Java literals found in the `String` to a `Writer`.
  `void`
  `write(Writer out)`
  Writes the content of this object to the given writer.

  ### Methods inherited from class org.apache.commons.configuration2.BaseConfiguration

  `addPropertyDirect, clearInternal, clearPropertyDirect, containsKeyInternal, containsValueInternal, getKeysInternal, getPropertyInternal, isEmptyInternal, sizeInternal`

  ### Methods inherited from class org.apache.commons.configuration2.AbstractConfiguration

  `addErrorLogListener, addProperty, addPropertyInternal, append, beginRead, beginWrite, clear, clearProperty, cloneInterpolator, contains, containsKey, containsValue, copy, endRead, endWrite, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getConfigurationDecoder, getConversionHandler, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getKeys, getKeys, getKeysInternal, getKeysInternal, getList, getList, getList, getList, getListDelimiterHandler, getLogger, getLong, getLong, getLong, getProperties, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, getSynchronizer, immutableSubset, initLogger, installInterpolator, interpolate, interpolate, interpolatedConfiguration, isEmpty, isScalarValue, isThrowExceptionOnMissing, lock, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setListDelimiterHandler, setLogger, setParentInterpolator, setPrefixLookups, setProperty, setPropertyInternal, setSynchronizer, setThrowExceptionOnMissing, size, subset, unlock`

  ### Methods inherited from class org.apache.commons.configuration2.event.BaseEventSource

  `addEventListener, clearErrorListeners, clearEventListeners, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, setDetailEvents`

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

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

  ### Methods inherited from interface org.apache.commons.configuration2.Configuration

  `addProperty, clear, clearProperty, getInterpolator, installInterpolator, setInterpolator, setProperty, subset`

  ### Methods inherited from interface org.apache.commons.configuration2.ImmutableConfiguration

  `containsKey, containsValue, entrySet, forEach, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getEnum, getEnum, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getKeys, getKeys, getList, getList, getList, getList, getLong, getLong, getLong, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, immutableSubset, isEmpty, size`

  ### Methods inherited from interface org.apache.commons.configuration2.sync.SynchronizerSupport

  `getSynchronizer, lock, setSynchronizer, unlock`

- ## Field Details

  - ### DEFAULT_INCLUDE_LISTENER

    public static final ConfigurationConsumer<ConfigurationException> DEFAULT_INCLUDE_LISTENER
    Defines default error handling for the special `"include"` key by throwing the given exception.
    Since:
      2.6

  - ### NOOP_INCLUDE_LISTENER

    public static final ConfigurationConsumer<ConfigurationException> NOOP_INCLUDE_LISTENER
    Defines error handling as a noop for the special `"include"` key.
    Since:
      2.6

  - ### DEFAULT_ENCODING

    public static final String DEFAULT_ENCODING
    The default encoding (ISO-8859-1 as specified by https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html)

- ## Constructor Details

  - ### PropertiesConfiguration

    public PropertiesConfiguration()
    Creates an empty PropertyConfiguration object which can be used to synthesize a new Properties file by adding values and then saving().

- ## Method Details

  - ### getInclude

    public static String getInclude()
    Gets the property value for including other properties files. By default it is "include".
    Returns:
      A String.

  - ### getIncludeOptional

    public static String getIncludeOptional()
    Gets the property value for including other properties files. By default it is "includeoptional".

    If the file is absent, processing continues normally.

    Returns:
      A String.
    Since:
      2.5

  - ### setInclude

    public static void setInclude(String inc)
    Sets the property value for including other properties files. By default it is "include".
    Parameters:
      `inc` - A String.

  - ### setIncludeOptional

    public static void setIncludeOptional(String inc)
    Sets the property value for including other properties files. By default it is "include".

    If the file is absent, processing continues normally.

    Parameters:
      `inc` - A String.
    Since:
      2.5

  - ### unescapeJava

    protected static String unescapeJava(String str)

    Unescapes any Java literals found in the `String` to a `Writer`.

    This is a slightly modified version of the StringEscapeUtils.unescapeJava() function in commons-lang that doesn't drop escaped separators (i.e '\,').
    Parameters:
      `str` - the `String` to unescape, may be null
    Returns:
      the processed string
    Throws:
      `IllegalArgumentException` - if the Writer is `null`

  - ### unescapeJava

    protected static String unescapeJava(String str, boolean jupCompatible)
    Unescapes Java literals found in the `String` to a `Writer`.

    When the parameter `jupCompatible` is `false`, the classic behavior is used (see `unescapeJava(String)`). When it's `true` a slightly different behavior that's compatible with `Properties` is used (see `PropertiesConfiguration.JupIOFactory`).

    Parameters:
      `str` - the `String` to unescape, may be null
      `jupCompatible` - whether unescaping is compatible with `Properties`; otherwise the classic behavior is used
    Returns:
      the processed string
    Throws:
      `IllegalArgumentException` - if the Writer is `null`

  - ### clone

    public Object clone()
    Creates a copy of this object.
    Overrides:
      `clone` in class `BaseConfiguration`
    Returns:
      the copy

  - ### getFooter

    public String getFooter()
    Gets the footer comment. This is a comment at the very end of the file.
    Returns:
      the footer comment
    Since:
      2.0

  - ### getHeader

    public String getHeader()
    Gets the comment header.
    Returns:
      the comment header
    Since:
      1.1

  - ### getIncludeListener

    public ConfigurationConsumer<ConfigurationException> getIncludeListener()
    Gets the current include listener, never null.
    Returns:
      the current include listener, never null.
    Since:
      2.6

  - ### getIOFactory

    public PropertiesConfiguration.IOFactory getIOFactory()
    Gets the `IOFactory` to be used for creating readers and writers when loading or saving this configuration.
    Returns:
      the `IOFactory`
    Since:
      1.7

  - ### getLayout

    public PropertiesConfigurationLayout getLayout()
    Gets the associated layout object.
    Returns:
      the associated layout object
    Since:
      1.3

  - ### getLocator

    public FileLocator getLocator()
    Gets the file locator.
    Returns:
      the file locator.
    Since:
      2.15.0

  - ### initFileLocator

    public void initFileLocator(FileLocator locator)
    Sets the current `FileLocator` for a following IO operation. The `FileLocator` is needed to resolve include files with relative file names.
    Specified by:
      `initFileLocator` in interface `FileLocatorAware`
    Parameters:
      `locator` - the current `FileLocator`
    Since:
      2.0

  - ### isIncludesAllowed

    public boolean isIncludesAllowed()
    Reports the status of file inclusion.
    Returns:
      True if include files are loaded.

  - ### read

    public void read(Reader in) throws ConfigurationException, IOException
    Reads the content of this object from the given reader. Client code should not call this method directly, but use a `FileHandler` for reading data. This implementation delegates to the associated layout object which does the actual loading. Note that this method does not do any synchronization. This lies in the responsibility of the caller. (Typically, the caller is a `FileHandler` object which takes care for proper synchronization.)
    Specified by:
      `read` in interface `FileBased`
    Parameters:
      `in` - the reader
    Throws:
      `ConfigurationException` - if a non-I/O related problem occurs, for example the data read does not have the expected format
      `IOException` - if an I/O error occurs.
    Since:
      2.0

  - ### setFooter

    public void setFooter(String footer)
    Sets the footer comment. If set, this comment is written after all properties at the end of the file.
    Parameters:
      `footer` - the footer comment
    Since:
      2.0

  - ### setHeader

    public void setHeader(String header)
    Sets the comment header.
    Parameters:
      `header` - the header to use
    Since:
      1.1

  - ### setIncludeListener

    public void setIncludeListener(ConfigurationConsumer<ConfigurationException> includeListener)
    Sets the current include listener, may not be null.
    Parameters:
      `includeListener` - the current include listener, may not be null.
    Throws:
      `IllegalArgumentException` - if the `includeListener` is null.
    Since:
      2.6

  - ### setIncludesAllowed

    public void setIncludesAllowed(boolean includesAllowed)
    Controls whether additional files can be loaded by the `include = <xxx>` statement or not. This is true per default.
    Parameters:
      `includesAllowed` - True if Includes are allowed.

  - ### setIOFactory

    public void setIOFactory(PropertiesConfiguration.IOFactory ioFactory)
    Sets the `IOFactory` to be used for creating readers and writers when loading or saving this configuration. Using this method a client can customize the reader and writer classes used by the load and save operations. Note that this method must be called before invoking one of the `load()` and `save()` methods. Especially, if you want to use a custom `IOFactory` for changing the `PropertiesReader`, you cannot load the configuration data in the constructor.
    Parameters:
      `ioFactory` - the new `IOFactory` (must not be null)
    Throws:
      `IllegalArgumentException` - if the `IOFactory` is null
    Since:
      1.7

  - ### setLayout

    public void setLayout(PropertiesConfigurationLayout layout)
    Sets the associated layout object.
    Parameters:
      `layout` - the new layout object; can be null, then a new layout object will be created
    Since:
      1.3

  - ### write

    public void write(Writer out) throws ConfigurationException, IOException
    Writes the content of this object to the given writer. Client code should not call this method directly, but use a `FileHandler` for writing data. This implementation delegates to the associated layout object which does the actual saving. Note that, analogous to `read(Reader)`, this method does not do any synchronization.
    Specified by:
      `write` in interface `FileBased`
    Parameters:
      `out` - the writer
    Throws:
      `ConfigurationException` - if a non-I/O related problem occurs, for example the data read does not have the expected format
      `IOException` - if an I/O error occurs.
    Since:
      2.0