## org.apache.commons.configuration
Class PropertiesConfigurationLayout

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

All Implemented Interfaces:
  ConfigurationListener

    public class PropertiesConfigurationLayout

extends Object
implements ConfigurationListener

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 blanc line before the first property definition.
- For the property `AppName` one comment line and one leading blanc line is stored.
- For the property `windowColors` two comment lines and two leading blanc 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<CR>Another vendor`, whith `<CR>` 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
Version:
  $Id: PropertiesConfigurationLayout.java 439648 2006-09-02 20:42:10Z oheger $
Author:
  Commons Configuration team

Nested Class Summary
`(package private) static class` `PropertiesConfigurationLayout.PropertyLayoutData` A helper class for storing all layout related information for a configuration property.

Constructor Summary
`PropertiesConfigurationLayout(PropertiesConfiguration config)` Creates a new instance of `PropertiesConfigurationLayout` and initializes it with the associated configuration object.
`PropertiesConfigurationLayout(PropertiesConfiguration config, PropertiesConfigurationLayout c)` Creates a new instance of `PropertiesConfigurationLayout` and initializes it with the given configuration object.

Method Summary
`void` `configurationChanged(ConfigurationEvent event)` The event listener callback.
`int` `getBlancLinesBefore(String key)` Returns the number of blanc lines before this property key.
`String` `getCanonicalComment(String key, boolean commentChar)` Returns the comment for the specified property key in a cononical form.
`String` `getCanonicalHeaderComment(boolean commentChar)` Returns the header comment of the represented properties file in a canonical form.
`String` `getComment(String key)` Returns the comment for the specified property key.
`PropertiesConfiguration` `getConfiguration()` Returns the associated configuration object.
`String` `getHeaderComment()` Returns the header comment of the represented properties file.
`Set` `getKeys()` Returns a set with all property keys managed by this object.
`(package private) static boolean` `isCommentLine(String line)` Tests whether a line is a comment, i.e. whether it starts with a comment character.
`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(Reader in)` Reads a properties file and stores its internal structure.
`void` `save(Writer out)` Writes the properties file to the given writer, preserving as much of its structure as possible.
`void` `setBlancLinesBefore(String key, int number)` Sets the number of blanc lines before the given property key.
`void` `setComment(String key, String comment)` Sets the comment for the specified property key.
`void` `setForceSingleLine(boolean f)` Sets the "force single line" flag.
`void` `setHeaderComment(String comment)` Sets the header comment for the represented properties file.
`void` `setSingleLine(String key, boolean f)` Sets the "single line flag" for the specified property key.
`(package private) static String` `stripCommentChar(String s, boolean comment)` Either removes the comment character from the given comment line or ensures that the line starts with a comment character.
`(package private) static String` `trimComment(String s, boolean comment)` Trims a comment.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### PropertiesConfigurationLayout

    public PropertiesConfigurationLayout(PropertiesConfiguration config)

  Creates a new instance of `PropertiesConfigurationLayout` and initializes it with the associated configuration object.

  Parameters:
    `config` - the configuration (must not be null)

### PropertiesConfigurationLayout

    public PropertiesConfigurationLayout(PropertiesConfiguration config,
                                         PropertiesConfigurationLayout c)

  Creates a new instance of `PropertiesConfigurationLayout` and initializes it with the given configuration object. The data of the specified layout object is copied.

  Parameters:
    `config` - the configuration (must not be null)
    `c` - the layout object to be copied

Method Detail

### getConfiguration

    public PropertiesConfiguration getConfiguration()

  Returns the associated configuration object.

  Returns:
    the associated configuration

### getCanonicalComment

    public String getCanonicalComment(String key,
                                      boolean commentChar)

  Returns the comment for the specified property key in a cononical form. "Canonical" means that either all lines start with a comment character or none. 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.

  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)

### getComment

    public String getComment(String key)

  Returns 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)

### 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)

### getBlancLinesBefore

    public int getBlancLinesBefore(String key)

  Returns the number of blanc lines before this property key. If this key does not exist, 0 will be returned.

  Parameters:
    `key` - the property key
  Returns:
    the number of blanc lines before the property definition for this key

### setBlancLinesBefore

    public void setBlancLinesBefore(String key,
                                    int number)

  Sets the number of blanc 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 blanc lines to add before this property definition

### getCanonicalHeaderComment

    public String getCanonicalHeaderComment(boolean commentChar)

  Returns 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)

### getHeaderComment

    public String getHeaderComment()

  Returns 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)

### 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

### 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

### 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

### isForceSingleLine

    public boolean isForceSingleLine()

  Returns the "force single line" flag.

  Returns:
    the force single line flag
  See Also:
    `setForceSingleLine(boolean)`

### 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 `java.lang.Properties`, which cannot deal with multiple definitions of a single property.

  Parameters:
    `f` - the force single line flag

### getKeys

    public Set getKeys()

  Returns a set with all property keys managed by this object.

  Returns:
    a set with all contained property keys

### load

    public void load(Reader in)
              throws ConfigurationException

  Reads a properties file and stores its internal structure. The found properties will be added to the associated configuration object.

  Parameters:
    `in` - the reader to the properties file
  Throws:
    `ConfigurationException` - if an error occurs

### save

    public void save(Writer out)
              throws ConfigurationException

  Writes the properties file to the given writer, preserving as much of its structure as possible.

  Parameters:
    `out` - the writer
  Throws:
    `ConfigurationException` - if an error occurs

### configurationChanged

    public void configurationChanged(ConfigurationEvent event)

  The event listener callback. Here event notifications of the configuration object are processed to update the layout object properly.

  Specified by:
    `configurationChanged` in interface `ConfigurationListener`
  Parameters:
    `event` - the event object

### isCommentLine

    static boolean isCommentLine(String line)

  Tests whether a line is a comment, i.e. whether it starts with a comment character.

  Parameters:
    `line` - the line
  Returns:
    a flag if this is a comment line

### trimComment

    static String trimComment(String s,
                              boolean comment)

  Trims a comment. This method either removes all comment characters from the given string, leaving only the plain comment text or ensures that every line starts with a valid comment character.

  Parameters:
    `s` - the string to be processed
    `comment` - if true, a comment character will always be enforced; if false, it will be removed
  Returns:
    the trimmed comment

### stripCommentChar

    static String stripCommentChar(String s,
                                   boolean comment)

  Either removes the comment character from the given comment line or ensures that the line starts with a comment character.

  Parameters:
    `s` - the comment line
    `comment` - if true, a comment character will always be enforced; if false, it will be removed
  Returns:
    the line without comment character

Copyright © 2001-2006 The Apache Software Foundation. All Rights Reserved.