##### Configuration

- Home
- Download
- Release History
- User's Guide
- Howtos (1.2 release)
- Runtime Dependencies
- Javadoc (current release)
- Javadoc (old releases)

##### Development

- Building
- Roadmap
- Issue Tracking
- SVN

##### Project Documentation

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

##### Commons

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

## Properties files

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.

### Using PropertiesConfiguration

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:

- 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 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"));

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

### Lists and arrays

As was already pointed out in the section List handling of Basic features, Commons Configuration has the ability to return easily a list of values. For example a properties file can contain 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;

All of the features related to list handling described for `AbstractConfiguration` also apply to properties files, including changing the list delimiter or disabling list handling at all.

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

More information about saving properties files (and file-based configurations in general) can be found in the section about File-based Configurations.

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

### Layout Objects

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.