##### Configuration

- Home
- Download
- User's Guide
- Howtos (Release 1.2)
- Runtime Dependencies
- Building
- Roadmap
- Javadoc (Release 1.3)
- Javadoc (Release 1.2)
- Javadoc (Release 1.1)
- Javadoc (Release 1.0)
- SVN

##### Extensions

- Avalon Component

##### Project Documentation

- About
- Downloads
- Project Info
- Project Reports
- Development Process

##### Commons

- Home
- Components
- Sandbox
- Dormant
- Volunteering
- Contributing Patches
- Building Components
- Releasing Components
- Wiki

##### Legend

- External Link
- Opens in a new window

## 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