Using the XBRLAPI from the command line
Overview
This page is relevant to those looking to perform some basic command line tests that XBRLAPI is available from their commandline.
Get Java on the command line
Type java -version at the command line to see if Java is available.
You should see a message indicating that the java version is 1.6 or later. See the
Java configuration page if you run into troubles.
Get the necessary JAR files
Ensure that the XBRLAPI JAR files are on the class path. This can be done by placing them in the lib/ext directory in the Java installation. It can also be done by modifying the CLASS_PATH environment variable to include the directory that contains the XBRLAPI JAR files. It can also be done by ensuring that the current directory for the command line operations also contains the XBRLAPI JAR files.
At a minimum you will need:
- xbrlapi-utilities-VERSION.jar
- xbrlapi-api-VERSION.jar
- xmlbase-api-VERSION.jar
- xlink-api-VERSION.jar
- xpointer-api-VERSION.jar
where VERSION is the XBRLAPI release VERSION.
Download the necessary XBRLAPI modules as JAR files from Sourceforge. You will definitely require the xbrlapi-utilities module, the xbrlapi-api module, the xbrlapi-xlink, xbrlapi-xpointer and xbrlapi-xmlbase modules. If you want to use a persistent data store, then you will also require one of the xbrlapi-bdb-xml or xbrlapi-exist modules.
You will also require some third party JAR files. Depending on the XBRLAPI modules that you require, you may need to obtain the following JAR files:
| JAR file | Version | Purpose | Requiring modules |
|---|---|---|---|
| log4j-1.2.13.jar | 1.2.13 | logging framework | xbrlapi-utilities |
| xml-apis.jar | 1.3.04 | XML API for Xerces | xbrlapi-utilities |
| xercesImpl.jar | 2.8.1 | Xerces XML Parser | xbrlapi-utilities |
| junit.jar | 3.8.1 | JUnit unit testing | xbrlapi-utilities |
| saxon9.jar | 9.1 | Saxon 9.1 processor | xbrlapi-api |
| saxon9.jar | 9.1 | Saxon 9.1 processor | xbrlapi-api |
| saxon9-dom.jar | 9.1 | Saxon 9.1 processor - to enable operations on XML DOM structures | xbrlapi-api |
| saxon9-s9api.jar | 9.1 | Saxon 9.1 processor - to enable S9API XQuery operations | xbrlapi-api |
| google-collect-1.0.jar | 1.0 | Google Collections Extension Library | xbrlapi-api |
| exist-1.1.1.jar | 1.1.1 | eXist XML database | xbrlapi-exist |
| xmldb.jar | eXist version | XML:DB API as distributed with eXist 1.1.1 | xbrlapi-exist |
| xmlrpc-1.2-patched.jar | 1.2 patched for eXist | XML RPC API as distributed with eXist 1.1.1 | xbrlapi-exist |
| db.jar | 2.3.10 | Berkeley DB Java interface to binaries | xbrlapi-bdb-xml |
| dbxml.jar | 2.3.10 | Berkeley DB XML overlay: Java interface to binaries | xbrlapi-bdb-xml |
To make things easy, these have been included in the SVN repository for the XBRLAPI so if you check out the XBRLAPI project from SVN then you should have them all. Alternatively you can download those that you require directly from the browseable SVN repository on Sourceforge.
Put the JAR files on your CLASS_PATH
Make sure that all of the necessary JAR files (the XBRLAPI ones and the third party dependency ones) are on your Java CLASS_PATH. If you have installed a complete Java SDK, then a very simple way to achieve this outcome is to place them in your $JAVA_HOME/jre/lib/ext directory where $JAVA_HOME is the value of the JAVA_HOME environment variable set when you installed your Java SDK. If you are identifying the necessary JAR files using the -classpath parameter, then be sure not to also use the -jar parameter for the Java runtime engine.
Configure log4j
You need to configure log4j.
This configuration is specified in an XML file. A useful starting point for such
a
log4j configuration is available from the online SVN browsing facility at Sourceforge. Download
the log4j.xml file and its DTD (or if you have checked out the entire XBRLAPI project, then just use the log4.xml
file that is in the conf directory of the XBRLAPI project) and store it somewhere
convenient, say /configuration/file/path/log4j.xml. This configuration file
is set up to send log messages to the console.
Configure your local cache for XBRL documents
The XBRLAPI caches any documents that are loaded into a data store. You need to set
up a writeable folder to store this cache. When populated, the cache will contain a local
copy of each of the XML documents that are discovered during the loading process.
Refer to the directory where the local copies are to be cached as:
/xbrl/cache/
At this point you have just about enough basicd configuration to run your own programs using the XBRLAPI from the commandline. There are a few specific commandline programs with more detailed documentation in the examples on this website.
Running the Unit tests distributed with XBRLAPI
A more comprehensive test of your XBRLAPI installation is pFree Open-Source Softwareible using the JUnit tests that are distributed with XBRLAPI.