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, sizeInternaladdErrorLogListener, 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, unlockaddEventListener, clearErrorListeners, clearEventListeners, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, setDetailEventsequals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitaddProperty, clear, clearProperty, getInterpolator, installInterpolator, setInterpolator, setProperty, subsetcontainsKey, 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, sizegetSynchronizer, lock, setSynchronizer, unlockpublic 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.public void setIncludesAllowed(boolean includesAllowed)
include = <xxx>
statement or not. This is true per default.includesAllowed - True if Includes are allowed.public boolean isIncludesAllowed()
public String getHeader()
public void setHeader(String header)
header - the header to usepublic String getFooter()
public void setFooter(String footer)
footer - the footer commentpublic PropertiesConfigurationLayout getLayout()
public void setLayout(PropertiesConfigurationLayout layout)
layout - the new layout object; can be null, then a new
layout object will be createdpublic ConfigurationConsumer<ConfigurationException> getIncludeListener()
public PropertiesConfiguration.IOFactory getIOFactory()
IOFactory to be used for creating readers and
writers when loading or saving this configuration.IOFactorypublic void setIncludeListener(ConfigurationConsumer<ConfigurationException> includeListener)
includeListener - the current include listener, may not be null.IllegalArgumentException - if the includeListener is null.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 initFileLocator(FileLocator locator)
FileLocator for a following IO operation. The
FileLocator is needed to resolve include files with relative file
names.initFileLocator in interface FileLocatorAwarelocator - the current FileLocatorpublic 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 FileBasedin - 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 occurspublic 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 FileBasedout - 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 occurspublic Object clone()
clone in class BaseConfigurationprotected 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 nullprotected 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 nullCopyright © 2001–2020 The Apache Software Foundation. All rights reserved.