org.apache.commons.configuration.PropertiesConfiguration Maven / Gradle / Ivy
Show all versions of commons-configuration Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.configuration;
import java.io.File;
import java.io.FilterWriter;
import java.io.IOException;
import java.io.LineNumberReader;
import java.io.Reader;
import java.io.Writer;
import java.net.URL;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import org.apache.commons.lang.ArrayUtils;
import org.apache.commons.lang.StringEscapeUtils;
import org.apache.commons.lang.StringUtils;
/**
* 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, basically it follows
* the syntax of the stream parsed by {@link 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 {@link 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. Note:
* When the configuration file is written back to disk the associated
*
{@link PropertiesConfigurationLayout} object (see below) will
* try to preserve as much of the original format as possible, i.e. properties
* with multiple values defined on a single line will also be written back on
* a single line, and multiple occurrences of a single key will be written on
* multiple lines. If the addProperty() method was called
* multiple times for adding multiple values to a property, these properties
* will per default be written on multiple lines in the output file, too.
* Some options of the PropertiesConfigurationLayout class have
* influence on that behavior.
*
* -
* 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 {@link 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.
*
Note:Configuration objects of this type can be read concurrently
* by multiple threads. However if one of these threads modifies the object,
* synchronization has to be performed manually.
*
* @see 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 1162387 2011-08-27 16:05:20Z oheger $
*/
public class PropertiesConfiguration extends AbstractFileConfiguration
{
/** Constant for the supported comment characters.*/
static final String COMMENT_CHARS = "#!";
/** Constant for the default properties separator.*/
static final String DEFAULT_SEPARATOR = " = ";
/**
* Constant for the default IOFactory. This instance is used
* when no specific factory was set.
*/
private static final IOFactory DEFAULT_IO_FACTORY = new DefaultIOFactory();
/**
* This is the name of the property that can point to other
* properties file for including other properties files.
*/
private static String include = "include";
/** The list of possible key/value separators */
private static final char[] SEPARATORS = new char[] {'=', ':'};
/** The white space characters used as key/value separators. */
private static final char[] WHITE_SPACE = new char[]{' ', '\t', '\f'};
/**
* The default encoding (ISO-8859-1 as specified by
* http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html)
*/
private static final String DEFAULT_ENCODING = "ISO-8859-1";
/** Constant for the platform specific line separator.*/
private static final String LINE_SEPARATOR = System.getProperty("line.separator");
/** Constant for the escaping character.*/
private static final String ESCAPE = "\\";
/** Constant for the escaped escaping character.*/
private static final String DOUBLE_ESC = ESCAPE + ESCAPE;
/** Constant for the radix of hex numbers.*/
private static final int HEX_RADIX = 16;
/** Constant for the length of a unicode literal.*/
private static final int UNICODE_LEN = 4;
/** Stores the layout object.*/
private PropertiesConfigurationLayout layout;
/** The IOFactory for creating readers and writers.*/
private volatile IOFactory ioFactory;
/** Allow file inclusion or not */
private boolean includesAllowed;
/**
* Creates an empty PropertyConfiguration object which can be
* used to synthesize a new Properties file by adding values and
* then saving().
*/
public PropertiesConfiguration()
{
layout = createLayout();
setIncludesAllowed(false);
}
/**
* 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.
*
* @param fileName The name of the properties file to load.
* @throws ConfigurationException Error while loading the properties file
*/
public PropertiesConfiguration(String fileName) throws ConfigurationException
{
super(fileName);
}
/**
* 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. If the file does not exist,
* an empty configuration will be created. Later the save()
* method can be called to save the properties to the specified file.
*
* @param file The properties file to load.
* @throws ConfigurationException Error while loading the properties file
*/
public PropertiesConfiguration(File file) throws ConfigurationException
{
super(file);
// If the file does not exist, no layout object was created. We have to
// do this manually in this case.
getLayout();
}
/**
* 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.
*
* @param url The location of the properties file to load.
* @throws ConfigurationException Error while loading the properties file
*/
public PropertiesConfiguration(URL url) throws ConfigurationException
{
super(url);
}
/**
* Gets the property value for including other properties files.
* By default it is "include".
*
* @return A String.
*/
public static String getInclude()
{
return PropertiesConfiguration.include;
}
/**
* Sets the property value for including other properties files.
* By default it is "include".
*
* @param inc A String.
*/
public static void setInclude(String inc)
{
PropertiesConfiguration.include = inc;
}
/**
* 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.
*
* @param includesAllowed includesAllowed True if Includes are allowed.
*/
protected void setIncludesAllowed(boolean includesAllowed)
{
this.includesAllowed = includesAllowed;
}
/**
* Reports the status of file inclusion.
*
* @return True if include files are loaded.
*/
public boolean getIncludesAllowed()
{
return this.includesAllowed;
}
/**
* Return the comment header.
*
* @return the comment header
* @since 1.1
*/
public String getHeader()
{
return getLayout().getHeaderComment();
}
/**
* Set the comment header.
*
* @param header the header to use
* @since 1.1
*/
public void setHeader(String header)
{
getLayout().setHeaderComment(header);
}
/**
* Returns the encoding to be used when loading or storing configuration
* data. This implementation ensures that the default encoding will be used
* if none has been set explicitly.
*
* @return the encoding
*/
public String getEncoding()
{
String enc = super.getEncoding();
return (enc != null) ? enc : DEFAULT_ENCODING;
}
/**
* Returns the associated layout object.
*
* @return the associated layout object
* @since 1.3
*/
public synchronized PropertiesConfigurationLayout getLayout()
{
if (layout == null)
{
layout = createLayout();
}
return layout;
}
/**
* Sets the associated layout object.
*
* @param layout the new layout object; can be null, then a new
* layout object will be created
* @since 1.3
*/
public synchronized void setLayout(PropertiesConfigurationLayout layout)
{
// only one layout must exist
if (this.layout != null)
{
removeConfigurationListener(this.layout);
}
if (layout == null)
{
this.layout = createLayout();
}
else
{
this.layout = layout;
}
}
/**
* Creates the associated layout object. This method is invoked when the
* layout object is accessed and has not been created yet. Derived classes
* can override this method to hook in a different layout implementation.
*
* @return the layout object to use
* @since 1.3
*/
protected PropertiesConfigurationLayout createLayout()
{
return new PropertiesConfigurationLayout(this);
}
/**
* Returns the IOFactory to be used for creating readers and
* writers when loading or saving this configuration.
*
* @return the IOFactory
* @since 1.7
*/
public IOFactory getIOFactory()
{
return (ioFactory != null) ? ioFactory : DEFAULT_IO_FACTORY;
}
/**
* Sets the IOFactory to be used for creating readers and
* writers when loading or saving this configuration. Using this method a
* client can customize the reader and writer classes used by the load and
* save operations. Note that this method must be called before invoking
* one of the load() and save() methods.
* Especially, if you want to use a custom IOFactory for
* changing the PropertiesReader, you cannot load the
* configuration data in the constructor.
*
* @param ioFactory the new IOFactory (must not be null)
* @throws IllegalArgumentException if the IOFactory is
* null
* @since 1.7
*/
public void setIOFactory(IOFactory ioFactory)
{
if (ioFactory == null)
{
throw new IllegalArgumentException("IOFactory must not be null!");
}
this.ioFactory = ioFactory;
}
/**
* 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.
*
* @param in An InputStream.
*
* @throws ConfigurationException if an error occurs
*/
public synchronized void load(Reader in) throws ConfigurationException
{
boolean oldAutoSave = isAutoSave();
setAutoSave(false);
try
{
getLayout().load(in);
}
finally
{
setAutoSave(oldAutoSave);
}
}
/**
* Save the configuration to the specified stream.
*
* @param writer the output stream used to save the configuration
* @throws ConfigurationException if an error occurs
*/
public void save(Writer writer) throws ConfigurationException
{
enterNoReload();
try
{
getLayout().save(writer);
}
finally
{
exitNoReload();
}
}
/**
* Extend the setBasePath method to turn includes
* on and off based on the existence of a base path.
*
* @param basePath The new basePath to set.
*/
public void setBasePath(String basePath)
{
super.setBasePath(basePath);
setIncludesAllowed(StringUtils.isNotEmpty(basePath));
}
/**
* Creates a copy of this object.
*
* @return the copy
*/
public Object clone()
{
PropertiesConfiguration copy = (PropertiesConfiguration) super.clone();
if (layout != null)
{
copy.setLayout(new PropertiesConfigurationLayout(copy, layout));
}
return copy;
}
/**
* This method is invoked by the associated
* {@link 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.
*
* @param key the property key
* @param value the property value
* @return a flag whether this is a normal property
* @throws ConfigurationException if an error occurs
* @since 1.3
*/
boolean propertyLoaded(String key, String value)
throws ConfigurationException
{
boolean result;
if (StringUtils.isNotEmpty(getInclude())
&& key.equalsIgnoreCase(getInclude()))
{
if (getIncludesAllowed())
{
String[] files;
if (!isDelimiterParsingDisabled())
{
files = StringUtils.split(value, getListDelimiter());
}
else
{
files = new String[]{value};
}
for (int i = 0; i < files.length; i++)
{
loadIncludeFile(interpolate(files[i].trim()));
}
}
result = false;
}
else
{
addProperty(key, value);
result = true;
}
return result;
}
/**
* Tests whether a line is a comment, i.e. whether it starts with a comment
* character.
*
* @param line the line
* @return a flag if this is a comment line
* @since 1.3
*/
static boolean isCommentLine(String line)
{
String s = line.trim();
// blanc lines are also treated as comment lines
return s.length() < 1 || COMMENT_CHARS.indexOf(s.charAt(0)) >= 0;
}
/**
* Returns the number of trailing backslashes. This is sometimes needed for
* the correct handling of escape characters.
*
* @param line the string to investigate
* @return the number of trailing backslashes
*/
private static int countTrailingBS(String line)
{
int bsCount = 0;
for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--)
{
bsCount++;
}
return bsCount;
}
/**
* This class is used to read properties lines. These lines do
* not terminate with new-line chars but rather when there is no
* backslash sign a the end of the line. This is used to
* concatenate multiple lines for readability.
*/
public static class PropertiesReader extends LineNumberReader
{
/** Stores the comment lines for the currently processed property.*/
private List commentLines;
/** Stores the name of the last read property.*/
private String propertyName;
/** Stores the value of the last read property.*/
private String propertyValue;
/** Stores the property separator of the last read property.*/
private String propertySeparator = DEFAULT_SEPARATOR;
/** Stores the list delimiter character.*/
private char delimiter;
/**
* Constructor.
*
* @param reader A Reader.
*/
public PropertiesReader(Reader reader)
{
this(reader, AbstractConfiguration.getDefaultListDelimiter());
}
/**
* Creates a new instance of PropertiesReader and sets
* the underlying reader and the list delimiter.
*
* @param reader the reader
* @param listDelimiter the list delimiter character
* @since 1.3
*/
public PropertiesReader(Reader reader, char listDelimiter)
{
super(reader);
commentLines = new ArrayList();
delimiter = listDelimiter;
}
/**
* Reads a property line. Returns null if Stream is
* at EOF. Concatenates lines ending with "\".
* Skips lines beginning with "#" or "!" and empty lines.
* The return value is a property definition (<name>
* = <value>)
*
* @return A string containing a property value or null
*
* @throws IOException in case of an I/O error
*/
public String readProperty() throws IOException
{
commentLines.clear();
StringBuffer buffer = new StringBuffer();
while (true)
{
String line = readLine();
if (line == null)
{
// EOF
return null;
}
if (isCommentLine(line))
{
commentLines.add(line);
continue;
}
line = line.trim();
if (checkCombineLines(line))
{
line = line.substring(0, line.length() - 1);
buffer.append(line);
}
else
{
buffer.append(line);
break;
}
}
return buffer.toString();
}
/**
* Parses the next property from the input stream and stores the found
* name and value in internal fields. These fields can be obtained using
* the provided getter methods. The return value indicates whether EOF
* was reached (false) or whether further properties are
* available (true).
*
* @return a flag if further properties are available
* @throws IOException if an error occurs
* @since 1.3
*/
public boolean nextProperty() throws IOException
{
String line = readProperty();
if (line == null)
{
return false; // EOF
}
// parse the line
parseProperty(line);
return true;
}
/**
* Returns the comment lines that have been read for the last property.
*
* @return the comment lines for the last property returned by
* readProperty()
* @since 1.3
*/
public List getCommentLines()
{
return commentLines;
}
/**
* Returns the name of the last read property. This method can be called
* after {@link #nextProperty()} was invoked and its
* return value was true.
*
* @return the name of the last read property
* @since 1.3
*/
public String getPropertyName()
{
return propertyName;
}
/**
* Returns the value of the last read property. This method can be
* called after {@link #nextProperty()} was invoked and
* its return value was true.
*
* @return the value of the last read property
* @since 1.3
*/
public String getPropertyValue()
{
return propertyValue;
}
/**
* Returns the separator that was used for the last read property. The
* separator can be stored so that it can later be restored when saving
* the configuration.
*
* @return the separator for the last read property
* @since 1.7
*/
public String getPropertySeparator()
{
return propertySeparator;
}
/**
* Parses a line read from the properties file. This method is called
* for each non-comment line read from the source file. Its task is to
* split the passed in line into the property key and its value. The
* results of the parse operation can be stored by calling the
* initPropertyXXX() methods.
*
* @param line the line read from the properties file
* @since 1.7
*/
protected void parseProperty(String line)
{
String[] property = doParseProperty(line);
initPropertyName(property[0]);
initPropertyValue(property[1]);
initPropertySeparator(property[2]);
}
/**
* Sets the name of the current property. This method can be called by
* parseProperty() for storing the results of the parse
* operation. It also ensures that the property key is correctly
* escaped.
*
* @param name the name of the current property
* @since 1.7
*/
protected void initPropertyName(String name)
{
propertyName = StringEscapeUtils.unescapeJava(name);
}
/**
* Sets the value of the current property. This method can be called by
* parseProperty() for storing the results of the parse
* operation. It also ensures that the property value is correctly
* escaped.
*
* @param value the value of the current property
* @since 1.7
*/
protected void initPropertyValue(String value)
{
propertyValue = unescapeJava(value, delimiter);
}
/**
* Sets the separator of the current property. This method can be called
* by parseProperty(). It allows the associated layout
* object to keep track of the property separators. When saving the
* configuration the separators can be restored.
*
* @param value the separator used for the current property
* @since 1.7
*/
protected void initPropertySeparator(String value)
{
propertySeparator = value;
}
/**
* Checks if the passed in line should be combined with the following.
* This is true, if the line ends with an odd number of backslashes.
*
* @param line the line
* @return a flag if the lines should be combined
*/
private static boolean checkCombineLines(String line)
{
return countTrailingBS(line) % 2 != 0;
}
/**
* Parse a property line and return the key, the value, and the separator in an array.
*
* @param line the line to parse
* @return an array with the property's key, value, and separator
*/
private static String[] doParseProperty(String line)
{
// sorry for this spaghetti code, please replace it as soon as
// possible with a regexp when the Java 1.3 requirement is dropped
String[] result = new String[3];
StringBuffer key = new StringBuffer();
StringBuffer value = new StringBuffer();
StringBuffer separator = new StringBuffer();
// state of the automaton:
// 0: key parsing
// 1: antislash found while parsing the key
// 2: separator crossing
// 3: value parsing
int state = 0;
for (int pos = 0; pos < line.length(); pos++)
{
char c = line.charAt(pos);
switch (state)
{
case 0:
if (c == '\\')
{
state = 1;
}
else if (ArrayUtils.contains(WHITE_SPACE, c))
{
// switch to the separator crossing state
separator.append(c);
state = 2;
}
else if (ArrayUtils.contains(SEPARATORS, c))
{
// switch to the value parsing state
separator.append(c);
state = 3;
}
else
{
key.append(c);
}
break;
case 1:
if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c))
{
// this is an escaped separator or white space
key.append(c);
}
else
{
// another escaped character, the '\' is preserved
key.append('\\');
key.append(c);
}
// return to the key parsing state
state = 0;
break;
case 2:
if (ArrayUtils.contains(WHITE_SPACE, c) || ArrayUtils.contains(SEPARATORS, c))
{
// record the separator
separator.append(c);
}
else
{
// any other character indicates we encountered the beginning of the value
value.append(c);
// switch to the value parsing state
state = 3;
}
break;
case 3:
value.append(c);
break;
}
}
result[0] = key.toString().trim();
result[1] = value.toString().trim();
result[2] = separator.toString();
return result;
}
} // class PropertiesReader
/**
* This class is used to write properties lines. The most important method
* is writeProperty(String, Object, boolean), which is called
* during a save operation for each property found in the configuration.
*/
public static class PropertiesWriter extends FilterWriter
{
/** Constant for the initial size when creating a string buffer. */
private static final int BUF_SIZE = 8;
/** The delimiter for multi-valued properties.*/
private char delimiter;
/** The separator to be used for the current property. */
private String currentSeparator;
/** The global separator. If set, it overrides the current separator.*/
private String globalSeparator;
/** The line separator.*/
private String lineSeparator;
/**
* Constructor.
*
* @param writer a Writer object providing the underlying stream
* @param delimiter the delimiter character for multi-valued properties
*/
public PropertiesWriter(Writer writer, char delimiter)
{
super(writer);
this.delimiter = delimiter;
}
/**
* Returns the current property separator.
*
* @return the current property separator
* @since 1.7
*/
public String getCurrentSeparator()
{
return currentSeparator;
}
/**
* Sets the current property separator. This separator is used when
* writing the next property.
*
* @param currentSeparator the current property separator
* @since 1.7
*/
public void setCurrentSeparator(String currentSeparator)
{
this.currentSeparator = currentSeparator;
}
/**
* Returns the global property separator.
*
* @return the global property separator
* @since 1.7
*/
public String getGlobalSeparator()
{
return globalSeparator;
}
/**
* Sets the global property separator. This separator corresponds to the
* globalSeparator property of
* {@link PropertiesConfigurationLayout}. It defines the separator to be
* used for all properties. If it is undefined, the current separator is
* used.
*
* @param globalSeparator the global property separator
* @since 1.7
*/
public void setGlobalSeparator(String globalSeparator)
{
this.globalSeparator = globalSeparator;
}
/**
* Returns the line separator.
*
* @return the line separator
* @since 1.7
*/
public String getLineSeparator()
{
return (lineSeparator != null) ? lineSeparator : LINE_SEPARATOR;
}
/**
* Sets the line separator. Each line written by this writer is
* terminated with this separator. If not set, the platform-specific
* line separator is used.
*
* @param lineSeparator the line separator to be used
* @since 1.7
*/
public void setLineSeparator(String lineSeparator)
{
this.lineSeparator = lineSeparator;
}
/**
* Write a property.
*
* @param key the key of the property
* @param value the value of the property
*
* @throws IOException if an I/O error occurs
*/
public void writeProperty(String key, Object value) throws IOException
{
writeProperty(key, value, false);
}
/**
* Write a property.
*
* @param key The key of the property
* @param values The array of values of the property
*
* @throws IOException if an I/O error occurs
*/
public void writeProperty(String key, List values) throws IOException
{
for (int i = 0; i < values.size(); i++)
{
writeProperty(key, values.get(i));
}
}
/**
* Writes the given property and its value. If the value happens to be a
* list, the forceSingleLine flag is evaluated. If it is
* set, all values are written on a single line using the list delimiter
* as separator.
*
* @param key the property key
* @param value the property value
* @param forceSingleLine the "force single line" flag
* @throws IOException if an error occurs
* @since 1.3
*/
public void writeProperty(String key, Object value,
boolean forceSingleLine) throws IOException
{
String v;
if (value instanceof List)
{
List values = (List) value;
if (forceSingleLine)
{
v = makeSingleLineValue(values);
}
else
{
writeProperty(key, values);
return;
}
}
else
{
v = escapeValue(value, false);
}
write(escapeKey(key));
write(fetchSeparator(key, value));
write(v);
writeln(null);
}
/**
* Write a comment.
*
* @param comment the comment to write
* @throws IOException if an I/O error occurs
*/
public void writeComment(String comment) throws IOException
{
writeln("# " + comment);
}
/**
* Escape the separators in the key.
*
* @param key the key
* @return the escaped key
* @since 1.2
*/
private String escapeKey(String key)
{
StringBuffer newkey = new StringBuffer();
for (int i = 0; i < key.length(); i++)
{
char c = key.charAt(i);
if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c))
{
// escape the separator
newkey.append('\\');
newkey.append(c);
}
else
{
newkey.append(c);
}
}
return newkey.toString();
}
/**
* Escapes the given property value. Delimiter characters in the value
* will be escaped.
*
* @param value the property value
* @param inList a flag whether the value is part of a list
* @return the escaped property value
* @since 1.3
*/
private String escapeValue(Object value, boolean inList)
{
String escapedValue = handleBackslashs(value, inList);
if (delimiter != 0)
{
escapedValue = StringUtils.replace(escapedValue, String.valueOf(delimiter), ESCAPE + delimiter);
}
return escapedValue;
}
/**
* Performs the escaping of backslashes in the specified properties
* value. Because a double backslash is used to escape the escape
* character of a list delimiter, double backslashes also have to be
* escaped if the property is part of a (single line) list. Then, in all
* cases each backslash has to be doubled in order to produce a valid
* properties file.
*
* @param value the value to be escaped
* @param inList a flag whether the value is part of a list
* @return the value with escaped backslashes as string
*/
private String handleBackslashs(Object value, boolean inList)
{
String strValue = String.valueOf(value);
if (inList && strValue.indexOf(DOUBLE_ESC) >= 0)
{
char esc = ESCAPE.charAt(0);
StringBuffer buf = new StringBuffer(strValue.length() + BUF_SIZE);
for (int i = 0; i < strValue.length(); i++)
{
if (strValue.charAt(i) == esc && i < strValue.length() - 1
&& strValue.charAt(i + 1) == esc)
{
buf.append(DOUBLE_ESC).append(DOUBLE_ESC);
i++;
}
else
{
buf.append(strValue.charAt(i));
}
}
strValue = buf.toString();
}
return StringEscapeUtils.escapeJava(strValue);
}
/**
* Transforms a list of values into a single line value.
*
* @param values the list with the values
* @return a string with the single line value (can be null)
* @since 1.3
*/
private String makeSingleLineValue(List values)
{
if (!values.isEmpty())
{
Iterator it = values.iterator();
String lastValue = escapeValue(it.next(), true);
StringBuffer buf = new StringBuffer(lastValue);
while (it.hasNext())
{
// if the last value ended with an escape character, it has
// to be escaped itself; otherwise the list delimiter will
// be escaped
if (lastValue.endsWith(ESCAPE) && (countTrailingBS(lastValue) / 2) % 2 != 0)
{
buf.append(ESCAPE).append(ESCAPE);
}
buf.append(delimiter);
lastValue = escapeValue(it.next(), true);
buf.append(lastValue);
}
return buf.toString();
}
else
{
return null;
}
}
/**
* Helper method for writing a line with the platform specific line
* ending.
*
* @param s the content of the line (may be null)
* @throws IOException if an error occurs
* @since 1.3
*/
public void writeln(String s) throws IOException
{
if (s != null)
{
write(s);
}
write(getLineSeparator());
}
/**
* Returns the separator to be used for the given property. This method
* is called by writeProperty(). The string returned here
* is used as separator between the property key and its value. Per
* default the method checks whether a global separator is set. If this
* is the case, it is returned. Otherwise the separator returned by
* getCurrentSeparator() is used, which was set by the
* associated layout object. Derived classes may implement a different
* strategy for defining the separator.
*
* @param key the property key
* @param value the value
* @return the separator to be used
* @since 1.7
*/
protected String fetchSeparator(String key, Object value)
{
return (getGlobalSeparator() != null) ? getGlobalSeparator()
: getCurrentSeparator();
}
} // class PropertiesWriter
/**
*
* Definition of an interface that allows customization of read and write
* operations.
*
*
* For reading and writing properties files the inner classes
* PropertiesReader and PropertiesWriter are used.
* This interface defines factory methods for creating both a
* PropertiesReader and a PropertiesWriter. An
* object implementing this interface can be passed to the
* setIOFactory() method of
* PropertiesConfiguration. Every time the configuration is
* read or written the IOFactory is asked to create the
* appropriate reader or writer object. This provides an opportunity to
* inject custom reader or writer implementations.
*
*
* @since 1.7
*/
public interface IOFactory
{
/**
* Creates a PropertiesReader for reading a properties
* file. This method is called whenever the
* PropertiesConfiguration is loaded. The reader returned
* by this method is then used for parsing the properties file.
*
* @param in the underlying reader (of the properties file)
* @param delimiter the delimiter character for list parsing
* @return the PropertiesReader for loading the
* configuration
*/
PropertiesReader createPropertiesReader(Reader in, char delimiter);
/**
* Creates a PropertiesWriter for writing a properties
* file. This method is called before the
* PropertiesConfiguration is saved. The writer returned by
* this method is then used for writing the properties file.
*
* @param out the underlying writer (to the properties file)
* @param delimiter the delimiter character for list parsing
* @return the PropertiesWriter for saving the
* configuration
*/
PropertiesWriter createPropertiesWriter(Writer out, char delimiter);
}
/**
*
* A default implementation of the IOFactory interface.
*
*
* This class implements the createXXXX() methods defined by
* the IOFactory interface in a way that the default objects
* (i.e. PropertiesReader and PropertiesWriter are
* returned. Customizing either the reader or the writer (or both) can be
* done by extending this class and overriding the corresponding
* createXXXX() method.
*
*
* @since 1.7
*/
public static class DefaultIOFactory implements IOFactory
{
public PropertiesReader createPropertiesReader(Reader in, char delimiter)
{
return new PropertiesReader(in, delimiter);
}
public PropertiesWriter createPropertiesWriter(Writer out,
char delimiter)
{
return new PropertiesWriter(out, 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 separators (i.e '\,').
*
* @param str the String to unescape, may be null
* @param delimiter the delimiter for multi-valued properties
* @return the processed string
* @throws IllegalArgumentException if the Writer is null
*/
protected static String unescapeJava(String str, char delimiter)
{
if (str == null)
{
return null;
}
int sz = str.length();
StringBuffer out = new StringBuffer(sz);
StringBuffer unicode = new StringBuffer(UNICODE_LEN);
boolean hadSlash = false;
boolean inUnicode = false;
for (int i = 0; i < sz; i++)
{
char ch = str.charAt(i);
if (inUnicode)
{
// if in unicode, then we're reading unicode
// values in somehow
unicode.append(ch);
if (unicode.length() == UNICODE_LEN)
{
// unicode now contains the four hex digits
// which represents our unicode character
try
{
int value = Integer.parseInt(unicode.toString(), HEX_RADIX);
out.append((char) value);
unicode.setLength(0);
inUnicode = false;
hadSlash = false;
}
catch (NumberFormatException nfe)
{
throw new ConfigurationRuntimeException("Unable to parse unicode value: " + unicode, nfe);
}
}
continue;
}
if (hadSlash)
{
// handle an escaped value
hadSlash = false;
if (ch == '\\')
{
out.append('\\');
}
else if (ch == '\'')
{
out.append('\'');
}
else if (ch == '\"')
{
out.append('"');
}
else if (ch == 'r')
{
out.append('\r');
}
else if (ch == 'f')
{
out.append('\f');
}
else if (ch == 't')
{
out.append('\t');
}
else if (ch == 'n')
{
out.append('\n');
}
else if (ch == 'b')
{
out.append('\b');
}
else if (ch == delimiter)
{
out.append('\\');
out.append(delimiter);
}
else if (ch == 'u')
{
// uh-oh, we're in unicode country....
inUnicode = true;
}
else
{
out.append(ch);
}
continue;
}
else if (ch == '\\')
{
hadSlash = true;
continue;
}
out.append(ch);
}
if (hadSlash)
{
// then we're in the weird case of a \ at the end of the
// string, let's output it anyway.
out.append('\\');
}
return out.toString();
}
/**
* Helper method for loading an included properties file. This method is
* called by 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.
*
* @param fileName the name of the file to load
* @throws ConfigurationException if loading fails
*/
private void loadIncludeFile(String fileName) throws ConfigurationException
{
URL url = ConfigurationUtils.locate(getFileSystem(), getBasePath(), fileName);
if (url == null)
{
URL baseURL = getURL();
if (baseURL != null)
{
url = ConfigurationUtils.locate(getFileSystem(), baseURL.toString(), fileName);
}
}
if (url == null)
{
throw new ConfigurationException("Cannot resolve include file "
+ fileName);
}
load(url);
}
}