org.apache.commons.configuration
Class PropertiesConfiguration

java.lang.Object
  org.apache.commons.configuration.AbstractConfiguration
      org.apache.commons.configuration.BaseConfiguration
          org.apache.commons.configuration.AbstractFileConfiguration
              org.apache.commons.configuration.PropertiesConfiguration

All Implemented Interfaces:

Configuration, FileConfiguration

Direct Known Subclasses:

XMLPropertiesConfiguration

public class PropertiesConfiguration

extends AbstractFileConfiguration

This is the "classic" Properties loader which loads the values from a single or multiple files (which can be chained with "include =". All given path references are either absolute or relative to the file name supplied in the constructor.

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:

• Each property has the syntax key = value
• The key may use any character but the equal sign '='.
• value may be separated on different lines if a backslash is placed at the end of the line that continues below.
• If value is a list of strings, each token is separated by a comma ',' by default.
• 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 '#' 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.excaped = Hi\, what'up?

      # properties can reference other properties
      base.prop = /base
      first.prop = ${base.prop}/first
      second.prop = ${first.prop}/second
 

Version:

$Id: PropertiesConfiguration.java 156237 2005-03-05 10:26:22Z oheger $

Author:

Emmanuel Bourg, Stefano Mazzocchi, Jon S. Stevens, Dave Bryson, Geir Magnusson Jr., Leon Messerschmidt, Kent Johnson, Daniel Rall, Ilkka Priha, Jason van Zyl, Martin Poeschl, Henning P. Schmiedehausen, Eric Pugh, Oliver Heger

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

Fields inherited from class org.apache.commons.configuration.AbstractFileConfiguration

autoSave, basePath, fileName, strategy

Fields inherited from class org.apache.commons.configuration.AbstractConfiguration

END_TOKEN, START_TOKEN

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(File file)
Creates and loads the extended properties from the specified file.

PropertiesConfiguration(String fileName)
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

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.
void	load(Reader in) Load the properties from the given reader.
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 = statement or not.
protected static String	unescapeJava(String str, char delimiter) Unescapes any Java literals found in the String to a Writer.

Methods inherited from class org.apache.commons.configuration.AbstractFileConfiguration

addPropertyDirect, clearProperty, containsKey, getBasePath, getEncoding, getFile, getFileName, getKeys, getPath, getProperty, getReloadingStrategy, getURL, isAutoSave, isEmpty, load, load, load, load, load, load, possiblySave, reload, save, save, save, save, save, save, setAutoSave, setEncoding, setFile, setFileName, setPath, setReloadingStrategy, setURL

Methods inherited from class org.apache.commons.configuration.BaseConfiguration

clear

Methods inherited from class org.apache.commons.configuration.AbstractConfiguration

addProperty, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getList, getList, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolateHelper, isThrowExceptionOnMissing, resolveContainerStore, setDelimiter, setProperty, setThrowExceptionOnMissing, subset

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.commons.configuration.Configuration

addProperty, clear, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, setProperty, subset

Constructor Detail

PropertiesConfiguration

public PropertiesConfiguration()

Creates an empty PropertyConfiguration object which can be used to synthesize a new Properties file by adding values and then saving(). An object constructed by this C'tor can not be tickled into loading included files because it cannot supply a base for relative includes.

PropertiesConfiguration

public PropertiesConfiguration(String fileName)
                        throws ConfigurationException

Creates and loads the extended properties from the specified file. The specified file can contain "include = " properties which then are loaded and merged into the properties.

Parameters:

fileName - The name of the properties file to load.

Throws:

ConfigurationException - Error while loading the properties file

PropertiesConfiguration

public PropertiesConfiguration(File file)
                        throws ConfigurationException

Creates and loads the extended properties from the specified file. The specified file can contain "include = " properties which then are loaded and merged into the properties.

Parameters:

file - The properties file to load.

Throws:

ConfigurationException - Error while loading the properties file

PropertiesConfiguration

public PropertiesConfiguration(URL url)
                        throws ConfigurationException

Creates and loads the extended properties from the specified URL. The specified file can contain "include = " properties which then are loaded and merged into the properties.

Parameters:

url - The location of the properties file to load.

Throws:

ConfigurationException - Error while loading the properties file

Method Detail

getInclude

public static String getInclude()

Gets the property value for including other properties files. By default it is "include".

Returns:

A String.

setInclude

public static void setInclude(String inc)

Sets the property value for including other properties files. By default it is "include".

Parameters:

inc - A String.

setIncludesAllowed

protected void setIncludesAllowed(boolean includesAllowed)

Controls whether additional files can be loaded by the include = statement or not. Base rule is, that objects created by the empty C'tor can not have included files.

Parameters:

includesAllowed - includesAllowed True if Includes are allowed.

getIncludesAllowed

public boolean getIncludesAllowed()

Reports the status of file inclusion.

Returns:

True if include files are loaded.

getHeader

public String getHeader()

Return the comment header.

Since:

1.1

setHeader

public void setHeader(String header)

Set the comment header.

Since:

1.1

load

public void load(Reader in)
          throws ConfigurationException

Load the properties from the given reader. Note that the 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

save

public void save(Writer writer)
          throws ConfigurationException

Save the configuration to the specified stream.

Parameters:

writer - the output stream used to save the configuration

Throws:

ConfigurationException

setBasePath

public void setBasePath(String basePath)

Extend the setBasePath method to turn includes on and off based on the existence of a base path.

Specified by:

setBasePath in interface FileConfiguration

Overrides:

setBasePath in class AbstractFileConfiguration

Parameters:

basePath - The new basePath to set.

unescapeJava

protected static String unescapeJava(String str,
                                     char delimiter)

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

This is a slightly modified version of the StringEscapeUtils.unescapeJava() function in commons-lang that doesn't drop escaped commas (i.e '\,').

Parameters:

str - the String to unescape, may be null

Throws:

IllegalArgumentException - if the Writer is null