org.apache.commons.configuration
public class PropertiesConfiguration extends AbstractFileConfiguration
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:
key <separator> value
. The
separators accepted are '='
, ':'
and any white
space character. Examples:
key1 = value1 key2 : value2 key3 value3
key\:foo = bar
key = This property, has multiple, valueswill result in a property with three values. You can change the value delimiter using the
AbstractConfiguration
method. Setting the delimiter to 0 will disable value splitting completely.
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.
Version: $Id: PropertiesConfiguration.java 439648 2006-09-02 20:42:10Z oheger $
See Also: java.util.Properties#load
Nested Class Summary | |
---|---|
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 | |
---|---|
static String | COMMENT_CHARS Constant for the supported comment characters. |
static String | DEFAULT_ENCODING
The default encoding (ISO-8859-1 as specified by
http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html) |
static int | HEX_RADIX Constant for the radix of hex numbers. |
static String | include
This is the name of the property that can point to other
properties file for including other properties files. |
boolean | includesAllowed Allow file inclusion or not |
PropertiesConfigurationLayout | layout Stores the layout object. |
static String | LINE_SEPARATOR Constant for the platform specific line separator. |
static char[] | SEPARATORS The list of possible key/value separators |
static int | UNICODE_LEN Constant for the length of a unicode literal. |
static char[] | WHITE_SPACE The white space characters used as key/value separators. |
Constructor Summary | |
---|---|
PropertiesConfiguration()
Creates an empty PropertyConfiguration object which can be
used to synthesize a new Properties file by adding values and
then saving(). | |
PropertiesConfiguration(String fileName)
Creates and loads the extended properties from the specified file.
| |
PropertiesConfiguration(File file)
Creates and loads the extended properties from the specified file.
| |
PropertiesConfiguration(URL url)
Creates and loads the extended properties from the specified URL.
|
Method Summary | |
---|---|
Object | clone()
Creates a copy of this object.
|
protected PropertiesConfigurationLayout | createLayout()
Creates the associated layout object. |
String | getHeader()
Return the comment header.
|
static String | getInclude()
Gets the property value for including other properties files.
|
boolean | getIncludesAllowed()
Reports the status of file inclusion.
|
PropertiesConfigurationLayout | getLayout()
Returns the associated layout object.
|
static boolean | isCommentLine(String line)
Tests whether a line is a comment, i.e. whether it starts with a comment
character.
|
void | load(Reader in)
Load the properties from the given reader.
|
void | loadIncludeFile(String fileName)
Helper method for loading an included properties file. |
boolean | propertyLoaded(String key, String value)
This method is invoked by the associated
PropertiesConfigurationLayout object for each
property definition detected in the parsed properties file. |
void | save(Writer writer)
Save the configuration to the specified stream.
|
void | setBasePath(String basePath)
Extend the setBasePath method to turn includes
on and off based on the existence of a base path.
|
void | setHeader(String header)
Set the comment header.
|
static void | setInclude(String inc)
Sets the property value for including other properties files.
|
protected void | setIncludesAllowed(boolean includesAllowed)
Controls whether additional files can be loaded by the include = |
void | setLayout(PropertiesConfigurationLayout layout)
Sets the associated layout object.
|
protected static String | unescapeJava(String str, char delimiter) Unescapes any Java literals found in the |
Parameters: fileName The name of the properties file to load.
Throws: ConfigurationException Error while loading the properties file
Parameters: file The properties file to load.
Throws: ConfigurationException Error while loading the properties file
Parameters: url The location of the properties file to load.
Throws: ConfigurationException Error while loading the properties file
Returns: the copy
Returns: the layout object to use
Since: 1.3
Returns: the comment header
Since: 1.1
Returns: A String.
Returns: True if include files are loaded.
Returns: the associated layout object
Since: 1.3
Parameters: line the line
Returns: a flag if this is a comment line
Since: 1.3
clear()
method is not called, so
the properties contained in the loaded file will be added to the
actual set of properties.
Parameters: in An InputStream.
Throws: ConfigurationException if an error occurs
load()
when an include
property
is encountered. It tries to resolve relative file names based on the
current base path. If this fails, a resolution based on the location of
this properties file is tried.
Parameters: fileName the name of the file to load
Throws: ConfigurationException if loading fails
PropertiesConfigurationLayout
object for each
property definition detected in the parsed properties file. Its task is
to check whether this is a special property definition (e.g. the
include
property). If not, the property must be added to
this configuration. The return value indicates whether the property
should be treated as a normal property. If it is false, the
layout object will ignore this property.
Parameters: key the property key value the property value
Returns: a flag whether this is a normal property
Throws: ConfigurationException if an error occurs
Since: 1.3
Parameters: writer the output stream used to save the configuration
Throws: ConfigurationException if an error occurs
Parameters: basePath The new basePath to set.
Parameters: header the header to use
Since: 1.1
Parameters: inc A String.
Parameters: includesAllowed includesAllowed True if Includes are allowed.
Parameters: layout the new layout object; can be null, then a new layout object will be created
Since: 1.3
Unescapes any Java literals found in the String
to a
Writer
.
Parameters: str the String
to unescape, may be null delimiter the delimiter for multi-valued properties
Returns: the processed string
Throws: IllegalArgumentException if the Writer is null