Free Open-Source Software

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.

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 pFree Open-Source Softwareible to run the unit testing for the data store based on the Oracle Berkeley DB XML database. It needs to specify to the directory containing the binary library files that operate the database you are using.

If you have ideas on how to make the POM files more portable acrFree Open-Source Software platforms and environments then please put them forward.

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 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.4 as an example):

mvn install:install-file -DgroupId=exist -DartifactId=exist -Dversion=1.4 -Dpackaging=jar -Dfile=exist-1.4.jar
This needs to be run from the directory containing the JAR file to be added to the local repository.

A shell script that takes care of this for you is available from the source repository. It will need to be run from within the directory containing the relevant JAR files.

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.

The up-to-date dependencies for each module released by the XBRLAPI project are documented in the Maven POM files for the project and its modules

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.

Get Java XBRL API implementation at SourceForge.net. Fast, secure and Free Open Source software downloads