Class PropertiesConfiguration
- java.lang.Object
-
- org.apache.commons.configuration2.event.BaseEventSource
-
- org.apache.commons.configuration2.AbstractConfiguration
-
- org.apache.commons.configuration2.BaseConfiguration
-
- org.apache.commons.configuration2.PropertiesConfiguration
-
- All Implemented Interfaces:
java.lang.Cloneable
,Configuration
,EventSource
,FileBasedConfiguration
,ImmutableConfiguration
,FileBased
,FileLocatorAware
,SynchronizerSupport
public class PropertiesConfiguration extends BaseConfiguration implements FileBasedConfiguration, FileLocatorAware
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
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.
-
The list delimiter facilities provided by
AbstractConfiguration
are supported, too. If an appropriateListDelimiterHandler
is set (for instance aD efaultListDelimiterHandler
object configured with a comma as delimiter character), value can contain value delimiters and will then be interpreted as a list of tokens. So the following property definitionkey = This property, has multiple, values
will result in a property with three values. You can change the handling of delimiters using theAbstractConfiguration.setListDelimiterHandler(ListDelimiterHandler)
method. Per default, list splitting is disabled. - 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 thePropertiesConfigurationLayout
class, which is responsible for storing the layout of the parsed properties file (i.e. empty lines, comments, and such things). ThegetLayout()
method can be used to obtain this layout object. WithsetLayout()
a new layout object can be set. This should be done before a properties file was loaded.Like other
Configuration
implementations, this class uses aSynchronizer
object to control concurrent access. By choosing a suitable implementation of theSynchronizer
interface, an instance can be made thread-safe or not. Note that access to most of the properties typically set through a builder is not protected by theSynchronizer
. The intended usage is that these properties are set once at construction time through the builder and after that remain constant. If you wish to change such properties during life time of an instance, you have to use thelock()
andunlock()
methods manually to ensure that other threads see your changes.As this class extends
AbstractConfiguration
, all basic features like variable interpolation, list handling, or data type conversions are available as well. This is described in the chapter Basic features and AbstractConfiguration of the user's guide. There is also a separate chapter dealing with Properties files in special.- Version:
- $Id: PropertiesConfiguration.java 1790899 2017-04-10 21:56:46Z ggregory $
- 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:
Properties.load(java.io.Reader)
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
PropertiesConfiguration.DefaultIOFactory
A default implementation of theIOFactory
interface.static interface
PropertiesConfiguration.IOFactory
Definition of an interface that allows customization of read and write operations.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 Modifier and Type Field Description static java.lang.String
DEFAULT_ENCODING
The default encoding (ISO-8859-1 as specified by http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html)
-
Constructor Summary
Constructors Constructor Description PropertiesConfiguration()
Creates an empty PropertyConfiguration object which can be used to synthesize a new Properties file by adding values and then saving().
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.lang.Object
clone()
Creates a copy of this object.java.lang.String
getFooter()
Returns the footer comment.java.lang.String
getHeader()
Return the comment header.static java.lang.String
getInclude()
Gets the property value for including other properties files.PropertiesConfiguration.IOFactory
getIOFactory()
Returns theIOFactory
to be used for creating readers and writers when loading or saving this configuration.PropertiesConfigurationLayout
getLayout()
Returns the associated layout object.void
initFileLocator(FileLocator locator)
Stores the currentFileLocator
for a following IO operation.boolean
isIncludesAllowed()
Reports the status of file inclusion.void
read(java.io.Reader in)
Reads the content of this object from the given reader.void
setFooter(java.lang.String footer)
Sets the footer comment.void
setHeader(java.lang.String header)
Set the comment header.static void
setInclude(java.lang.String inc)
Sets the property value for including other properties files.void
setIncludesAllowed(boolean includesAllowed)
Controls whether additional files can be loaded by theinclude = <xxx>
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
setLayout(PropertiesConfigurationLayout layout)
Sets the associated layout object.protected static java.lang.String
unescapeJava(java.lang.String str)
Unescapes any Java literals found in theString
to aWriter
.void
write(java.io.Writer out)
Writes the content of this object to the given writer.-
Methods inherited from class org.apache.commons.configuration2.BaseConfiguration
addPropertyDirect, clearInternal, clearPropertyDirect, containsKeyInternal, getKeysInternal, getPropertyInternal, isEmptyInternal, sizeInternal
-
Methods inherited from class org.apache.commons.configuration2.AbstractConfiguration
addErrorLogListener, addProperty, addPropertyInternal, append, beginRead, beginWrite, clear, clearProperty, cloneInterpolator, containsKey, copy, endRead, endWrite, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getConfigurationDecoder, getConversionHandler, getDouble, getDouble, getDouble, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getKeys, getKeysInternal, getList, getList, getList, getList, getListDelimiterHandler, getLogger, getLong, getLong, getLong, getProperties, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, getSynchronizer, immutableSubset, initLogger, installInterpolator, interpolate, interpolate, interpolatedConfiguration, isEmpty, isScalarValue, isThrowExceptionOnMissing, lock, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setListDelimiterHandler, setLogger, setParentInterpolator, setPrefixLookups, setProperty, setPropertyInternal, setSynchronizer, setThrowExceptionOnMissing, size, subset, unlock
-
Methods inherited from class org.apache.commons.configuration2.event.BaseEventSource
addEventListener, clearErrorListeners, clearEventListeners, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, 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.configuration2.Configuration
addProperty, clear, clearProperty, getInterpolator, installInterpolator, setInterpolator, setProperty, subset
-
Methods inherited from interface org.apache.commons.configuration2.ImmutableConfiguration
containsKey, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getDouble, getDouble, getDouble, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getKeys, getList, getList, getList, getList, getLong, getLong, getLong, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, immutableSubset, isEmpty, size
-
Methods inherited from interface org.apache.commons.configuration2.sync.SynchronizerSupport
getSynchronizer, lock, setSynchronizer, unlock
-
-
-
-
Field Detail
-
DEFAULT_ENCODING
public static final java.lang.String DEFAULT_ENCODING
The default encoding (ISO-8859-1 as specified by http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html)- See Also:
- Constant Field Values
-
-
Method Detail
-
getInclude
public static java.lang.String getInclude()
Gets the property value for including other properties files. By default it is "include".- Returns:
- A String.
-
setInclude
public static void setInclude(java.lang.String inc)
Sets the property value for including other properties files. By default it is "include".- Parameters:
inc
- A String.
-
setIncludesAllowed
public void setIncludesAllowed(boolean includesAllowed)
Controls whether additional files can be loaded by theinclude = <xxx>
statement or not. This is true per default.- Parameters:
includesAllowed
- True if Includes are allowed.
-
isIncludesAllowed
public boolean isIncludesAllowed()
Reports the status of file inclusion.- Returns:
- True if include files are loaded.
-
getHeader
public java.lang.String getHeader()
Return the comment header.- Returns:
- the comment header
- Since:
- 1.1
-
setHeader
public void setHeader(java.lang.String header)
Set the comment header.- Parameters:
header
- the header to use- Since:
- 1.1
-
getFooter
public java.lang.String getFooter()
Returns the footer comment. This is a comment at the very end of the file.- Returns:
- the footer comment
- Since:
- 2.0
-
setFooter
public void setFooter(java.lang.String footer)
Sets the footer comment. If set, this comment is written after all properties at the end of the file.- Parameters:
footer
- the footer comment- Since:
- 2.0
-
getLayout
public PropertiesConfigurationLayout getLayout()
Returns the associated layout object.- Returns:
- the associated layout object
- Since:
- 1.3
-
setLayout
public void setLayout(PropertiesConfigurationLayout layout)
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
-
getIOFactory
public PropertiesConfiguration.IOFactory getIOFactory()
Returns theIOFactory
to be used for creating readers and writers when loading or saving this configuration.- Returns:
- the
IOFactory
- Since:
- 1.7
-
setIOFactory
public void setIOFactory(PropertiesConfiguration.IOFactory ioFactory)
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:
java.lang.IllegalArgumentException
- if theIOFactory
is null- Since:
- 1.7
-
initFileLocator
public void initFileLocator(FileLocator locator)
Stores the currentFileLocator
for a following IO operation. TheFileLocator
is needed to resolve include files with relative file names.- Specified by:
initFileLocator
in interfaceFileLocatorAware
- Parameters:
locator
- the currentFileLocator
- Since:
- 2.0
-
read
public void read(java.io.Reader in) throws ConfigurationException, java.io.IOException
Reads the content of this object from the given reader. Client code should not call this method directly, but use aFileHandler
for reading data. This implementation delegates to the associated layout object which does the actual loading. Note that this method does not do any synchronization. This lies in the responsibility of the caller. (Typically, the caller is aFileHandler
object which takes care for proper synchronization.)- Specified by:
read
in interfaceFileBased
- Parameters:
in
- the reader- Throws:
ConfigurationException
- if a non-I/O related problem occurs, e.g. the data read does not have the expected formatjava.io.IOException
- if an I/O error occurs- Since:
- 2.0
-
write
public void write(java.io.Writer out) throws ConfigurationException, java.io.IOException
Writes the content of this object to the given writer. Client code should not call this method directly, but use aFileHandler
for writing data. This implementation delegates to the associated layout object which does the actual saving. Note that, analogous toread(Reader)
, this method does not do any synchronization.- Specified by:
write
in interfaceFileBased
- Parameters:
out
- the writer- Throws:
ConfigurationException
- if a non-I/O related problem occurs, e.g. the data read does not have the expected formatjava.io.IOException
- if an I/O error occurs- Since:
- 2.0
-
clone
public java.lang.Object clone()
Creates a copy of this object.- Overrides:
clone
in classBaseConfiguration
- Returns:
- the copy
-
unescapeJava
protected static java.lang.String unescapeJava(java.lang.String str)
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 null- Returns:
- the processed string
- Throws:
java.lang.IllegalArgumentException
- if the Writer isnull
-
-