Overview

Commons Configuration can be built using maven or ant. While building on a JDK 1.4 and higher should be no problem for JDK 1.3 (which is the minimum required JDK) some preparations are necessary. This is covered in full detail in the Building with JDK 1.3 section below.

Maven Goals

Maven 1.x is our recommended build tool. To build the Configuration jar file, change into the directory where you unzipped the source distribution or where you checked out the sources from SVN and run "maven jar". The result will be in the (newly created) "target" subdirectory.

To build the Javadocs, run "maven javadoc". The result will be in "target/docs/apidocs".

To build the full website, run "maven site". Note: For this to work you will also have to checkout the commons-build module as a sibling directory to your Configuration root directory. The result will be in "target/docs".

Ant Goals

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/docs/apidocs".

Building with JDK 1.3

If you want to build Commons Configuration on a JDK 1.3, you will face two problems:

The first problem is that JDK 1.3 does not contain the JDBC 2.0 standard extensions, which are used by the DatabaseConfiguration class. Unfortunately, due to legal issues, the jar file containing these extensions cannot be distributed through the typical maven repositories and automatically downloaded. To resolve this issue perform the following steps:

• Download the JDBC 2.0 Optional Package from http://java.sun.com/products/jdbc/download.html and store the jdbc-stdext-2.0.jar somewhere on your hard disk.
• Create a build.properties file in the Configuration root directory that must contain the following line:
  
  dependency.jdbc = <path to jdbc-stdext-2.0.jar>

The second problem is related to a test class for DatabaseConfiguration that makes use of hsqldb. At the time of writing this, the hsqldb jar files distributed on the ibiblio maven repository only support JDK 1.4 and higher. This makes the tests fail with a class not found exception for java.sql.SavePoint. There are some workarounds for this problem:

• Disable the failing test class (org.apache.commons.configuration.TestDatabaseConfiguration) in the build script. For instance if building with maven, this can be done with an excludes element in the unitTest section of project.xml.
• It is possible to download a hsqldb distribution and recompile on JDK 1.3. The jar that is created this way will cause no problems on a JDK 1.3.
• Another solution would be to run maven on a JDK 1.4 or higher and use the maven.compile.executable property to point to a JDK 1.3 compiler. This will ensure that the classes are compiled on JDK 1.3, but the tests are run on the JDK maven is executing. Refer to the documentation of the Maven Java Plug-in for further information.

If these problems are solved, the build can be performed as described above.

Setting custom build parameters

Both the maven and the ant build script support a file called build.properties that can contain custom properties definitions. If this file exists in the project's root directory, it will be read and the properties it defines will be added to the running build script. This mechanism allows for customizing the build process without the need of changing the main build scripts.

One use case for setting custom build properties would be to build for a specific JDK version: If you build the jar on a JDK 1.5 for instance, the classes won't be compatible with older JDK versions. To enforce compatibility you can create a build.properties file containing the following maven specific settings:

maven.compile.source = 1.3
maven.compile.target = 1.3