org.apache.commons.configuration

Class PropertiesConfigurationLayout

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:

Since: 1.3

Version: $Id: PropertiesConfigurationLayout.java 439648 2006-09-02 20:42:10Z oheger $

Author: Commons Configuration team

Nested Class Summary
static classPropertiesConfigurationLayout.PropertyLayoutData
A helper class for storing all layout related information for a configuration property.
Field Summary
PropertiesConfigurationconfiguration
Stores the associated configuration object.
static StringCOMMENT_PREFIX
Constant for the default comment prefix.
static StringCR
Constant for the line break character.
booleanforceSingleLine
Stores the force single line flag.
StringheaderComment
Stores the header comment.
MaplayoutData
Stores a map with the contained layout information.
intloadCounter
A counter for determining nested load calls.
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
intcheckHeaderComment(List commentLines)
Checks if parts of the passed in comment can be used as header comment.
voidclear()
Removes all content from this layout object.
voidconfigurationChanged(ConfigurationEvent event)
The event listener callback.
voidcopyFrom(PropertiesConfigurationLayout c)
Copies the data from the given layout object.
StringextractComment(List commentLines, int from, int to)
Extracts a comment string from the given range of the specified comment lines.
PropertiesConfigurationLayout.PropertyLayoutDatafetchLayoutData(String key)
Returns a layout data object for the specified key.
intgetBlancLinesBefore(String key)
Returns the number of blanc lines before this property key.
StringgetCanonicalComment(String key, boolean commentChar)
Returns the comment for the specified property key in a cononical form.
StringgetCanonicalHeaderComment(boolean commentChar)
Returns the header comment of the represented properties file in a canonical form.
StringgetComment(String key)
Returns the comment for the specified property key.
PropertiesConfigurationgetConfiguration()
Returns the associated configuration object.
StringgetHeaderComment()
Returns the header comment of the represented properties file.
SetgetKeys()
Returns a set with all property keys managed by this object.
static booleanisCommentLine(String line)
Tests whether a line is a comment, i.e. whether it starts with a comment character.
booleanisForceSingleLine()
Returns the "force single line" flag.
booleanisSingleLine(String key)
Returns a flag whether the specified property is defined on a single line.
voidload(Reader in)
Reads a properties file and stores its internal structure.
voidsave(Writer out)
Writes the properties file to the given writer, preserving as much of its structure as possible.
voidsetBlancLinesBefore(String key, int number)
Sets the number of blanc lines before the given property key.
voidsetComment(String key, String comment)
Sets the comment for the specified property key.
voidsetForceSingleLine(boolean f)
Sets the "force single line" flag.
voidsetHeaderComment(String comment)
Sets the header comment for the represented properties file.
voidsetSingleLine(String key, boolean f)
Sets the "single line flag" for the specified property key.
static StringstripCommentChar(String s, boolean comment)
Either removes the comment character from the given comment line or ensures that the line starts with a comment character.
static StringtrimComment(String s, boolean comment)
Trims a comment.

Field Detail

configuration

private PropertiesConfiguration configuration
Stores the associated configuration object.

COMMENT_PREFIX

private static final String COMMENT_PREFIX
Constant for the default comment prefix.

CR

private static final String CR
Constant for the line break character.

forceSingleLine

private boolean forceSingleLine
Stores the force single line flag.

headerComment

private String headerComment
Stores the header comment.

layoutData

private Map layoutData
Stores a map with the contained layout information.

loadCounter

private int loadCounter
A counter for determining nested load calls.

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

checkHeaderComment

private int checkHeaderComment(List commentLines)
Checks if parts of the passed in comment can be used as header comment. This method checks whether a header comment can be defined (i.e. whether this is the first comment in the loaded file). If this is the case, it is searched for the lates blanc line. This line will mark the end of the header comment. The return value is the index of the first line in the passed in list, which does not belong to the header comment.

Parameters: commentLines the comment lines

Returns: the index of the next line after the header comment

clear

private void clear()
Removes all content from this layout object.

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.

Parameters: event the event object

copyFrom

private void copyFrom(PropertiesConfigurationLayout c)
Copies the data from the given layout object.

Parameters: c the layout object to copy

extractComment

private String extractComment(List commentLines, int from, int to)
Extracts a comment string from the given range of the specified comment lines. The single lines are added using a line feed as separator.

Parameters: commentLines a list with comment lines from the start index to the end index (inclusive)

Returns: the comment string (null if it is undefined)

fetchLayoutData

private PropertiesConfigurationLayout.PropertyLayoutData fetchLayoutData(String key)
Returns a layout data object for the specified key. If this is a new key, a new object is created and initialized with default values.

Parameters: key the key

Returns: the corresponding layout data object

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

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)

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)

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)

getConfiguration

public PropertiesConfiguration getConfiguration()
Returns the associated configuration object.

Returns: the associated configuration

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)

getKeys

public Set getKeys()
Returns a set with all property keys managed by this object.

Returns: a set with all contained property keys

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

isForceSingleLine

public boolean isForceSingleLine()
Returns the "force single line" flag.

Returns: the force single line flag

See Also: PropertiesConfigurationLayout

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(Reader in)
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)
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

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

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)

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

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

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

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

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