Using Maven with XBRLAPI
Overview
Maven is a build management tool that can be used to simplify the process of building XBRLAPI, managing the dependencies on third party JAR files, and automating the process of running unit tests.
Check the XBRLAPI source code out from the SVN repository
See the
Sourceforge instructions on getting a
copy of the XBRLAPI SVN repository. At its simplest you should use the
following command at the command line if you have an appropriate SVN client
installed in your own environment:
svn co https://xbrlapi.svn.sourceforge.net/svnroot/xbrlapi xbrlapi
Install Maven 2.0 or later
Download Maven 2.0 or later.
You download an archive file that needs to be extracted to the local file system. Once the
archive file is extracted, there is no additional installation process as such. However, you may
want to configure your environment to find the mvn command regardless of the current
directory.
Verify the installation by running mvn --version.
Sort out dependencies that are not supported by online Maven repositories
Maven does a great job of providing the necessary JAR files based upon the dependencies documented in the Maven program object models (POM files). However, some of the JAR files that XBRLAPI has dependencies on are not yet available from the online Maven repositories. These dependencies have to be addressed manually by placing the appropriate JAR files into the local Maven repository.
Adding a new custom JAR to the local MAVEN repository is done as follows (using eXist 1.1.1 as an example):
mvn install:install-file -DgroupId=exist -DartifactId=exist -Dversion=1.1.1 -Dpackaging=jar -Dfile=exist-1.1.1.jar
This needs to be run from the directory containing the JAR file to be added to the local repository.
Depending on the modules that you want to use, the following third party JAR files need to be inserted into the local MAVEN repository using the approach described above. Note that, if you do not want to use a persistent data store then none of these JAR files are required in the local MAVEN repository.
| Dependency for | Jar file | Group ID | Artifact ID | Version | Download | Notes | |
|---|---|---|---|---|---|---|---|
| xbrlapi-exist | exist-1.1.1.jar | exist | exist | 1.1.1 | eXist | This JAR contains the eXist implementation. It must be obtained from the eXist distribution. See eXist required library documentation for details. | |
| xbrlapi-exist and xbrlapi-xindice | xmldb.jar | exist | xmldb-api | custom | eXist. | This JAR contains the XML:DB API. It must be obtained from the eXist distribution where it has been modified for eXist if you intend to use it with an eXist data store. Otherwise it may be obtained from either the Xindice distribution or the XML:DB project. Xindice appears to work with the version provided by the eXist distribution. See eXist required library documentation for details. | |
| xbrlapi-exist and xbrlapi-xindice | xmlrpc-1.2-patched.jar | exist | xmlrpc | 1.2-patched | eXist | This JAR contains the XML RPC API. It must be obtained from the eXist distribution where it has been patched for eXist if you intend to use it with an eXist data store. This version also appears to work with Xindice. | |
| xbrlapi-xindice | xindice-1.1.jar | org.apache | xindice | 1.1 | Xindice | This JAR contains the Xindice implementation. It must be obtained from the Xindice installation. | |
| xbrlapi-bdbxml | db.jar | com.oracle.berkeley | db | 2.3.10 | Build documentation | After downloading the source, you need to run
./buildall.sh --enable-java --prefix=/usr/local/BerkeleyDBXML.2.3.10making sure that you use the appropriate version number for the installation directory. db.jar can be found in the lib directory of the installation. | |
| xbrlapi-bdbxml | dbxml.jar | com.oracle.berkeley | dbxml | 2.3.10 | Build documentation | After downloading the source, you need to run
./buildall.sh --enable-java --prefix=/usr/local/BerkeleyDBXML.2.3.10making sure that you use the appropriate version number for the installation directory. dbxml.jar can be found in the lib directory of the installation. |
Modify the POM files for your own environment
The XBRLAPI source has been divided into a number of different modules. Each module has its own POM.xml file. These module POM files are all referenced by the POM file in the root directory of the XBRLAPI source code. These POM files contain some information about the structure of the local file system that you will need to tailor to your own environment.
The POM files for each module (found in the module-xxx) directories) all define a
surefire-plugin property, called xbrlapi.test.configuration that identifies
the location of the test configuration properties file. This location needs to specify
the location of the test properties file that you want to use.
The POM files also specify the location of the log4j.xml logging configuration file that should be used in your own environment. This file location is specified at the end of the POM files in the test properties section. In most cases, if you have checked out the full XBRLAPI source tree, then a workable log4j.xml file will have been checked out into a conf directory. In such cases, the POM files will already refer to this log4j configuration file and no POM file modifications will be necessary.
The POM file for the bdb-xml project, contained in the module-bdb-xml directory
also specifies the location of the Oracle Berkeley DB XML database binaries. This needs to be
set to the appropriate location in your own environment. See the argLine element
in the surefire plugin configuration. Without setting this correctly, it will not be possible
to run the unit testing for the data store based on the Oracle Berkeley DB XML database.
If you have ideas on how to make the POM files more portable across platforms and environments then please put them forward.
Running Maven
The XBRLAPI source has been divided into a number of different modules. Each module
has its own POM.xml file. These module POM files are all referenced by the POM file in the
root directory of the XBRLAPI source code. To perform a Maven operation on the entire XBRLAPI
installation, issue the Maven command from the root directory of the XBRLAPI checked out from
the SVN repository. For example, to build and test all modules, run mvn test
from the command line when the current directory is the XBRLAPI root directory.
To build, test and install all modules, run mvn install from the command
line when the current directory is the XBRLAPI root directory.
The same commands can be run from the module-xxx directory to just operate
on that specific module. This is the approach that will need to be taken if you decide
not to install the necessary custom JAR files required by the persistent data store modules.
Note that installation involves copying the generated JAR file(s) into the local Maven repository, ready to be referenced as dependencies by other projects or modules.
See the Maven documentation for more details on what can be done with Maven.