public class PropertiesConfiguration extends BaseConfiguration implements FileBasedConfiguration, FileLocatorAware
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:
key <separator> value
. The separators accepted are '='
,
':'
and any white space character. Examples:
key1 = value1 key2 : value2 key3 value3
key\:foo = bar
AbstractConfiguration
are supported, too. If an appropriate
ListDelimiterHandler
is set (for instance a
D 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 definition
key = This property, has multiple, valueswill result in a property with three values. You can change the handling of delimiters using the
AbstractConfiguration.setListDelimiterHandler(ListDelimiterHandler)
method. Per default, list splitting is
disabled.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."include"
by using
setIncludeListener(ConfigurationConsumer)
.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.
Like other Configuration
implementations, this class uses a Synchronizer
object to control concurrent
access. By choosing a suitable implementation of the Synchronizer
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
the Synchronizer
. 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 the lock()
and unlock()
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.
Properties.load(java.io.Reader)
Modifier and Type | Class and Description |
---|---|
static class |
PropertiesConfiguration.DefaultIOFactory
A default implementation of the
IOFactory interface. |
static interface |
PropertiesConfiguration.IOFactory
Definition of an interface that allows customization of read and write operations.
|
static class |
PropertiesConfiguration.JupIOFactory
An alternative
PropertiesConfiguration.IOFactory that tries to mimic the behavior of Properties (Jup) more closely. |
static class |
PropertiesConfiguration.JupPropertiesReader
A
PropertiesConfiguration.PropertiesReader that tries to mimic the behavior of Properties . |
static class |
PropertiesConfiguration.JupPropertiesWriter
A
PropertiesConfiguration.PropertiesWriter that tries to mimic the behavior of Properties . |
static class |
PropertiesConfiguration.PropertiesReader
This class is used to read properties lines.
|
static class |
PropertiesConfiguration.PropertiesWriter
This class is used to write properties lines.
|
Modifier and Type | Field and Description |
---|---|
static 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)
|
static ConfigurationConsumer<ConfigurationException> |
DEFAULT_INCLUDE_LISTENER
Defines default error handling for the special
"include" key by throwing the given exception. |
static ConfigurationConsumer<ConfigurationException> |
NOOP_INCLUDE_LISTENER
Defines error handling as a noop for the special
"include" key. |
Constructor and Description |
---|
PropertiesConfiguration()
Creates an empty PropertyConfiguration object which can be used to synthesize a new Properties file by adding values
and then saving().
|
Modifier and Type | Method and Description |
---|---|
Object |
clone()
Creates a copy of this object.
|
String |
getFooter()
Returns the footer comment.
|
String |
getHeader()
Return the comment header.
|
static String |
getInclude()
Gets the property value for including other properties files.
|
ConfigurationConsumer<ConfigurationException> |
getIncludeListener()
Gets the current include listener, never null.
|
static String |
getIncludeOptional()
Gets the property value for including other properties files.
|
PropertiesConfiguration.IOFactory |
getIOFactory()
Returns the
IOFactory 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 current
FileLocator for a following IO operation. |
boolean |
isIncludesAllowed()
Reports the status of file inclusion.
|
void |
read(Reader in)
Reads the content of this object from the given reader.
|
void |
setFooter(String footer)
Sets the footer comment.
|
void |
setHeader(String header)
Set the comment header.
|
static void |
setInclude(String inc)
Sets the property value for including other properties files.
|
void |
setIncludeListener(ConfigurationConsumer<ConfigurationException> includeListener)
Sets the current include listener, may not be null.
|
static void |
setIncludeOptional(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 = <xxx> statement or not. |
void |
setIOFactory(PropertiesConfiguration.IOFactory ioFactory)
Sets the
IOFactory 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 String |
unescapeJava(String str)
Unescapes any Java literals found in the
String to a Writer . |
protected static String |
unescapeJava(String str,
boolean jupCompatible)
Unescapes Java literals found in the
String to a Writer . |
void |
write(Writer out)
Writes the content of this object to the given writer.
|
addPropertyDirect, clearInternal, clearPropertyDirect, containsKeyInternal, getKeysInternal, getPropertyInternal, isEmptyInternal, sizeInternal
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, getDuration, getDuration, 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
addEventListener, clearErrorListeners, clearEventListeners, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, setDetailEvents
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
addProperty, clear, clearProperty, getInterpolator, installInterpolator, setInterpolator, setProperty, subset
containsKey, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getEnum, getEnum, 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
getSynchronizer, lock, setSynchronizer, unlock
public static final ConfigurationConsumer<ConfigurationException> DEFAULT_INCLUDE_LISTENER
"include"
key by throwing the given exception.public static final ConfigurationConsumer<ConfigurationException> NOOP_INCLUDE_LISTENER
"include"
key.public static final String DEFAULT_ENCODING
public PropertiesConfiguration()
public static String getInclude()
public static String getIncludeOptional()
If the file is absent, processing continues normally.
public static void setInclude(String inc)
inc
- A String.public static void setIncludeOptional(String inc)
If the file is absent, processing continues normally.
inc
- A String.protected static String unescapeJava(String str)
Unescapes any Java literals found in the String
to a Writer
.
str
- the String
to unescape, may be nullIllegalArgumentException
- if the Writer is null
protected static String unescapeJava(String str, boolean jupCompatible)
String
to a Writer
.
When the parameter jupCompatible
is false
, the classic behavior is used (see
unescapeJava(String)
). When it's true
a slightly different behavior that's compatible with
Properties
is used (see PropertiesConfiguration.JupIOFactory
).
str
- the String
to unescape, may be nulljupCompatible
- whether unescaping is compatible with Properties
; otherwise the classic
behavior is usedIllegalArgumentException
- if the Writer is null
public Object clone()
clone
in class BaseConfiguration
public String getFooter()
public String getHeader()
public ConfigurationConsumer<ConfigurationException> getIncludeListener()
public PropertiesConfiguration.IOFactory getIOFactory()
IOFactory
to be used for creating readers and writers when loading or saving this configuration.IOFactory
public PropertiesConfigurationLayout getLayout()
public void initFileLocator(FileLocator locator)
FileLocator
for a following IO operation. The FileLocator
is needed to resolve
include files with relative file names.initFileLocator
in interface FileLocatorAware
locator
- the current FileLocator
public boolean isIncludesAllowed()
public void read(Reader in) throws ConfigurationException, IOException
FileHandler
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
a FileHandler
object which takes care for proper synchronization.)read
in interface FileBased
in
- the readerConfigurationException
- if a non-I/O related problem occurs, e.g. the data read does not have the expected
formatIOException
- if an I/O error occurs.public void setFooter(String footer)
footer
- the footer commentpublic void setHeader(String header)
header
- the header to usepublic void setIncludeListener(ConfigurationConsumer<ConfigurationException> includeListener)
includeListener
- the current include listener, may not be null.IllegalArgumentException
- if the includeListener
is null.public void setIncludesAllowed(boolean includesAllowed)
include = <xxx>
statement or not. This is true
per default.includesAllowed
- True if Includes are allowed.public void setIOFactory(PropertiesConfiguration.IOFactory ioFactory)
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.ioFactory
- the new IOFactory
(must not be null)IllegalArgumentException
- if the IOFactory
is nullpublic void setLayout(PropertiesConfigurationLayout layout)
layout
- the new layout object; can be null, then a new layout object will be createdpublic void write(Writer out) throws ConfigurationException, IOException
FileHandler
for writing data. This implementation delegates to the associated layout object which does the actual saving. Note that,
analogous to read(Reader)
, this method does not do any synchronization.write
in interface FileBased
out
- the writerConfigurationException
- if a non-I/O related problem occurs, e.g. the data read does not have the expected
formatIOException
- if an I/O error occurs.Copyright © 2001–2022 The Apache Software Foundation. All rights reserved.