XBRLInstance
Description
An XBRLInstance object represents the content of an XBRL Report. This is:
- all XBRL facts , and
- all XBRL contexts, and
- all XBRL units, and
- all Footnote Linkbases, and
- all references to XBRLTaxonomies, XBRLLinkbases, XBRLRoleRef and XBRLArcroleRef required for obtaining the DTS.
How to create an instance of an XBRLInstance object
There are several ways depending on what you are doing:
- If the user have just created a new empty DTSContainer object and the purpose is to read the content of an XBRL report (and the whole referenced DTS) then the simplest way is to use one of the load methods in the DTSContainer object passing the document URI of the XBRL report. The returned object is an XBRLDocument that can be casted to an XBRLInstance.
- If the user has already loaded a DTS (from a taxonomy file) and the purpose is to create a new XBRLInstance (in order to populate it with facts) then the user can use any of the available constructors. The most commonly used constructor is XBRLInstance(com.ihr.xbrl.om.DTSContainer) that accepts the current DTSContainer as a parameter and allows the user to start adding facts programatically.
Examples
Creation of a XBRLInstance object from a URL
/**
* Sample, a new instance document is read form the file received as a parameter
* After the instance object is obtained, the user can start working with it
*/
public class SampleReadInstance {
public static void main(String[] args) throws Exception {
DTSContainer dts = DTSContainer.newEmptyContainer();
XBRLInstance instance = (XBRLInstance)dts.load(new File(args[0]).toURI());
// ... rest of the application code goes here
}
}
Creation of a new instance docyment for a DTS after the DTS has been loaded
/**
* Sample, a new instance document is created after the DTS has been loaded
*/
public class SampleCreateInstanceForDTS {
public static void main(String[] args) throws Exception {
DTSContainer dts = DTSContainer.newEmptyContainer();
dts.load(new File("sampleTaxonomy.xsd").toURI());
XBRLInstance instance = new XBRLInstance(dts);
// ... rest of the application code goes here
}
}
Working with facts in an XBRLInstance
This section describes two abstract operations that the user can execute on XBRLInstance objects regardless the way they have been created.
The XBRLInstance object is able to automatically change in order to keep consistency during operations. For example, the action of adding a new XBRLFact item to the XBRLInstance may automatically add a new context or may reuse an existing context instead. The same happens with the unit and with the reference to the required taxonomy schema. Removing facts from the XBRLInstance is also an operation that keeps the instance document content consistent while silently removes content that is no longer used (like unused units or contexts etc).
Read access
Read access is an abstract operation implemented in several methods that allows the user to access to the content of the XBRLInstance. The content of an XBRLInstance can be accessed in two modes: sequential mode and indexed mode. Both modes are described in the XBRLFactsList interface.
Write access
Modifying the content of the XBRLInstance is normally implemented automatically inside the API at the time the user do operations that requires the API to keep the XBRLInstance consistent; for example, the action of creating a new fact automatically performs the operation of adding the new fact to the instance document. The user does not need to worry about how to keep consistency in the content of the XBRLInstance object.
Facts that the user can create with the API are:
Examples
In this example, the content of the XBRLInstance document is sequentially read in document order
Iterator<XBRLFact> iterF = instance.iterator();
while (iterF.hasNext()) {
XBRLFact f = iterF.next();
// ... do dome work with the fact
}
In this example, a new XBRLNumericFact is added to the XBRLInstance
// create the Non Numeric (Text) fact item
XBRLFactNonNumeric fA = new XBRLFactNonNumeric(instance,ctx,itemA);
// fA is nil until a value is assigned
fA.setValue(new StringValue("test"));
Other operations
Creating a footnote for a fact
Creating a footnote requires some initial work on the XBRLInstance:
Create the footnotes container
A footnotes container is an XLink extended link container for XBRL footnotes. In order to create the container the user should get the desired role type from the DTS and then call the FootnoteLinkbase constructor with the required parameters.
Here is an example about how to get the standard role URI and then create an extended link for footnotes
XBRLRoleType role = dts.getStaticRoleTypeByURI(XBRLExtendedLink.standard_role_URI); // Now create a container for footnotes (Footnote Extended Link) FootnoteLinkbase fl = new FootnoteLinkbase(instance, role);
Create the fact
Creating a fact is a very simple task. The user just need to call the apropriate constructor depending on the type of fact to be created. The final fact types that the user can create are:
All objects representing the fact above are final objects in a hierarchy. The hierarchy contains additional elements in order to make the final object meaningful. See the javadoc documentation of each one of the objects in order to learn more about the hierarchy.
The following example contains several lines of code but the creation of the fact is just one line.
// create a context for the instant "Begning of year 2008"
XBRLEntity ent = new XBRLEntity(dts,"http://www.xbrl.org/scheme","Sample Company",null);
XBRLPeriod p = new XBRLPeriod(dts,"2008-01-01");
XBRLContext ctx = new XBRLContext(instance,ent,p,null);
// Obtain the concept definition of concept "A" from the DTS
XBRLItem itemA = (XBRLItem)dts.getConcept(new QName(ns,"A"));
// create the Non Numeric (Text) fact item
XBRLFactNonNumeric fA = new XBRLFactNonNumeric(instance,ctx,itemA);
// fA is nil until a value is assigned
fA.setValue(new StringValue("sample text value"));
Create the footnote resource
Reporting Standard API does not contain a specific resource type for footnotes. Footnote resources can be created using the base XBRLResource object from the API.
The following example demonstrates how to do it. Note that the creation of the resource requires other parameters we have just created in this document. According to the parameters indicated in the example, the resource will be added to the parent footnote extended link container at the moment it is created. See the XBRLResource page for more information about the parameters.
// Create a Footnote resource and add it to the fl container
XBRLResource footnoteRes = new XBRLResource(fl,FootnoteLinkbase.lbResource,true);
// As footnotes can have simpleType content and complexType content (xhtml) the default is
// complexType content. So we now force the resource to have simple type content.
footnoteRes.setSimpleType();
// Footnote resource requires some values to be set
footnoteRes.setValue(new StringValue("Footnote content"));
footnoteRes.setLang("en");
Create the relationship linking the fact with the footnote
Finally, a relationship will join the fact in the report with the footnote resource. Creating a relationship requires providing some parameters we have already defined in this page. See the XBRL 2.1 specification for more information about the standard arcroles defined there.
// Create a relationship linking the fact with the footnote. XBRLArcroleType fact_footnote = dts.getStaticArcroleTypeByURI(FootnoteLinkbase.fact_footnote_arcrole_URI); new XBRLRelationship(fl,FootnoteLinkbase.standard_arc,fA,footnoteRes,fact_footnote,null,true);
