Configuration, FileConfiguration, FileSystemBasedXMLPropertiesConfigurationpublic class PropertiesConfiguration extends AbstractFileConfiguration
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
key = This property, has multiple, valueswill result in a property with three values. You can change the value delimiter using the
AbstractConfiguration.setListDelimiter(char)
method. Setting the delimiter to 0 will disable value splitting completely.
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.
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.
Properties.load(java.io.Reader)| Modifier and Type | Class | 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.PropertiesReader |
This class is used to read properties lines.
|
static class |
PropertiesConfiguration.PropertiesWriter |
This class is used to write properties lines.
|
END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKENautoSave, basePath, EVENT_CONFIG_CHANGED, EVENT_RELOAD, fileName, reloadLock, strategy| Constructor | Description |
|---|---|
PropertiesConfiguration() |
Creates an empty PropertyConfiguration object which can be
used to synthesize a new Properties file by adding values and
then saving().
|
PropertiesConfiguration(java.io.File file) |
Creates and loads the extended properties from the specified file.
|
PropertiesConfiguration(java.lang.String fileName) |
Creates and loads the extended properties from the specified file.
|
PropertiesConfiguration(java.net.URL url) |
Creates and loads the extended properties from the specified URL.
|
| Modifier and Type | Method | Description |
|---|---|---|
java.lang.Object |
clone() |
Creates a copy of this object.
|
protected PropertiesConfigurationLayout |
createLayout() |
Creates the associated layout object.
|
java.lang.String |
getEncoding() |
Returns the encoding to be used when loading or storing configuration
data.
|
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.
|
boolean |
getIncludesAllowed() |
Deprecated.
Only exists to not break backwards compatibility.
Use
isIncludesAllowed() instead. |
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.
|
boolean |
isIncludesAllowed() |
Reports the status of file inclusion.
|
void |
load(java.io.Reader in) |
Load the properties from the given reader.
|
void |
save(java.io.Writer writer) |
Save the configuration to the specified stream.
|
void |
setBasePath(java.lang.String basePath) |
Extend the setBasePath method to turn includes
on and off based on the existence of a base path.
|
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 the include =
|
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 java.lang.String |
unescapeJava(java.lang.String str,
char delimiter) |
Unescapes any Java literals found in the
String to a
Writer. |
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, subsetaddProperty, 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, setURLaddPropertyDirect, clear, clearPropertyDirectclear, 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, subsetaddConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEventspublic PropertiesConfiguration()
public PropertiesConfiguration(java.lang.String fileName) throws ConfigurationException
fileName - The name of the properties file to load.ConfigurationException - Error while loading the properties filepublic PropertiesConfiguration(java.io.File file) throws ConfigurationException
save()
method can be called to save the properties to the specified file.file - The properties file to load.ConfigurationException - Error while loading the properties filepublic PropertiesConfiguration(java.net.URL url) throws ConfigurationException
url - The location of the properties file to load.ConfigurationException - Error while loading the properties filepublic static java.lang.String getInclude()
public static void setInclude(java.lang.String inc)
inc - A String.public void setIncludesAllowed(boolean includesAllowed)
includesAllowed - True if Includes are allowed.@Deprecated public boolean getIncludesAllowed()
isIncludesAllowed() instead.isIncludesAllowed()public boolean isIncludesAllowed()
public java.lang.String getHeader()
public void setHeader(java.lang.String header)
header - the header to usepublic java.lang.String getFooter()
public void setFooter(java.lang.String footer)
footer - the footer commentpublic java.lang.String getEncoding()
getEncoding in interface FileConfigurationgetEncoding in class AbstractFileConfigurationpublic PropertiesConfigurationLayout getLayout()
public void setLayout(PropertiesConfigurationLayout layout)
layout - the new layout object; can be null, then a new
layout object will be createdprotected PropertiesConfigurationLayout createLayout()
public PropertiesConfiguration.IOFactory getIOFactory()
IOFactory to be used for creating readers and
writers when loading or saving this configuration.IOFactorypublic 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)java.lang.IllegalArgumentException - if the IOFactory is
nullpublic void load(java.io.Reader in) throws ConfigurationException
clear() method is not called, so
the properties contained in the loaded file will be added to the
actual set of properties.in - An InputStream.ConfigurationException - if an error occurspublic void save(java.io.Writer writer) throws ConfigurationException
writer - the output stream used to save the configurationConfigurationException - if an error occurspublic void setBasePath(java.lang.String basePath)
setBasePath in interface FileConfigurationsetBasePath in class AbstractFileConfigurationbasePath - The new basePath to set.public java.lang.Object clone()
clone in class AbstractFileConfigurationprotected static java.lang.String unescapeJava(java.lang.String str, char delimiter)
Unescapes any Java literals found in the String to a
Writer.
str - the String to unescape, may be nulldelimiter - the delimiter for multi-valued propertiesjava.lang.IllegalArgumentException - if the Writer is null