Class PropertiesConfiguration
- All Implemented Interfaces:
Cloneable
,Configuration
,FileConfiguration
,FileSystemBased
- Direct Known Subclasses:
XMLPropertiesConfiguration
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 Properties.load(java.io.Reader)
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 theAbstractConfiguration.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
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 theaddProperty()
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 thePropertiesConfigurationLayout
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 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.
- Version:
- $Id: PropertiesConfiguration.java 1534445 2013-10-22 01:19:43Z henning $
- Author:
- 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, Emmanuel Bourg
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
A default implementation of theIOFactory
interface.static interface
Definition of an interface that allows customization of read and write operations.static class
This class is used to read properties lines.static class
This class is used to write properties lines. -
Field Summary
Fields inherited from class org.apache.commons.configuration.AbstractFileConfiguration
autoSave, basePath, EVENT_CONFIG_CHANGED, EVENT_RELOAD, fileName, reloadLock, strategy
Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN
-
Constructor Summary
ConstructorsConstructorDescriptionCreates 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.Creates and loads the extended properties from the specified URL. -
Method Summary
Modifier and TypeMethodDescriptionclone()
Creates a copy of this object.protected PropertiesConfigurationLayout
Creates the associated layout object.Returns the encoding to be used when loading or storing configuration data.Returns the footer comment.Return the comment header.static String
Gets the property value for including other properties files.boolean
Deprecated.Only exists to not break backwards compatibility.Returns theIOFactory
to be used for creating readers and writers when loading or saving this configuration.Returns the associated layout object.boolean
Reports the status of file inclusion.void
Load the properties from the given reader.void
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
Sets the footer comment.void
Set the comment header.static void
setInclude
(String inc) Sets the property value for including other properties files.void
setIncludesAllowed
(boolean includesAllowed) Controls whether additional files can be loaded by the include =statement or not. void
setIOFactory
(PropertiesConfiguration.IOFactory ioFactory) Sets theIOFactory
to be used for creating readers and writers when loading or saving this configuration.void
Sets the associated layout object.protected static String
unescapeJava
(String str, char delimiter) Unescapes any Java literals found in theString
to aWriter
.Methods inherited from class org.apache.commons.configuration.AbstractFileConfiguration
addProperty, clearProperty, closeSilent, configurationChanged, containsKey, enterNoReload, exitNoReload, fireEvent, getBasePath, getFile, getFileName, getFileSystem, getKeys, getPath, getProperty, getReloadingStrategy, getReloadLock, getURL, isAutoSave, isEmpty, load, load, load, load, load, load, possiblySave, refresh, reload, reload, resetFileSystem, save, save, save, save, save, save, setAutoSave, setEncoding, setFile, setFileName, setFileSystem, setPath, setProperty, setReloadingStrategy, setURL
Methods inherited from class org.apache.commons.configuration.BaseConfiguration
addPropertyDirect, clear, clearPropertyDirect
Methods inherited from class org.apache.commons.configuration.AbstractConfiguration
addErrorLogListener, append, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getList, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolate, interpolatedConfiguration, interpolateHelper, isDelimiterParsingDisabled, isScalarValue, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissing, subset
Methods inherited from class org.apache.commons.configuration.event.EventSource
addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEvents
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.apache.commons.configuration.Configuration
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, subset
-
Constructor Details
-
PropertiesConfiguration
public PropertiesConfiguration()Creates an empty PropertyConfiguration object which can be used to synthesize a new Properties file by adding values and then saving(). -
PropertiesConfiguration
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
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 thesave()
method can be called to save the properties to the specified file.- Parameters:
file
- The properties file to load.- Throws:
ConfigurationException
- Error while loading the properties file
-
PropertiesConfiguration
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 Details
-
getInclude
Gets the property value for including other properties files. By default it is "include".- Returns:
- A String.
-
setInclude
Sets the property value for including other properties files. By default it is "include".- Parameters:
inc
- A String.
-
setIncludesAllowed
Controls whether additional files can be loaded by the include =statement or not. This is true per default. - Parameters:
includesAllowed
- True if Includes are allowed.
-
getIncludesAllowed
Deprecated.Only exists to not break backwards compatibility. UseisIncludesAllowed()
instead.Reports the status of file inclusion.- Returns:
- True if include files are loaded.
- See Also:
-
isIncludesAllowed
Reports the status of file inclusion.- Returns:
- True if include files are loaded.
-
getHeader
Return the comment header.- Returns:
- the comment header
- Since:
- 1.1
-
setHeader
Set the comment header.- Parameters:
header
- the header to use- Since:
- 1.1
-
getEncoding
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.- Specified by:
getEncoding
in interfaceFileConfiguration
- Overrides:
getEncoding
in classAbstractFileConfiguration
- Returns:
- the encoding
-
getLayout
Returns the associated layout object.- Returns:
- the associated layout object
- Since:
- 1.3
-
setLayout
Sets the associated layout object.- Parameters:
layout
- the new layout object; can be null, then a new layout object will be created- Since:
- 1.3
-
createLayout
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.- Returns:
- the layout object to use
- Since:
- 1.3
-
getIOFactory
Returns theIOFactory
to be used for creating readers and writers when loading or saving this configuration.- Returns:
- the
IOFactory
- Since:
- 1.7
-
setIOFactory
Sets theIOFactory
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 theload()
andsave()
methods. Especially, if you want to use a customIOFactory
for changing thePropertiesReader
, you cannot load the configuration data in the constructor.- Parameters:
ioFactory
- the newIOFactory
(must not be null)- Throws:
IllegalArgumentException
- if theIOFactory
is null- Since:
- 1.7
-
load
Load the properties from the given reader. Note that theclear()
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
-
save
Save the configuration to the specified stream.- Parameters:
writer
- the output stream used to save the configuration- Throws:
ConfigurationException
- if an error occurs
-
setBasePath
Extend the setBasePath method to turn includes on and off based on the existence of a base path.- Specified by:
setBasePath
in interfaceFileConfiguration
- Overrides:
setBasePath
in classAbstractFileConfiguration
- Parameters:
basePath
- The new basePath to set.
-
clone
Creates a copy of this object.- Overrides:
clone
in classAbstractFileConfiguration
- Returns:
- the copy
-
unescapeJava
Unescapes any Java literals found in the
This is a slightly modified version of the StringEscapeUtils.unescapeJava() function in commons-lang that doesn't drop escaped separators (i.e '\,').String
to aWriter
.- Parameters:
str
- theString
to unescape, may be nulldelimiter
- the delimiter for multi-valued properties- Returns:
- the processed string
- Throws:
IllegalArgumentException
- if the Writer isnull
-