File Systems

In its default mode of operation Commons Configuration supports retrieving and storing configuration files either on a local file system or via http. However, Commons Configuration provides support for allowing other File System adapters. All file access is accomplished through the FileSystem interface so accessing files using other mechanisms is possible.

Commons Configuration also provides a second FileSystem which allows retrieval using Apache Commons VFS. As of this writing Commons VFS supports 18 protocols for manipulating files.

Configuration

The FileSystem used by Commons Configuration can be set in one of several ways:

A system property named "org.apache.commons.configuration.filesystem" can be defined with the full class name of the desired FileSystem implementation to set the default FileSystem.
FileSystem.setDefaultFilesystem() can be called to directly set the default FileSystem implementation.
DefaultConfigurationBuilder.setFileSystem() can be called to set the FileSystem implementation. DefaultConfiguratonBuilder will use this for each configuration it creates
DefaultConfigurationBuilder can be configured with the FileSystem to be used when creating each of the configurations.
Each Configuration referenced in DefaultConfigurationBuilder's configuration can be configured with the FileSystem to use for that configuration.
Call setFileSystem() directly on any Configuration that implements FileSystemBased. Both AbstractFileConfiguration and AbstractHierarchicalFileConfiguration implement FileSystemBased

The example that follows shows how to add FileSystem configuration to DefaultConfigurationBuilder.


<configuration>
  <header>
    <result delimiterParsingDisabled="true" forceReloadCheck="true">
      <expressionEngine config-class="org.apache.commons.configuration.tree.xpath.XPathExpressionEngine"/>
    </result>
    <fileSystem config-class="org.apache.commons.configuration.VFSFileSystem"/>
  </header>
  <override>
    <xml fileName="settings.xml" config-name="xml">
      <fileSystem config-class="org.apache.commons.configuration.DefaultFileSystem"/>
    </xml>
  </override>
</configuration>

File Options Provider

Commons VFS allows options to the underlying file systems being used. Commons Configuration allows applications to provide these by implementing the FileOptionsProvider interface and registering the provider with the FileSystem. FileOptionsProvider has a single method that must be implemented, getOptions, which returns a Map containing the keys and values that the FileSystem might use. The getOptions method is called as each configuration uses VFS to create a FileOjbect to access the file. The map returned does not have to contain the same keys and/or values each time it is called. For example, the value of the currentUser key can be set to the id of the currently logged in user to allow a WebDAV save to record the userid as a file attribute.

File Reloading Strategy

The VFSFileChangedReloadingStrategy can be used to cause Configurations accessed via the VFSFileSystem to be monitored and reloaded when the files are modified. The example below shows how DefaultConfigurationBuilder can be configured to use VFSFilChangedReloadingStrategy. In the example below both test.properties and settings.xml would be checked for changes once per minute.


<configuration>
  <header>
    <result delimiterParsingDisabled="true" forceReloadCheck="true">
      <expressionEngine config-class="org.apache.commons.configuration.tree.xpath.XPathExpressionEngine"/>
    </result>
    <fileSystem config-class="org.apache.commons.configuration.VFSFileSystem"/>
  </header>
  <override>
    <properties fileName="test.properties" throwExceptionOnMissing="true">
      <reloadingStrategy refreshDelay="60000"
        config-class="org.apache.commons.configuration.reloading.VFSFileChangedReloadingStrategy"/>
    </properties>
    <xml fileName="settings.xml" config-name="xml">
      <reloadingStrategy refreshDelay="60000"
         config-class="org.apache.commons.configuration.reloading.VFSFileChangedReloadingStrategy"/>
    </xml>
  </override>
</configuration>