Apache Commons logo Commons Configuration

Overview

Commons Configuration can be built using maven or ant.

Maven 2

Commons Configuration uses Maven 2 as its build tool. The recommended version is Maven 2.2.1. To build the Configuration jar, change into the directory where the source distribution resides and run "mvn install". This will compile the source and tests, run the tests, and then package the jar. The jar will also be copied into the local maven repository for use by other builds.

This build requires a JDK 1.5 or higher. It is possible to build Commons Configuration on a JDK 1.4 by specifying the "java-1.4" profile: "mvn install -Pjava-1.4". This profile and the settings required are described in detail in Testing with different Java versions. If this profile is active, some classes depending on Commons VFS (which is available for Java 1.5+ only) are excluded from compilation.

To build the web site run "mvn site". When it completes the web site will reside in the target/site directory and may be viewed by opening target/site/index.html.

Running Functional Tests

TestWebdavConfigurationBuilder is a functional test that tests DefaultConfigurationBuilder with the configuration files stored in a WebDAV server. To run the test the steps that follow

  1. Copy all the files in the conf directory to the WebDAV server. Not all the files are required but it is generally easier to use a tool like cadaver and do an mput than try to copy the required files individually.
  2. Add the following to the profiles section of settings.xml in the Maven home directory. Modify the urls to match your setup.
       <profile>
        <profile>
          <id>webdav</id>
          <activation>
            <activeByDefault>false</activeByDefault>
          </activation>
          <properties>
            <test.webdav.base>webdav://vfsusr:vfstest@192.168.10.133:80/conf</test.webdav.base>
          </properties>
        </profile>
  3. run "mvn -P webdav test -Dtest=TestWebdavConfigurationBuilder". The test can also be run using "mvn -P webdav test" but this will run all the unit tests in addition to the WebDAV test.

Building with Ant

In order to build the project with Apache Ant, some manual preparations have to be done. The problem is that Commons Configuration uses classes generated by JavaCC to process configuration files in specific formats. These classes are produced dynamically during the build process. While Maven is able to download all required artifacts automatically, the Ant build is not that smart. Therefore, it is required to download and install JavaCC manually. Then a file named build.properties has to be created in the root directory of Commons Configuration which defines the javacc_home property; here the path to the JavaCC installation has to be set. Commons Configuration already ships with a build.properties.sample file which can be copied and adapted correspondingly.

After these preparations have been done, the following Ant goals can be used:

  • To build a jar file, change into Configuration's root directory and run "ant jar". The result will be in the "target" subdirectory.
  • To build the Javadocs, run "ant javadoc". The result will be in "target/site/apidocs".