oss

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.5 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:

where YYYYMMDD is the date on which the XBRLAPI JAR files were generated.

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, xbrlapi-exist, or xbrlapi-xindice 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
xalan.jar 2.7.0 Xalan XSLT 1.0 and XPath 1.0 processor xbrlapi-api
exist-1.1.1.jar 1.1.1 eXist XML database xbrlapi-exist
xindice-1.1.jar 1.1 Xindice XML database xbrlapi-xindice
xmldb.jar eXist version XML:DB API as distributed with eXist 1.1.1 xbrlapi-exist and xbrlapi-xindice
xmlrpc-1.2-patched.jar 1.2 patched for eXist XML RPC API as distributed with eXist 1.1.1 xbrlapi-exist and xbrlapi-xindice
commons-logging-1.0.3.jar 1.0.3 Apache Commons Logging framework xbrlapi-xindice
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 (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 sends log messages to the output 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/

Test using the in-memory data store.

You should now be ready to use the XBRLAPI in conjunction with various types of supported data stores. To test that this is indeed the case, try using the XBRLAPI from the command line.

A simple test of the XBRLAPI using the in-memory data store involves loading the XBRL instance schema using XBRLAPI. An appropriate command is:
java -jar xbrlapi-api-YYYYMMDD.jar -logger [LOG4J.CONFIG] -class org.xbrlapi.data.dom.Load -cache [CACHE.LOCATION] [URL]+

Alternatively, if you are identifying the JAR files that you require using the -classpath parameter, then something more like the following will be appropriate:
java -classpath xerces.jar:xalan.jar:xml-apis.jar:junit.jar:log4j-1.2.13.jar:xbrlapi-api-YYYYMMDD.jar:xbrlapi-xpointer-YYYYMMDD.jar:xbrlapi-xmlbase-YYYYMMDD.jar:xbrlapi-xlink-YYYYMMDD.jar:xbrlapi-utilities-YYYYMMDD.jar \ org.xbrlapi.Run -logger [LOG4J.CONFIG] -class org.xbrlapi.data.dom.Load -cache [CACHE.LOCATION] [URL]+
This of course, assumes that the necessary JAR files are all in the current directory.

Note that you will need to replace YYYYMMDD with the year, month and day values in your copy of the XBRLAPI JAR file.

Replace [LOG4J.CONFIG] with the path to (and name of) the log4j configuration file.

Replace [CACHE.LOCATION] with the full path to the directory you want to use for local caching.

Replace [URL]+ with one or more URLs specifying the starting points to use for the XBRL data discovery and loading process.

For example, if you are working with xbrlapi-api-YYYYMMDD.jar and the log4j.xml file is in the current directory and the current directory is also to be used as the root of the taxonomy cache, then the command to load data using the XBRL instance schema as a starting point would be:

java -jar xbrlapi-api-YYYYMMDD.jar -logger log4j.xml -class org.xbrlapi.data.dom.Load -cache . http://www.xbrl.org/2003/xbrl-instance-2003-12-31.xsd

Note the -class parameter which specifies the class to execute. Instead of simply performing a load operation using the org.xbrlapi.data.dom.Load class, you can perform a more complex compose operation (merging all of the discovered documents into a single XML composite document) by using the following command:

java -jar xbrlapi-api-YYYYMMDD.jar -logger [LOG4J.CONFIG] -class org.xbrlapi.data.dom.Compose -cache [CACHE.LOCATION] -output [OUTPUT.LOCATION] [URL]+

Replace [OUTPUT.LOCATION] with the path to the directory where you want the composite document to be saved.

Running the Unit tests distributed with XBRLAPI

A more comprehensive test of your XBRLAPI installation is possible using the JUnit tests that are distributed with XBRLAPI.

SourceForge Logo