Java Doc for PropertiesConfiguration.java in  » Library » Apache-commons-configuration-1.4-src » org » apache » commons » configuration » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 java.util.Properties.load and adds several useful extensions:

• Each property has the syntax key <separator> 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.
• value can contain value delimiters and will then be interpreted as a list of tokens. Default value delimiter is the comma ','. So the following property definition

   key = This property, has multiple, values
   

  will result in a property with three values. You can change the value delimiter using the AbstractConfiguration.setListDelimiter(char) method. Setting the delimiter to 0 will disable value splitting completely.
• 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.
• 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.

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.
See Also:   java.util.Properties.load
author:
   Stefano Mazzocchi
author:
   Jon S. Stevens
author:
   Dave Bryson
author:
   Geir Magnusson Jr.
author:
   Leon Messerschmidt
author:
   Kent Johnson
author:
   Daniel Rall
author:
   Ilkka Priha
author:
   Jason van Zyl
author:
   Martin Poeschl
author:
   Henning P. Schmiedehausen
author:
   Eric Pugh
author:
   Oliver Heger
author:
   Emmanuel Bourg
version:
   $Id: PropertiesConfiguration.java 439648 2006-09-02 20:42:10Z oheger $

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

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