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 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". The result will be in "target/docs".
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".
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:
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:
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.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.
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