Using Maven with XBRLAPI
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
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
Verify the installation by running
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
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
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.
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
- Project POM
- XBRL API
- Oracle Berkeley XML Database data store
- eXist XML Database stand-alone data store
- eXist XML Database embedded data store
- Utilities - common components required by other modules
- XBRL Dimensions module
- XLink module
- XML Base module
- X-Pointer module
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
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.