The XBRL Composer software is covered by the GNU general public licence.
2 April, 2004
Abstract
The XBRL composer is a Java library that facilitates efficient compilation of a discoverable taxonomy set (DTS) as defined in the XBRL 2.1 specification. These objects can be serialized as XML documents and saved to files. Such files can also be loaded directly as a Java DTS object.
Note that this project has spawned another open source project, XBRLAPI, that goes beyond the compilation of an XBRL DTS to define and implement a comprehensive XBRL API in Java.
Table of Contents
The discoverable taxonomy set is formed by XLink processing the documents that together comprise a DTS.
The XBRL composer software extends on the DTS defined in the XBRL specification by permitting the document set to include XBRL instances as well as taxonomy schemas and linkbases.
The javadoc documentation of the classes comprising the XBRL Composer software is also available.
You will require a Java runtime environment to use the XBRL composer classes. The classes have been tested on the Sun 1.4.2 JRE.
You will also require the Xerces and Xalan libraries, available from the Apache website
.To get a basic working installation in place on a MS Windows system, do the following:
- Obtain and install the JRE software from Sun which can be downloaded from the Sun Java website.
- Download the Xerces JAR files from the Apache website. and place them in the {ROOT}\{JAVA}\lib\ext directory. The required JAR files are xercesImpl.jar and xml-apis.jar and xmlParserAPIs.jar. The {JAVA} directory is the root of the directory structure created by installing the Java Runtime environment.
- Download the Xalan JAR files from the Apache website. and place them in the {ROOT}\{JAVA}\lib\ext directory. The required files are xalan.jar and xsltc.jar and bsf.jar.
- Place the xbrl composer JAR file, xbrlcomposer-YYYYMMDD.jar in the {ROOT}\{JAVA}\lib\ext directory.
- Create a directory to store the taxonomy cache in so that the XBRL composer software can cache documents for offline usage. A large tree structure of taxonomy and instance documents can build up under this cache root directory over time. Call this directory the CACHEROOT directory.
At this stage you are prepared to use the XBRL composer software either using a command line approach or using the various API's exposed by the XBRL composer classes.
The XBRL composer provides a variety of functionality via the commandline interface. Some of these are memory intensive enough to require significant amounts of memory to be available. For this reason, it can be prudent run the Java runtime engine with additional memory. This involves using the following java command:
java -Xmx1g net.sourceforge.xbrlcomposer.DTS [parameters] [URLS]
where the 1 in the Xmx1g argument can take any integer value.
The [URL]s in the command line is any set of URLs of XML documents including taxonomy schemas, XBRL linkbases and XBRL instances. These documents can be based on either the XBRL 2.0 or the XBRL 2.1 specification (or both although that is not really a great idea most of the time).
It is also possible to specify the starting point URL's using the file protocol instead of the http protocol so that you can avoid the need to have a web server serving up documents on the local file system. Better yet, you can specify the full path and file name of starting point documents in the local file system or the name and the path of the starting point documents relative to the directory from which the command line is being executed.
The commandline usage of the DTS class can take any of the following parameters:
-c CACHEROOT
specifies the location, within the local file system, of the document cache. If omitted then no taxonomy documents are cached locally and no locally cached documents are used. This can make usage of the software more difficult when internet access is restricted or unavailable. IF the CACHEROOT contains spaces, then surround it with double quote symbols.-d DECOMPOSITIONROOT
specifies the location, within the local file system, that should be used to store the documents in the DTS when decomposing it into the various documents that it is comprised of. The result of the decomposition act is to create a directory structure under the DECOMPOSITIONROOT that mirrors the information contained in the absolute URLs of the individual files making up the DTS. If the CACHEROOT contains spaces, then surround it with double quote symbols. If the XBRL Composer is being used as part of an XBRL taxonomy (or instance) editing application, then it may well make sense to set the DECOMPOSITIONROOT equal to the CACHEROOT. The DTS is not decomposed in this way unless the -d argument is used.-e EXISTINGDTSFILE
specifies the filename and location, within the local file system, of the existing DTS (previously serialized) to load into a DTS object and augment with the specified URLS. IF the EXISTINGDTSFILE contains spaces, then surround it with double quote symbols.-o FILENAME
specifies the name and location in the local file system of the file to be created once the DTS has been composed. If this parameter is not specified then the XML representation of the DTS is streamed to System.out. If the FILENAME contains spaces, then surround it with double quote symbols.-r CLASSNAME
specifies the class name of the entity resolver class to use when SAX parsing the documents in the DTS. This should not be used if the -c command line argument is used. Instead, it provides a simple hook for alternative entity resolvers to be used in place of the dynamic document caching system that is built into the XBRL Composer. For example, to use this argument to specify that you wish to use the DynamicEntityResolverImpl class that comes with the XBRL Composer (not that such a use of this argument makes much sense), specify-r net.sourceforge.xbrlcomposer.DynamicEntityResolverImpl
. The Java class that you specify will be dynamically loaded and instantiated
if you want to use the static entity resolution class instead of the dynamic entity resolution class, then you will need to have an XML file defining the mappings from the original URL's to the URL's that resolve to documents in the local cache.
This map has the following structure:
<mappings>
<map></map>
<map></map>
...
</mappings>
An example of a DTS created using the DTS class is available in a compressed (ZIPPED) format.
