XBRLAPI installation and configuration on MS Windows (TM)
This page is relevant to those looking to use XBRLAPI in their own MS Windows environment.
Download and install the latest Java JDK for Windows.
Ensure the Java bin folder path is added to the PATH variable
under System Variables. Select Start -> My Computer -> System
Properties -> Advanced system settings -> Advanced tab ->
Environment Variables -> System variables -> PATH. Prepend
Files\Java\jdk1.6.0_22\bin; to the beginning of the PATH variable (Note
that the jdk number will depend on which version of Java you have
To check that Java has been installed correctly, type java -version at the command line. It should come back with whatever version you have installed.
Install Oracle Berkeley XML Database
Download and run the latest Oracle Berkeley DB XML database MSI Windows Installer
Follow the prompts for the MS Installer file and select the option to update environment variables.
Ensure the Oracle bin folder path is on the PATH variable under
System Variables as done above for Java but prepending the PATH with
Files\Oracle Berkeley DB XML 2.5.16\bin;
Ensure that the db.jar and dbxml.jar files distributed with the Oracle database are on the CLASSPATH System Variable. Select Start -> My Computer -> System Properties -> Advanced system settings -> Advanced tab -> Environment Variables -> System variables -> CLASSPATH
Prepend the CLASSPATH sytem variable value with
Files\Oracle\Berkeley DB XML 2.5.16\jar\dbxml.jar;C:\Program
Files\Oracle\Berkeley DB XML 2.5.16\jar\db.jar;
There are two options: one for commandline usage of the API and one for usage within Eclipse.
The command line involves fewer installations and is thus initially a quicker solution. However, Eclipse IDE (or any IDE) makes it easier to run programs and set their arguments (since you can save the arguments in Eclipse as default whenever you run the program, while you have to manually record what arguments you use on the command line) and allows you to navigate through programs to better understand what is being referenced, among other things. If you are planning to use this XBRLAPI for extended interactions with the XBRL data, using an IDE is a good idea.
Install the XBRLAPI for commandline usage (option 1)
Download the latest single xbrlapi-X.X.jar from Sourceforge.
Ensure that the XBRLAPI jar file is on your Java CLASSPATH. The
easiest way to do this is to put the jar files in the
directory under the Java path (for example,
Install the XBRLAPI for usage within Eclipse (option 2)
Set up Eclipse
Download Eclipse IDE for Java EE Developers.
Unzip the eclipse file into a directory. It’s recommended that the directory be close to the root (for example, C:\Eclipse). Once the file is unzipped, simply open Eclipse by running the eclipse.exe file.
Ensure there are no additional files in the jre\lib\ext directory beyond the ones standard with Java (this sometimes causes Eclipse to use the wrong libraries). So, if you put the XBRLAPI jar files and Oracle jar files in the jre\lib\ext directory for command line installation, you’ll need to remove them for Eclipse to run.
Run/open Eclipse by double-clicking or running eclipse.exe in the Eclipse folder. There is no installation step; you simply run the executable file.
Install the Subversion Eclipse Plugin
This step is necessary for you to checkout/download the current XBRLAPI source files and quickly update to reflect any future changes
In Eclipse, go to Help-> Install New Software -> Available Software Sites and search for "subversive". Select the Eclipse Subversive Download site (community.polarion.com) and click the "Add" button
Back on the original Eclipse Available Software Sites dialog box, select the Subversive site from the drop-down list by the words "Work with:"
Select the checkbox next to "Subversive SVN Connectors" and follow the steps to install the software.
Set up a connection to the XBRLAPI project
In Eclipse, go to Window -> Open Perspective-> Other-> SVN Repository Exploring
Create a new repository location by clicking on the drop-down portion of the "New" icon on the left of the toolbar and selecting "New Repository Location"
as the URL.
Expand the XBRLAPI subversion repository to show the branches and trunk. Right-click on the trunk and choose "Check-out".
Configure the XBRLAPI project properties
Go to Window -> Open Perspective -> Java and right-click on the trunk of the xbrlapi project and choose "Properties". Choose "Java Build Path" from the list of properties in the dialog box and then the "Libraries" tab.
Make sure the following libraries are listed:
- JRE System Library
- xbrlapi.org user library
If the libraries are not listed, add them by choosing "Add Library..." -> User Library -> "User Libraries..." -> "New..." and then adding the relevant jar files by using "Add JARs..." and selecting the jars in the java\lib directory in your Eclipse project folder.
Running a simple example
Create a folder called "container" (or whatever you want) that will hold the Oracle database files to be created.
Create a folder called "cache" (or whatever you want) that will be used by the programs to cache copies of XBRL documents that are loaded into the data store. This cache allows you to operate offline after the first interaction with the XBRL files.
An example command to load the XBRL 2.1 instance schema might be:
java -Xmx1g -Dlog4j.configuration=log4j.xml org.xbrlapi.data.bdbxml.examples.load.Load -database C:\Documents\XBRLAPI\container -container TestContainer -cache C:\Documents\XBRLAPI\cache http://www.xbrl.org/2003/xbrl-instance-2003-12-31.xsd
The Xmx1g option increases the java heap size. Use this if you get java.lang.OutofMemoryError.
The Dlog4j.configuration option specifies the location and name of the LOG4J logging configuration file.
The database argument is the directory you want to store the new container in. Create this folder before running the command.
The container argument is the name you want assigned to the dataset. This can be anything.
The cache argument is the directory you want to the program to store various files in. Create this folder before running the command.
The URL is the address for the instance document or schema you want stored in the dataset. This can be any xbrl file.
Keep in mind for all these directory paths that any spaces in the paths will cause Windows trouble at the command line. Avoid spaces if possible. If you can't avoid them, consider making a symbolic reference (i.e. shortcut) to the directory. For example, type mklink /d C:\xbrl_db "C:\Sample Path\XBRL API" at the command line to make a shortcut reference C:\xbrl_db that points to the directory C:\Sample Path\XBRL API (which has problematic spaces).
Access the Java perspective by clicking on Window -> Open Perspective -> Java
Open the class:
Set configurations by going to Run-> Run Configurations and
choosing to set configurations for a Java Application called Load. Make
sure the main class is listed as
Set the following Program arguments (without quotes, but with a space or line break between each argument), using the path for your xbrlapi data instead of C:\Documents\XBRLAPI (See the description of each argument in the Command Line instructions above)
- (only if you have 2 GB RAM or have gotten errors about not enough memory) "-dbCacheSize 500"
- -database C:\Documents\XBRLAPI\container
- -container TestContainer
- -cache C:\Documents\XBRLAPI\cache
Set the following VM argument:
Select "Apply" to save and apply the arguments, and then select "Run" to run the program. The Console at the bottom of the screen should show that the document was successfully added.
If you get errors that seem to be about the Oracle Berkeley database (for example, "no libdb_java48"), make sure that Oracle bin folder path is at the beginning of the PATH variable (before the Java bin folder) (as specified above). Also make sure that the Oracle db.jar and dbxml.jar files are in the CLASSPATH variable (as specified above).
If you get errors about the amount of storage space (for example, "PANIC: Not enough space"), make sure to specify the Oracle database cache size as smaller (500MB, for example) as an argument when running Java programs. This is a parameter to the org.xbrlapi.bdbxml.data.StoreImpl constructor.
If you get errors about classes not being found, try downloading the dependency jars from http://xbrlapi.svn.sourceforge.net/viewvc/xbrlapi/trunk/java/lib/ and adding them to the Java CLASSPATH.
This page has been contributed by Beth Blankespoor.