org.apache.commons.configuration.PropertiesConfigurationLayout Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-configuration Show documentation
Show all versions of commons-configuration Show documentation
Tools to assist in the reading of configuration/preferences files in
various formats
/*
* 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.IOException;
import java.io.Reader;
import java.io.Writer;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.apache.commons.collections.map.LinkedMap;
import org.apache.commons.configuration.event.ConfigurationEvent;
import org.apache.commons.configuration.event.ConfigurationListener;
import org.apache.commons.lang.StringUtils;
/**
*
* A helper class used by {@link PropertiesConfiguration} to keep
* the layout of a properties file.
*
*
* Instances of this class are associated with a
* PropertiesConfiguration object. They are responsible for
* analyzing properties files and for extracting as much information about the
* file layout (e.g. empty lines, comments) as possible. When the properties
* file is written back again it should be close to the original.
*
*
* The PropertiesConfigurationLayout object associated with a
* PropertiesConfiguration object can be obtained using the
* getLayout() method of the configuration. Then the methods
* provided by this class can be used to alter the properties file's layout.
*
*
* Implementation note: This is a very simple implementation, which is far away
* from being perfect, i.e. the original layout of a properties file won't be
* reproduced in all cases. One limitation is that comments for multi-valued
* property keys are concatenated. Maybe this implementation can later be
* improved.
*
*
* To get an impression how this class works consider the following properties
* file:
*
*
*
*
* # A demo configuration file
* # for Demo App 1.42
*
* # Application name
* AppName=Demo App
*
* # Application vendor
* AppVendor=DemoSoft
*
*
* # GUI properties
* # Window Color
* windowColors=0xFFFFFF,0x000000
*
* # Include some setting
* include=settings.properties
* # Another vendor
* AppVendor=TestSoft
*
*
*
*
* For this example the following points are relevant:
*
*
*
* - The first two lines are set as header comment. The header comment is
* determined by the last blanc line before the first property definition.
* - For the property
AppName one comment line and one
* leading blanc line is stored.
* - For the property
windowColors two comment lines and two
* leading blanc lines are stored.
* - Include files is something this class cannot deal with well. When saving
* the properties configuration back, the included properties are simply
* contained in the original file. The comment before the include property is
* skipped.
* - For all properties except for
AppVendor the "single
* line" flag is set. This is relevant only for windowColors,
* which has multiple values defined in one line using the separator character.
* - The
AppVendor property appears twice. The comment lines
* are concatenated, so that layout.getComment("AppVendor"); will
* result in Application vendor<CR>Another vendor, whith
* <CR> meaning the line separator. In addition the
* "single line" flag is set to false for this property. When
* the file is saved, two property definitions will be written (in series).
*
*
*
* @author Commons
* Configuration team
* @version $Id: PropertiesConfigurationLayout.java 759750 2009-03-29 19:15:36Z oheger $
* @since 1.3
*/
public class PropertiesConfigurationLayout implements ConfigurationListener
{
/** Constant for the line break character. */
private static final String CR = "\n";
/** Constant for the default comment prefix. */
private static final String COMMENT_PREFIX = "# ";
/** Stores the associated configuration object. */
private PropertiesConfiguration configuration;
/** Stores a map with the contained layout information. */
private Map layoutData;
/** Stores the header comment. */
private String headerComment;
/** The global separator that will be used for all properties. */
private String globalSeparator;
/** The line separator.*/
private String lineSeparator;
/** A counter for determining nested load calls. */
private int loadCounter;
/** Stores the force single line flag. */
private boolean forceSingleLine;
/**
* Creates a new instance of PropertiesConfigurationLayout
* and initializes it with the associated configuration object.
*
* @param config the configuration (must not be null)
*/
public PropertiesConfigurationLayout(PropertiesConfiguration config)
{
this(config, null);
}
/**
* Creates a new instance of PropertiesConfigurationLayout
* and initializes it with the given configuration object. The data of the
* specified layout object is copied.
*
* @param config the configuration (must not be null)
* @param c the layout object to be copied
*/
public PropertiesConfigurationLayout(PropertiesConfiguration config,
PropertiesConfigurationLayout c)
{
if (config == null)
{
throw new IllegalArgumentException(
"Configuration must not be null!");
}
configuration = config;
layoutData = new LinkedMap();
config.addConfigurationListener(this);
if (c != null)
{
copyFrom(c);
}
}
/**
* Returns the associated configuration object.
*
* @return the associated configuration
*/
public PropertiesConfiguration getConfiguration()
{
return configuration;
}
/**
* Returns the comment for the specified property key in a canonical form.
* "Canonical" means that either all lines start with a comment
* character or none. If the commentChar parameter is false,
* all comment characters are removed, so that the result is only the plain
* text of the comment. Otherwise it is ensured that each line of the
* comment starts with a comment character. Also, line breaks in the comment
* are normalized to the line separator "\n".
*
* @param key the key of the property
* @param commentChar determines whether all lines should start with comment
* characters or not
* @return the canonical comment for this key (can be null)
*/
public String getCanonicalComment(String key, boolean commentChar)
{
String comment = getComment(key);
if (comment == null)
{
return null;
}
else
{
return trimComment(comment, commentChar);
}
}
/**
* Returns the comment for the specified property key. The comment is
* returned as it was set (either manually by calling
* setComment() or when it was loaded from a properties
* file). No modifications are performed.
*
* @param key the key of the property
* @return the comment for this key (can be null)
*/
public String getComment(String key)
{
return fetchLayoutData(key).getComment();
}
/**
* Sets the comment for the specified property key. The comment (or its
* single lines if it is a multi-line comment) can start with a comment
* character. If this is the case, it will be written without changes.
* Otherwise a default comment character is added automatically.
*
* @param key the key of the property
* @param comment the comment for this key (can be null, then the
* comment will be removed)
*/
public void setComment(String key, String comment)
{
fetchLayoutData(key).setComment(comment);
}
/**
* Returns the number of blanc lines before this property key. If this key
* does not exist, 0 will be returned.
*
* @param key the property key
* @return the number of blanc lines before the property definition for this
* key
*/
public int getBlancLinesBefore(String key)
{
return fetchLayoutData(key).getBlancLines();
}
/**
* Sets the number of blanc lines before the given property key. This can be
* used for a logical grouping of properties.
*
* @param key the property key
* @param number the number of blanc lines to add before this property
* definition
*/
public void setBlancLinesBefore(String key, int number)
{
fetchLayoutData(key).setBlancLines(number);
}
/**
* Returns the header comment of the represented properties file in a
* canonical form. With the commentChar parameter it can be
* specified whether comment characters should be stripped or be always
* present.
*
* @param commentChar determines the presence of comment characters
* @return the header comment (can be null)
*/
public String getCanonicalHeaderComment(boolean commentChar)
{
return (getHeaderComment() == null) ? null : trimComment(
getHeaderComment(), commentChar);
}
/**
* Returns the header comment of the represented properties file. This
* method returns the header comment exactly as it was set using
* setHeaderComment() or extracted from the loaded properties
* file.
*
* @return the header comment (can be null)
*/
public String getHeaderComment()
{
return headerComment;
}
/**
* Sets the header comment for the represented properties file. This comment
* will be output on top of the file.
*
* @param comment the comment
*/
public void setHeaderComment(String comment)
{
headerComment = comment;
}
/**
* Returns a flag whether the specified property is defined on a single
* line. This is meaningful only if this property has multiple values.
*
* @param key the property key
* @return a flag if this property is defined on a single line
*/
public boolean isSingleLine(String key)
{
return fetchLayoutData(key).isSingleLine();
}
/**
* Sets the "single line flag" for the specified property key.
* This flag is evaluated if the property has multiple values (i.e. if it is
* a list property). In this case, if the flag is set, all values will be
* written in a single property definition using the list delimiter as
* separator. Otherwise multiple lines will be written for this property,
* each line containing one property value.
*
* @param key the property key
* @param f the single line flag
*/
public void setSingleLine(String key, boolean f)
{
fetchLayoutData(key).setSingleLine(f);
}
/**
* Returns the "force single line" flag.
*
* @return the force single line flag
* @see #setForceSingleLine(boolean)
*/
public boolean isForceSingleLine()
{
return forceSingleLine;
}
/**
* Sets the "force single line" flag. If this flag is set, all
* properties with multiple values are written on single lines. This mode
* provides more compatibility with java.lang.Properties,
* which cannot deal with multiple definitions of a single property. This
* mode has no effect if the list delimiter parsing is disabled.
*
* @param f the force single line flag
*/
public void setForceSingleLine(boolean f)
{
forceSingleLine = f;
}
/**
* Returns the separator for the property with the given key.
*
* @param key the property key
* @return the property separator for this property
* @since 1.7
*/
public String getSeparator(String key)
{
return fetchLayoutData(key).getSeparator();
}
/**
* Sets the separator to be used for the property with the given key. The
* separator is the string between the property key and its value. For new
* properties " = " is used. When a properties file is read, the
* layout tries to determine the separator for each property. With this
* method the separator can be changed. To be compatible with the properties
* format only the characters = and : (with or
* without whitespace) should be used, but this method does not enforce this
* - it accepts arbitrary strings. If the key refers to a property with
* multiple values that are written on multiple lines, this separator will
* be used on all lines.
*
* @param key the key for the property
* @param sep the separator to be used for this property
* @since 1.7
*/
public void setSeparator(String key, String sep)
{
fetchLayoutData(key).setSeparator(sep);
}
/**
* Returns the global separator.
*
* @return the global properties separator
* @since 1.7
*/
public String getGlobalSeparator()
{
return globalSeparator;
}
/**
* Sets the global separator for properties. With this method a separator
* can be set that will be used for all properties when writing the
* configuration. This is an easy way of determining the properties
* separator globally. To be compatible with the properties format only the
* characters = and : (with or without whitespace)
* should be used, but this method does not enforce this - it accepts
* arbitrary strings. If the global separator is set to null,
* property separators are not changed. This is the default behavior as it
* produces results that are closer to the original properties file.
*
* @param globalSeparator the separator to be used for all properties
* @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;
}
/**
* Sets the line separator. When writing the properties configuration, all
* lines are terminated with this separator. If no separator was set, the
* platform-specific default line separator is used.
*
* @param lineSeparator the line separator
* @since 1.7
*/
public void setLineSeparator(String lineSeparator)
{
this.lineSeparator = lineSeparator;
}
/**
* Returns a set with all property keys managed by this object.
*
* @return a set with all contained property keys
*/
public Set getKeys()
{
return layoutData.keySet();
}
/**
* Reads a properties file and stores its internal structure. The found
* properties will be added to the associated configuration object.
*
* @param in the reader to the properties file
* @throws ConfigurationException if an error occurs
*/
public void load(Reader in) throws ConfigurationException
{
if (++loadCounter == 1)
{
getConfiguration().removeConfigurationListener(this);
}
PropertiesConfiguration.PropertiesReader reader = getConfiguration()
.getIOFactory().createPropertiesReader(in,
getConfiguration().getListDelimiter());
try
{
while (reader.nextProperty())
{
if (getConfiguration().propertyLoaded(reader.getPropertyName(),
reader.getPropertyValue()))
{
boolean contained = layoutData.containsKey(reader
.getPropertyName());
int blancLines = 0;
int idx = checkHeaderComment(reader.getCommentLines());
while (idx < reader.getCommentLines().size()
&& ((String) reader.getCommentLines().get(idx))
.length() < 1)
{
idx++;
blancLines++;
}
String comment = extractComment(reader.getCommentLines(),
idx, reader.getCommentLines().size() - 1);
PropertyLayoutData data = fetchLayoutData(reader
.getPropertyName());
if (contained)
{
data.addComment(comment);
data.setSingleLine(false);
}
else
{
data.setComment(comment);
data.setBlancLines(blancLines);
data.setSeparator(reader.getPropertySeparator());
}
}
}
}
catch (IOException ioex)
{
throw new ConfigurationException(ioex);
}
finally
{
if (--loadCounter == 0)
{
getConfiguration().addConfigurationListener(this);
}
}
}
/**
* Writes the properties file to the given writer, preserving as much of its
* structure as possible.
*
* @param out the writer
* @throws ConfigurationException if an error occurs
*/
public void save(Writer out) throws ConfigurationException
{
try
{
char delimiter = getConfiguration().isDelimiterParsingDisabled() ? 0
: getConfiguration().getListDelimiter();
PropertiesConfiguration.PropertiesWriter writer = getConfiguration()
.getIOFactory().createPropertiesWriter(out, delimiter);
writer.setGlobalSeparator(getGlobalSeparator());
if (getLineSeparator() != null)
{
writer.setLineSeparator(getLineSeparator());
}
if (headerComment != null)
{
writeComment(writer, getCanonicalHeaderComment(true));
writer.writeln(null);
}
for (Iterator it = layoutData.keySet().iterator(); it.hasNext();)
{
String key = (String) it.next();
if (getConfiguration().containsKey(key))
{
// Output blank lines before property
for (int i = 0; i < getBlancLinesBefore(key); i++)
{
writer.writeln(null);
}
// Output the comment
writeComment(writer, getCanonicalComment(key, true));
// Output the property and its value
boolean singleLine = (isForceSingleLine() || isSingleLine(key))
&& !getConfiguration().isDelimiterParsingDisabled();
writer.setCurrentSeparator(getSeparator(key));
writer.writeProperty(key, getConfiguration().getProperty(
key), singleLine);
}
}
writer.flush();
}
catch (IOException ioex)
{
throw new ConfigurationException(ioex);
}
}
/**
* The event listener callback. Here event notifications of the
* configuration object are processed to update the layout object properly.
*
* @param event the event object
*/
public void configurationChanged(ConfigurationEvent event)
{
if (event.isBeforeUpdate())
{
if (AbstractFileConfiguration.EVENT_RELOAD == event.getType())
{
clear();
}
}
else
{
switch (event.getType())
{
case AbstractConfiguration.EVENT_ADD_PROPERTY:
boolean contained = layoutData.containsKey(event
.getPropertyName());
PropertyLayoutData data = fetchLayoutData(event
.getPropertyName());
data.setSingleLine(!contained);
break;
case AbstractConfiguration.EVENT_CLEAR_PROPERTY:
layoutData.remove(event.getPropertyName());
break;
case AbstractConfiguration.EVENT_CLEAR:
clear();
break;
case AbstractConfiguration.EVENT_SET_PROPERTY:
fetchLayoutData(event.getPropertyName());
break;
}
}
}
/**
* Returns a layout data object for the specified key. If this is a new key,
* a new object is created and initialized with default values.
*
* @param key the key
* @return the corresponding layout data object
*/
private PropertyLayoutData fetchLayoutData(String key)
{
if (key == null)
{
throw new IllegalArgumentException("Property key must not be null!");
}
PropertyLayoutData data = (PropertyLayoutData) layoutData.get(key);
if (data == null)
{
data = new PropertyLayoutData();
data.setSingleLine(true);
layoutData.put(key, data);
}
return data;
}
/**
* Removes all content from this layout object.
*/
private void clear()
{
layoutData.clear();
setHeaderComment(null);
}
/**
* 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
*/
static boolean isCommentLine(String line)
{
return PropertiesConfiguration.isCommentLine(line);
}
/**
* Trims a comment. This method either removes all comment characters from
* the given string, leaving only the plain comment text or ensures that
* every line starts with a valid comment character.
*
* @param s the string to be processed
* @param comment if true, a comment character will always be
* enforced; if false, it will be removed
* @return the trimmed comment
*/
static String trimComment(String s, boolean comment)
{
StringBuffer buf = new StringBuffer(s.length());
int lastPos = 0;
int pos;
do
{
pos = s.indexOf(CR, lastPos);
if (pos >= 0)
{
String line = s.substring(lastPos, pos);
buf.append(stripCommentChar(line, comment)).append(CR);
lastPos = pos + CR.length();
}
} while (pos >= 0);
if (lastPos < s.length())
{
buf.append(stripCommentChar(s.substring(lastPos), comment));
}
return buf.toString();
}
/**
* Either removes the comment character from the given comment line or
* ensures that the line starts with a comment character.
*
* @param s the comment line
* @param comment if true, a comment character will always be
* enforced; if false, it will be removed
* @return the line without comment character
*/
static String stripCommentChar(String s, boolean comment)
{
if (s.length() < 1 || (isCommentLine(s) == comment))
{
return s;
}
else
{
if (!comment)
{
int pos = 0;
// find first comment character
while (PropertiesConfiguration.COMMENT_CHARS.indexOf(s
.charAt(pos)) < 0)
{
pos++;
}
// Remove leading spaces
pos++;
while (pos < s.length()
&& Character.isWhitespace(s.charAt(pos)))
{
pos++;
}
return (pos < s.length()) ? s.substring(pos)
: StringUtils.EMPTY;
}
else
{
return COMMENT_PREFIX + s;
}
}
}
/**
* Extracts a comment string from the given range of the specified comment
* lines. The single lines are added using a line feed as separator.
*
* @param commentLines a list with comment lines
* @param from the start index
* @param to the end index (inclusive)
* @return the comment string (null if it is undefined)
*/
private String extractComment(List commentLines, int from, int to)
{
if (to < from)
{
return null;
}
else
{
StringBuffer buf = new StringBuffer((String) commentLines.get(from));
for (int i = from + 1; i <= to; i++)
{
buf.append(CR);
buf.append(commentLines.get(i));
}
return buf.toString();
}
}
/**
* Checks if parts of the passed in comment can be used as header comment.
* This method checks whether a header comment can be defined (i.e. whether
* this is the first comment in the loaded file). If this is the case, it is
* searched for the latest blanc line. This line will mark the end of the
* header comment. The return value is the index of the first line in the
* passed in list, which does not belong to the header comment.
*
* @param commentLines the comment lines
* @return the index of the next line after the header comment
*/
private int checkHeaderComment(List commentLines)
{
if (loadCounter == 1 && getHeaderComment() == null
&& layoutData.isEmpty())
{
// This is the first comment. Search for blanc lines.
int index = commentLines.size() - 1;
while (index >= 0
&& ((String) commentLines.get(index)).length() > 0)
{
index--;
}
setHeaderComment(extractComment(commentLines, 0, index - 1));
return index + 1;
}
else
{
return 0;
}
}
/**
* Copies the data from the given layout object.
*
* @param c the layout object to copy
*/
private void copyFrom(PropertiesConfigurationLayout c)
{
for (Iterator it = c.getKeys().iterator(); it.hasNext();)
{
String key = (String) it.next();
PropertyLayoutData data = (PropertyLayoutData) c.layoutData
.get(key);
layoutData.put(key, data.clone());
}
}
/**
* Helper method for writing a comment line. This method ensures that the
* correct line separator is used if the comment spans multiple lines.
*
* @param writer the writer
* @param comment the comment to write
* @throws IOException if an IO error occurs
*/
private static void writeComment(
PropertiesConfiguration.PropertiesWriter writer, String comment)
throws IOException
{
if (comment != null)
{
writer.writeln(StringUtils.replace(comment, CR, writer
.getLineSeparator()));
}
}
/**
* A helper class for storing all layout related information for a
* configuration property.
*/
static class PropertyLayoutData implements Cloneable
{
/** Stores the comment for the property. */
private StringBuffer comment;
/** The separator to be used for this property. */
private String separator;
/** Stores the number of blanc lines before this property. */
private int blancLines;
/** Stores the single line property. */
private boolean singleLine;
/**
* Creates a new instance of PropertyLayoutData.
*/
public PropertyLayoutData()
{
singleLine = true;
separator = PropertiesConfiguration.DEFAULT_SEPARATOR;
}
/**
* Returns the number of blanc lines before this property.
*
* @return the number of blanc lines before this property
*/
public int getBlancLines()
{
return blancLines;
}
/**
* Sets the number of properties before this property.
*
* @param blancLines the number of properties before this property
*/
public void setBlancLines(int blancLines)
{
this.blancLines = blancLines;
}
/**
* Returns the single line flag.
*
* @return the single line flag
*/
public boolean isSingleLine()
{
return singleLine;
}
/**
* Sets the single line flag.
*
* @param singleLine the single line flag
*/
public void setSingleLine(boolean singleLine)
{
this.singleLine = singleLine;
}
/**
* Adds a comment for this property. If already a comment exists, the
* new comment is added (separated by a newline).
*
* @param s the comment to add
*/
public void addComment(String s)
{
if (s != null)
{
if (comment == null)
{
comment = new StringBuffer(s);
}
else
{
comment.append(CR).append(s);
}
}
}
/**
* Sets the comment for this property.
*
* @param s the new comment (can be null)
*/
public void setComment(String s)
{
if (s == null)
{
comment = null;
}
else
{
comment = new StringBuffer(s);
}
}
/**
* Returns the comment for this property. The comment is returned as it
* is, without processing of comment characters.
*
* @return the comment (can be null)
*/
public String getComment()
{
return (comment == null) ? null : comment.toString();
}
/**
* Returns the separator that was used for this property.
*
* @return the property separator
*/
public String getSeparator()
{
return separator;
}
/**
* Sets the separator to be used for the represented property.
*
* @param separator the property separator
*/
public void setSeparator(String separator)
{
this.separator = separator;
}
/**
* Creates a copy of this object.
*
* @return the copy
*/
public Object clone()
{
try
{
PropertyLayoutData copy = (PropertyLayoutData) super.clone();
if (comment != null)
{
// must copy string buffer, too
copy.comment = new StringBuffer(getComment());
}
return copy;
}
catch (CloneNotSupportedException cnex)
{
// This cannot happen!
throw new ConfigurationRuntimeException(cnex);
}
}
}
}