Properties files are a popular mean of configuring applications. Of course Commons Configuration
supports this format and enhance significantly the basic java.util.Properties
class.
This section introduces the features of the PropertiesConfiguration
class.
At first lets consider that the whole configuration data of an application consists in
a single properties file named usergui.properties
with the following content:
# Properties definining the GUI colors.background = #FFFFFF
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 to load properties from
java.io.File
object
Note that the load()
methods do not empty the
configuration before new data is loaded. This makes it easy to
construct union configurations by simply calling load()
multiple times. But if you want to reuse a Configuration
object and load a different file, remember to call the
clear()
method first to ensure that old properties are
wiped out.
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
A common issue with properties file is to handle the reloading of the file when it
changes. Typically you would use a thread monitoring the date of the file and reloading
the Properties
when a more recent date is detected. Commons Configuration
integrates this mechanism out of the box, to enable it, just specify a reloading strategy
on your configuration:
PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties"); config.setReloadingStrategy(new FileChangedReloadingStrategy());
Now everytime you edit manually the usergui.properties
file, the
configuration is automatically refreshed and the modified values are immediately
available to your application.
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);
And if you don't want to bother saving your configuration everytime it changes, you can enable the automatic saving mode:
PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties"); config.setAutoSave(true); config.setProperty("colors.background", "#000000); // the configuration is saved after this call
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 directly with:
String[] colors = config.getStringArray("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;
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 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