Package org.apache.commons.configuration2

# Class PropertiesConfigurationLayout

java.lang.Object
org.apache.commons.configuration2.PropertiesConfigurationLayout

All Implemented Interfaces:
  `EventListener<ConfigurationEvent>`

public class PropertiesConfigurationLayout extends Object implements EventListener<ConfigurationEvent>

A helper class used by `PropertiesConfiguration` to keep the layout of a properties file.

Instances of this class are associated with a `PropertiesConfiguration` object. They are responsible for analyzing properties files and for extracting as much information about the file layout (e.g. empty lines, comments) as possible. When the properties file is written back again it should be close to the original.

The `PropertiesConfigurationLayout` object associated with a `PropertiesConfiguration` object can be obtained using the `getLayout()` method of the configuration. Then the methods provided by this class can be used to alter the properties file's layout.

Implementation note: This is a very simple implementation, which is far away from being perfect, i.e. the original layout of a properties file won't be reproduced in all cases. One limitation is that comments for multi-valued property keys are concatenated. Maybe this implementation can later be improved.

To get an impression how this class works consider the following properties file:

     # A demo configuration file
     # for Demo App 1.42

     # Application name
     AppName=Demo App

     # Application vendor
     AppVendor=DemoSoft

     # GUI properties
     # Window Color
     windowColors=0xFFFFFF,0x000000

     # Include some setting
     include=settings.properties
     # Another vendor
     AppVendor=TestSoft

For this example the following points are relevant:

- The first two lines are set as header comment. The header comment is determined by the last blank line before the first property definition.
- For the property `AppName` one comment line and one leading blank line is stored.
- For the property `windowColors` two comment lines and two leading blank lines are stored.
- Include files is something this class cannot deal with well. When saving the properties configuration back, the included properties are simply contained in the original file. The comment before the include property is skipped.
- For all properties except for `AppVendor` the "single line" flag is set. This is relevant only for `windowColors`, which has multiple values defined in one line using the separator character.
- The `AppVendor` property appears twice. The comment lines are concatenated, so that `layout.getComment("AppVendor");` will result in `Application vendor&lt;CR&gt;Another vendor`, with `&lt;CR&gt;` meaning the line separator. In addition the "single line" flag is set to false for this property. When the file is saved, two property definitions will be written (in series).

Since:
  1.3

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PropertiesConfigurationLayout()`
  Creates a new, empty instance of `PropertiesConfigurationLayout`.
  `PropertiesConfigurationLayout(PropertiesConfigurationLayout c)`
  Creates a new instance of `PropertiesConfigurationLayout` and copies the data of the specified layout object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `getBlancLinesBefore(String key)`
  Deprecated.
  Use `getBlankLinesBefore(String)`.
  `int`
  `getBlankLinesBefore(String key)`
  Gets the number of blank lines before this property key.
  `String`
  `getCanonicalComment(String key, boolean commentChar)`
  Gets the comment for the specified property key in a canonical form.
  `String`
  `getCanonicalFooterCooment(boolean commentChar)`
  Gets the footer comment of the represented properties file in a canonical form.
  `String`
  `getCanonicalHeaderComment(boolean commentChar)`
  Gets the header comment of the represented properties file in a canonical form.
  `String`
  `getComment(String key)`
  Gets the comment for the specified property key.
  `String`
  `getFooterComment()`
  Gets the footer comment of the represented properties file.
  `String`
  `getGlobalSeparator()`
  Gets the global separator.
  `String`
  `getHeaderComment()`
  Gets the header comment of the represented properties file.
  `Set<String>`
  `getKeys()`
  Gets a set with all property keys managed by this object.
  `String`
  `getLineSeparator()`
  Gets the line separator.
  `String`
  `getSeparator(String key)`
  Gets the separator for the property with the given key.
  `boolean`
  `isForceSingleLine()`
  Returns the "force single line" flag.
  `boolean`
  `isSingleLine(String key)`
  Returns a flag whether the specified property is defined on a single line.
  `void`
  `load(PropertiesConfiguration config, Reader reader)`
  Reads a properties file and stores its internal structure.
  `void`
  `onEvent(ConfigurationEvent event)`
  The event listener callback.
  `void`
  `save(PropertiesConfiguration config, Writer writer)`
  Writes the properties file to the given writer, preserving as much of its structure as possible.
  `void`
  `setBlancLinesBefore(String key, int number)`
  Deprecated.
  use `setBlankLinesBefore(String, int)`.
  `void`
  `setBlankLinesBefore(String key, int number)`
  Sets the number of blank lines before the given property key.
  `void`
  `setComment(String key, String comment)`
  Sets the comment for the specified property key.
  `void`
  `setFooterComment(String footerComment)`
  Sets the footer comment for the represented properties file.
  `void`
  `setForceSingleLine(boolean f)`
  Sets the "force single line" flag.
  `void`
  `setGlobalSeparator(String globalSeparator)`
  Sets the global separator for properties.
  `void`
  `setHeaderComment(String comment)`
  Sets the header comment for the represented properties file.
  `void`
  `setLineSeparator(String lineSeparator)`
  Sets the line separator.
  `void`
  `setSeparator(String key, String sep)`
  Sets the separator to be used for the property with the given key.
  `void`
  `setSingleLine(String key, boolean f)`
  Sets the "single line flag" for the specified property key.

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

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

- ## Constructor Details

  - ### PropertiesConfigurationLayout

    public PropertiesConfigurationLayout()
    Creates a new, empty instance of `PropertiesConfigurationLayout`.

  - ### PropertiesConfigurationLayout

    public PropertiesConfigurationLayout(PropertiesConfigurationLayout c)
    Creates a new instance of `PropertiesConfigurationLayout` and copies the data of the specified layout object.
    Parameters:
      `c` - the layout object to be copied

- ## Method Details

  - ### getBlancLinesBefore

    @Deprecated public int getBlancLinesBefore(String key)
    Deprecated.
    Use `getBlankLinesBefore(String)`.
    Gets the number of blank lines before this property key. If this key does not exist, 0 will be returned.
    Parameters:
      `key` - the property key
    Returns:
      the number of blank lines before the property definition for this key

  - ### getBlankLinesBefore

    public int getBlankLinesBefore(String key)
    Gets the number of blank lines before this property key. If this key does not exist, 0 will be returned.
    Parameters:
      `key` - the property key
    Returns:
      the number of blank lines before the property definition for this key

  - ### getCanonicalComment

    public String getCanonicalComment(String key, boolean commentChar)
    Gets the comment for the specified property key in a canonical form. "Canonical" means that either all lines start with a comment character or none. If the `commentChar` parameter is false, all comment characters are removed, so that the result is only the plain text of the comment. Otherwise it is ensured that each line of the comment starts with a comment character. Also, line breaks in the comment are normalized to the line separator "\n".
    Parameters:
      `key` - the key of the property
      `commentChar` - determines whether all lines should start with comment characters or not
    Returns:
      the canonical comment for this key (can be null)

  - ### getCanonicalFooterCooment

    public String getCanonicalFooterCooment(boolean commentChar)
    Gets the footer comment of the represented properties file in a canonical form. This method works like `getCanonicalHeaderComment()`, but reads the footer comment.
    Parameters:
      `commentChar` - determines the presence of comment characters
    Returns:
      the footer comment (can be null)
    Since:
      2.0
    See Also:
      - `getCanonicalHeaderComment(boolean)`

  - ### getCanonicalHeaderComment

    public String getCanonicalHeaderComment(boolean commentChar)
    Gets the header comment of the represented properties file in a canonical form. With the `commentChar` parameter it can be specified whether comment characters should be stripped or be always present.
    Parameters:
      `commentChar` - determines the presence of comment characters
    Returns:
      the header comment (can be null)

  - ### getComment

    public String getComment(String key)
    Gets the comment for the specified property key. The comment is returned as it was set (either manually by calling `setComment()` or when it was loaded from a properties file). No modifications are performed.
    Parameters:
      `key` - the key of the property
    Returns:
      the comment for this key (can be null)

  - ### getFooterComment

    public String getFooterComment()
    Gets the footer comment of the represented properties file. This method returns the footer comment exactly as it was set using `setFooterComment()` or extracted from the loaded properties file.
    Returns:
      the footer comment (can be null)
    Since:
      2.0

  - ### getGlobalSeparator

    public String getGlobalSeparator()
    Gets the global separator.
    Returns:
      the global properties separator
    Since:
      1.7

  - ### getHeaderComment

    public String getHeaderComment()
    Gets the header comment of the represented properties file. This method returns the header comment exactly as it was set using `setHeaderComment()` or extracted from the loaded properties file.
    Returns:
      the header comment (can be null)

  - ### getKeys

    public Set<String> getKeys()
    Gets a set with all property keys managed by this object.
    Returns:
      a set with all contained property keys

  - ### getLineSeparator

    public String getLineSeparator()
    Gets the line separator.
    Returns:
      the line separator
    Since:
      1.7

  - ### getSeparator

    public String getSeparator(String key)
    Gets the separator for the property with the given key.
    Parameters:
      `key` - the property key
    Returns:
      the property separator for this property
    Since:
      1.7

  - ### isForceSingleLine

    public boolean isForceSingleLine()
    Returns the "force single line" flag.
    Returns:
      the force single line flag
    See Also:
      - `setForceSingleLine(boolean)`

  - ### isSingleLine

    public boolean isSingleLine(String key)
    Returns a flag whether the specified property is defined on a single line. This is meaningful only if this property has multiple values.
    Parameters:
      `key` - the property key
    Returns:
      a flag if this property is defined on a single line

  - ### load

    public void load(PropertiesConfiguration config, Reader reader) throws ConfigurationException
    Reads a properties file and stores its internal structure. The found properties will be added to the specified configuration object.
    Parameters:
      `config` - the associated configuration object
      `reader` - the reader to the properties file
    Throws:
      `ConfigurationException` - if an error occurs

  - ### onEvent

    public void onEvent(ConfigurationEvent event)
    The event listener callback. Here event notifications of the configuration object are processed to update the layout object properly.
    Specified by:
      `onEvent` in interface `EventListener<ConfigurationEvent>`
    Parameters:
      `event` - the event object

  - ### save

    public void save(PropertiesConfiguration config, Writer writer) throws ConfigurationException
    Writes the properties file to the given writer, preserving as much of its structure as possible.
    Parameters:
      `config` - the associated configuration object
      `writer` - the writer
    Throws:
      `ConfigurationException` - if an error occurs

  - ### setBlancLinesBefore

    @Deprecated public void setBlancLinesBefore(String key, int number)
    Deprecated.
    use `setBlankLinesBefore(String, int)`.
    Sets the number of blank lines before the given property key. This can be used for a logical grouping of properties.
    Parameters:
      `key` - the property key
      `number` - the number of blank lines to add before this property definition

  - ### setBlankLinesBefore

    public void setBlankLinesBefore(String key, int number)
    Sets the number of blank lines before the given property key. This can be used for a logical grouping of properties.
    Parameters:
      `key` - the property key
      `number` - the number of blank lines to add before this property definition
    Since:
      2.8.0

  - ### setComment

    public void setComment(String key, String comment)
    Sets the comment for the specified property key. The comment (or its single lines if it is a multi-line comment) can start with a comment character. If this is the case, it will be written without changes. Otherwise a default comment character is added automatically.
    Parameters:
      `key` - the key of the property
      `comment` - the comment for this key (can be null, then the comment will be removed)

  - ### setFooterComment

    public void setFooterComment(String footerComment)
    Sets the footer comment for the represented properties file. This comment will be output at the bottom of the file.
    Parameters:
      `footerComment` - the footer comment
    Since:
      2.0

  - ### setForceSingleLine

    public void setForceSingleLine(boolean f)
    Sets the "force single line" flag. If this flag is set, all properties with multiple values are written on single lines. This mode provides more compatibility with `Properties`, which cannot deal with multiple definitions of a single property. This mode has no effect if the list delimiter parsing is disabled.
    Parameters:
      `f` - the force single line flag

  - ### setGlobalSeparator

    public void setGlobalSeparator(String globalSeparator)
    Sets the global separator for properties. With this method a separator can be set that will be used for all properties when writing the configuration. This is an easy way of determining the properties separator globally. To be compatible with the properties format only the characters `=` and `:` (with or without whitespace) should be used, but this method does not enforce this - it accepts arbitrary strings. If the global separator is set to null, property separators are not changed. This is the default behavior as it produces results that are closer to the original properties file.
    Parameters:
      `globalSeparator` - the separator to be used for all properties
    Since:
      1.7

  - ### setHeaderComment

    public void setHeaderComment(String comment)
    Sets the header comment for the represented properties file. This comment will be output on top of the file.
    Parameters:
      `comment` - the comment

  - ### setLineSeparator

    public void setLineSeparator(String lineSeparator)
    Sets the line separator. When writing the properties configuration, all lines are terminated with this separator. If no separator was set, the platform-specific default line separator is used.
    Parameters:
      `lineSeparator` - the line separator
    Since:
      1.7

  - ### setSeparator

    public void setSeparator(String key, String sep)
    Sets the separator to be used for the property with the given key. The separator is the string between the property key and its value. For new properties " = " is used. When a properties file is read, the layout tries to determine the separator for each property. With this method the separator can be changed. To be compatible with the properties format only the characters `=` and `:` (with or without whitespace) should be used, but this method does not enforce this - it accepts arbitrary strings. If the key refers to a property with multiple values that are written on multiple lines, this separator will be used on all lines.
    Parameters:
      `key` - the key for the property
      `sep` - the separator to be used for this property
    Since:
      1.7

  - ### setSingleLine

    public void setSingleLine(String key, boolean f)
    Sets the "single line flag" for the specified property key. This flag is evaluated if the property has multiple values (i.e. if it is a list property). In this case, if the flag is set, all values will be written in a single property definition using the list delimiter as separator. Otherwise multiple lines will be written for this property, each line containing one property value.
    Parameters:
      `key` - the property key
      `f` - the single line flag