org.apache.commons.configuration
Class BasePropertiesConfiguration

java.lang.Object
  org.apache.commons.configuration.AbstractConfiguration
      org.apache.commons.configuration.BaseConfiguration
          org.apache.commons.configuration.BasePathConfiguration
              org.apache.commons.configuration.BasePropertiesConfiguration

All Implemented Interfaces:

BasePathLoader, Configuration

Direct Known Subclasses:

ClassPropertiesConfiguration, PropertiesConfiguration

public abstract class BasePropertiesConfiguration

extends BasePathConfiguration

loads the configuration from a properties 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 ','.
• 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 ConfigurationsRepository. 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. Duplicate name values will be replaced, so be careful.

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: BasePropertiesConfiguration.java,v 1.13 2004/06/23 11:15:45 ebourg Exp $

Field Summary

protected static String

include This is the name of the property that can point to other properties file for including other properties files.

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

DELIMITER, END_TOKEN, START_TOKEN

Constructor Summary

BasePropertiesConfiguration()

Method Summary

String	getInclude() Gets the property value for including other properties files.
boolean	getIncludesAllowed() Reports the status of file inclusion.
protected abstract InputStream	getPropertyStream(String resourceName) Implementations of this class must implement this method.
void	load(InputStream input) Load the properties from the given input stream.
void	load(InputStream input, String encoding) Load the properties from the given input stream and using the specified encoding.
void	save(OutputStream out) Save the configuration to the specified stream.
void	save(OutputStream out, String encoding) Save the configuration to the specified stream.
void	save(String filename) Save the configuration to a file.
void	save(Writer writer) Save the configuration to the specified stream.
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) Unescapes any Java literals found in the String to a Writer.

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

getBasePath, setBasePath

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

addPropertyDirect, clearProperty, containsKey, getKeys, getPropertyDirect, isEmpty

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

addProperty, 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, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolateHelper, setProperty, split, subset

Methods inherited from class java.lang.Object

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

Field Detail

include

protected static String include

This is the name of the property that can point to other properties file for including other properties files.

Constructor Detail

BasePropertiesConfiguration

public BasePropertiesConfiguration()

Method Detail

getPropertyStream

protected abstract InputStream getPropertyStream(String resourceName)
                                          throws IOException

Implementations of this class must implement this method.

Parameters:

resourceName - The Resource to load

Returns:

An Input Stream

Throws:

IOException - Error while loading the properties file

load

public void load(InputStream input)
          throws ConfigurationException

Load the properties from the given input stream.

Parameters:

input - An InputStream.

Throws:

ConfigurationException

load

public void load(InputStream input,
                 String encoding)
          throws ConfigurationException

Load the properties from the given input stream and using the specified encoding.

Parameters:

input - An InputStream.

encoding - An encoding.

Throws:

ConfigurationException

save

public void save(String filename)
          throws ConfigurationException

Save the configuration to a file. Properties with multiple values are saved on multiple lines, one value per line.

Parameters:

filename - the name of the properties file

Throws:

ConfigurationException

save

public void save(OutputStream out)
          throws IOException

Save the configuration to the specified stream.

Parameters:

out - the output stream used to save the configuration

Throws:

IOException

save

public void save(OutputStream out,
                 String encoding)
          throws IOException

Save the configuration to the specified stream.

Parameters:

out - the output stream used to save the configuration

encoding - the charset used to write the configuration

Throws:

IOException

save

public void save(Writer writer)
          throws IOException

Save the configuration to the specified stream.

Parameters:

writer - the output stream used to save the configuration

Throws:

IOException

getInclude

public String getInclude()

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

Returns:

A String.

setInclude

public 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.

unescapeJava

protected static String unescapeJava(String str)

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