Oracle Berkeley Database XML data store configuration

Overview

This page is relevant to those looking to use the XBRLAPI with the Oracle Berkeley Database XML data store. It provides very terse suggestions on the steps required to get the Oracle Berkeley Database XML database running in a manner that will permit interaction from the XBRLAPI.

You will need to download or otherwise have the xbrlapi-bdbxml module on the class path to use the Oracle Berkeley Database XML data store.

Install the binaries (MS Windows only)

You can install the database directly on computers with a modern MS Windows operating system. Simply run the MS Installer file that can be downloaded from the Oracle website. Otherwise you will need to install the software by building it from source.

Download the source code from Oracle

Get the sources from the Oracle website.

Build the source code and install it

Unzip the tar.gz download. Change directory to the root directory created by the extraction process. Run ./buildall.sh --enable-java --prefix=/usr/local/BerkeleyDBXML-2.5.16
making sure that you use the appropriate version number for the installation directory. This command will build the binaries and install them in the directory specified by the --prefix parameter. The --enable-java parameter ensures that the necessary Java JAR files to manage the interface to the database binaries are also created.

See the Oracle documentation resources for more details.

Set up Java Virtual Machine to use the database

Ensure that any JVM that is running code that uses the database is called with the JVM parameter: -Djava.library.path=/usr/local/BerkeleyDBXML-2.5.16/lib
to ensure that the C++ binary libraries are correctly linked to.

Also ensure that the dbxml.jar and db.jar files are on the class path. You can find these JAR files in the lib directory created as a part of the installation directory.

Using the database from a Java servlet container

If using a Java servlet container, adding the library directory (/usr/local/BerkeleyDBXML-2.5.16/lib) to the the LD_LIBRARY_PATH environment variable on Linux should allow the JVM running the servlet container to find the correct libraries.

Better still, at least on UBUNTU, create a new configuration file /etc/ld.so.conf.d/bdbxml.conf and give it the content: /usr/local/BerkeleyDBXML.2.3.10/lib though note that this value for the parameter will depend on the path that you chose for installing the database binaries when you built them.

Using with the Maven Surefire plugin for unit testing

Add an argline element as a child of the configuration element for the surefire plugin and give the argline element the value -Djava.library.path=/usr/local/BerkeleyDBXML-2.5.16/lib where /usr/local/BerkeleyDBXML-2.5.16/lib is the location of the database binaries.

Unit testing

Once the Oracle Berkeley Database XML is installed you should be able to run all of the unit tests in the unit testing suite provided by org.xbrlapi.data.bdbxml.tests package. If you run into problems make sure that the Oracle Berkeley Database XML test configuration parameters reflect your own Oracle Berkeley Database XML installation.