Properties files are a popular mean of configuring applications. Of course Commons Configuration
supports this format and enhances significantly the basic java.util.Properties
class.
This section introduces the features of the
PropertiesConfiguration
class.
Note that PropertiesConfiguration
is a very typical example
for an implementation of the Configuration
interface and
many of the features described in this section (e.g. list handling or
interpolation) are supported by other configuration classes as well.
This is because most configuration implementations that ship with
Commons Configuration are derived from the common base class
AbstractConfiguration
,
which implementes this features.
Let's start with a simple properties file named
usergui.properties
with the following content:
# Properties definining the GUI colors.background = #FFFFFF colors.foreground = #000080 window.width = 500 window.height = 300
To load this file, you'll write:
Configuration config = new PropertiesConfiguration("usergui.properties");
If you do not specify an absolute path, the file will be searched automatically in the following locations:
Instead of using a constructor that takes a file name you can also
invoke one of the load()
methods. There are several
overloaded variants that allow you to load properties from various
sources. More information about loading properties files (and file-based
configurations in general) can be found in the section about
File-based Configurations.
After the properties file was loaded you can access its content through
the methods of the Configuration
interface, e.g.
String backColor = config.getString("colors.background"); Dimension size = new Dimension(config.getInt("window.width"), config.getInt("window.height"));
If a property is named "include
" and the value of that property is the
name of a file on the disk, that file will be included into the configuration. Here is
an example:
# usergui.properties include = colors.properties include = sizes.properties
# colors.properties colors.background = #FFFFFF
Commons Configuration has the ability to return easily a list of values, for example if your file contains a list of comma separated values:
# chart colors colors.pie = #FF0000, #00FF00, #0000FF
You don't have to split the value manually, you can retrieve an array
or a java.util.List
directly with:
String[] colors = config.getStringArray("colors.pie"); List colorList = config.getList("colors.pie");
Alternatively, you can specify a list of values in your properties file by using the same key on several lines:
# chart colors colors.pie = #FF0000; colors.pie = #00FF00; colors.pie = #0000FF;
The addProperty()
and setProperty()
methods
also implement special list handling. The property value that is passed
to these methods can be a list or an array resulting in a property
with multiple values. If the property value is a string, it is checked
whether it contains the list delimiter character. If this is
the case, the string is splitted, and its single parts are added one
by one. The list delimiter character is the comma by default. It is
also applied to the properties when the configuration file is loaded
(that's the reason why the example above with the comma separated list
of chart colors works). By using the setListDelimiter()
method you can set it to a different character. Here are some examples:
// Change the list delimiter character to a slash config.setListDelimiter('/'); // Now add some properties config.addProperty("greeting", "Hello, how are you?"); config.addProperty("colors.pie", new String[] { "#FF0000", "#00FF00", "#0000FF" }); config.addProperty("colors.graph", "#808080/#00FFCC/#6422FF"); // Access data String salut = config.getString("greeting"); List colPie = config.getList("colors.pie"); String[] colGraph = config.getStringArray("colors.graph"); String firstPieColor = config.getString("colors.pie");
In this example the list delimiter character is changed from a comma
to a slash. Because of this the greeting
property won't
be splitted, but remains a single string. The string passed as value
for the colors.graph
property in opposite contains the
new delimiter character and thus will result in a property with three
values.
Of interest is also the last line of the example fragment. Here the
getString()
method is called for a property that has
multiple values. This call will return the first value of the list.
If you want to change the list delimiter character for all configuration
objects, you can use the static setDefaultListDelimiter()
method of AbstractConfiguration
. It is also possible to
disable splitting of string properties at all for a Configuration
instance by calling its setDelimiterParsingDisabled()
method with a value of true.
Note: The list handling and string splitting facilities
described in this section are not specific to PropertiesConfiguration
,
but are also supported by other configuration classes.
If you are familiar with Ant or Maven, you have most certainly already encountered
the variables (like ${token}
) that are automatically expanded when the
configuration file is loaded. Commons Configuration supports this feature as well,
here is an example:
application.name = Killer App application.version = 1.6.2 application.title = ${application.name} ${application.version}
If you now retrieve the value for the application.title
property, the result will be Killer App 1.6.2
. As for
list handling, variable interpolation is a feature supported by other
configuration classes as well.
To save your configuration, just call the save()
method:
PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties"); config.setProperty("colors.background", "#000000); config.save();
You can also save a copy of the configuration to another file:
PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties"); config.setProperty("colors.background", "#000000); config.save("usergui.backup.properties);
More information about saving properties files (and file-based configurations in general) can be found in the section about File-based Configurations.
If you need a special character in a property like a line feed, a tabulation or an unicode character, you can specify it with the same escaped notation used for Java Strings. The list separator ("," by default), can also be escaped:
key = This \n string \t contains \, escaped \\ characters \u0020
Each PropertiesConfiguration
object is associated with a
Layout object, an instance of the class
PropertiesConfigurationLayout
. This layout object is
responsible for preserving most of the structure of loaded configuration
files. This means that things like comments or blanc lines in a saved
properties file will closely resemble the original properties file
(the algorithm is not 100 percent perfect, but for most use cases it
should be sufficient).
Normally a developer does not have to deal with these layout objects.
However there are some methods that might be of interest in certain use
cases. For instance PropertiesConfigurationLayout
defines
methods for obtaining and setting the comment for a property key. A
header comment for the whole properties file is also supported. If the
values of multi-valued properties should always be written on a
single line rather than adding a new property definition for each value
(which would be incompatible with java.util.Properties
)
the setForceSingleLine()
method can be used.