Properties files

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.

Loading

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:

  • in the current directory
  • in the user home directory
  • in the classpath

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

  • a file, specified by either a path or a java.io.File object
  • a URL
  • an input stream or a reader.

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.

Includes

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

Automatic Reloading

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.

Saving

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

Lists and arrays

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;

Variable Interpolation

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}

Special Characters

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