dimension processor development guide

B1WD-3109-01ENZ0(00)

Interstage XWand V12

Dimension processor Development Guide

Java Interface(XBRL 2.1)

ii

Preface

What This Guide Is About This is Interstage XWand Dimension processor User’s Guide. It contains the outline, functions, and usage

of Dimension processor.

Intended Readership This guide is designed for developers who develop applications using Dimension processor.

The reader is expected to understand XBRL 2.1 Specification and XBRL Dimensions Specification.

Related Manuals - XBRL Processor XBRL 2.1 Java Interface API Reference (referred to as "XBRL API Reference")

- Dimension Processor XBRL 2.1 Java Interface API Reference (referred to as "Dimension Processor

API Reference")

Export Restrictions This software product is designed primarily for use in the country to which the software is imported. The

software must not be re-exported from the country without authorization from the appropriate

government authorities in accordance with the Foreign Exchange and Foreign Trade Control Law of

the country. In no event will Fujitsu be liable for foreign government or third-party claims for

compensation or damages whatsoever arising from the use of the software resulting in any violation of

the laws and ordinances of the country or those of the relevant country. Fujitsu assumes no

responsibility for any problems or damages arising from such use of the software outside the country. If

Fujitsu suffers any damages as a result of a user’s violation of the above laws, Fujitsu reserves the

right to claim compensation from the user.

Trademarks - XBRL, is a trademark or service mark of XBRL International, Inc., registered in the United States and in

other countries.

- Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be

trademarks of their respective owners.

- Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States and

other countries.

- Other company names and product names are trademarks or registered trademarks of their respective

owners.

Remarks - The contents of the manual may be revised without prior notice.

- The contents of the manual shall not be reproduced in any way or form without the express written

permission of Fujitsu Limited.

- Fujitsu assumes no responsibility for infringement of any patent rights or other rights of third parties

arising from use of information in the manual.

iii

Date of Issue - December 2011: 1st edition

iv

Contents

CONTENTS ............................................................................................................................................... IV

CHAPTER 1 THE OUTLINE OF DIMENSION PROCESSOR ...................................................... 1

1.1 OUTLINE ........................................................................................................................................................ 2 1.2 FUNCTIONAL OUTLINE ................................................................................................................................... 3

CHAPTER 2 VALIDATION .................................................................................................................. 4

2.1 OUTLINE ........................................................................................................................................................ 5 2.2 VALIDATION FOR A TAXONOMY ....................................................................................................................... 6 2.3 VALIDATION FOR AN INSTANCE ....................................................................................................................... 7 2.4 REFERRING TO THE XBRL DIMENSIONS SPECIFICATION STANDARD SCHEMA ............................................. 8

CHAPTER 3 DATA MODEL ............................................................................................................... 9

3.1 OUTLINE ...................................................................................................................................................... 10 3.1.1 Creating a Dimension processor data model ........................................................................................ 10 3.1.2 Taxonomy .................................................................................................................................................. 11 3.1.3 Instance ..................................................................................................................................................... 12

3.2 THE DATA MODEL FOR TAXONOMY ............................................................................................................... 13 3.2.1 Creating a data model for taxonomy ...................................................................................................... 13 3.2.2 Traversing a data model for taxonomy ................................................................................................... 13

3.3 THE DATA MODEL FOR INSTANCE ................................................................................................................. 18 3.3.1 Creating a data model for instance ......................................................................................................... 18 3.3.2 Traversing a data model for instance ...................................................................................................... 19

CHAPTER 4 TUTORIAL ................................................................................................................... 22

4.1 OUTLINE ...................................................................................................................................................... 23 4.2 SAMPLE DATA .............................................................................................................................................. 24 4.3 SAMPLE PROGRAM ..................................................................................................................................... 25

4.3.1 Program flow ............................................................................................................................................. 25 4.3.2 Processing the Primary Item ................................................................................................................... 25 4.3.3 Processing the Hypercube ...................................................................................................................... 26 4.3.4 Processing the Dimension Item .............................................................................................................. 27 4.3.5 Processing the Domain Member ............................................................................................................ 27 4.3.6 Processing the total value check ............................................................................................................. 28

CHAPTER 5 CHANGES IN API SPECIFICATIONS ..................................................................... 32

5.1 CHANGES / DIFFERENCES IN API SPECIFICATIONS FROM V8...................................................................... 33

Chapter 1 The Outline of Dimension Processor

1

Chapter 1 The Outline of Dimension

Processor


2

1.1 Outline

The XBRL Dimensions Specification is designed by XBRL International, for the purpose of expressing multi-dimensional data in standardized formats within the rules of XBRL 2.1 Specification. This specification defines the procedure of how to express multi-dimensional data in taxonomy and instance documents. The Dimension processor provides functions that handle taxonomy or instance files according to the XBRL Dimensions Specification.


3

1.2 Functional outline

The following describes functions Dimension processor provides.

- Function to verify that given taxonomy or instance files are compliant with XBRL Dimensions Specification. By applying this processor to given taxonomy or instance objects created by XBRL Processor, you can examine whether or not the given files are compliant with XBRL Dimensions Specification.

- Function to get data from given taxonomy or instance files according to XBRL Dimensions

Specification. Dimension processor defines data models of the concepts in XBRL Dimensions Specification like Hypercube, Dimension Item and so on. Dimension processor provides API that enables taxonomy or instance document processing according to the Dimension specific data models.

Chapter 2 Validation

4


Follow the procedure given in this section to validate taxonomy or instance files in view of XBRL

Dimensions Specification.

XBRL Dimensions validation is carried out by using classes in com.fujitsu.xml.xbrl.dimension

package. This manual describes an outline. For more details, refer to "Dimension Processor

API Reference".


5

2.1 Outline

Use methods in the XBRLDimensionProcessor class to carry out XBRL Dimensions validation. To receive errors detected in XBRL Dimensions validation, create a class which implements XBRLDimensionErrorHandler interface and use setErrorHandler method in XBRLDimensionProcessor class to set a handler. The following shows an example: // Creates a Dimension processor object XBRLDimensionProcessor dimProc = new XBRLDimensionProcessor(); // creating a class object used for receiving validation errors // UserXBRLDimensionErrorHandler implements XBRLDimensionErrorHandler interface. UserXBRLDimensionErrorHandler handler = new UserXBRLDimensionErrorHandler(); dimProc.setErrorHandler(handler); After the above, the application validates taxonomy or instance with the methods defined in the XBRLDimensionProcessor class. When an XBRL Dimensions validation error is detected an appropriate method of the implementation class of XBRLDimensionErrorHandler is called according to the error type.


6

2.2 Validation for a taxonomy

Use validateTaxonomySet methods in the XBRLDimensionProcessor class to validate taxonomy. This method validates a TaxonomySet created by XBRL Processor. The following shows an example. Note : The following example omits the code to receive errors detected in XBRL Dimensions validation explained in the "2.1 The Outline of Dimension Processor". // loading a taxonomy document by using XBRL Processor XBRLProcessor xbrlProc = new XBRLProcessor(); TaxonomySet taxSet = xbrlProc.loadTaxonomySet(new StreamSource(taxonomyFile)); // Dimension processor XBRLDimensionProcessor dimProc = new XBRLDimensionProcessor(); // creating a class object used for receiving validation errors UserXBRLDimensionErrorHandler handler = new UserXBRLDimensionErrorHandler(); dimProc.setErrorHandler(handler); // validation process dimProc.validateTaxonomySet(taxSet);


7

2.3 Validation for an instance

Use validateInstance methods in the XBRLDimensionProcessor class to validate an instance. This method validates an Instance created by XBRL Processor. The following shows an example. Note : The following example omits the code to receive errors detected in XBRL Dimensions validation explained in the "2.1 The Outline of Dimension Processor". // loading an instance document by using XBRL Processor XBRLProcessor xbrlProc = new XBRLProcessor(); Instance instance = xbrlProc.loadInstance(new StreamSource(instanceFile)); // Dimension processor XBRLDimensionProcessor dimProc = new XBRLDimensionProcessor(); // validation process dimProc.validateInstance(instance); The above validation process also validates the taxonomy that the given instance refers to. As an another way, the validation process validates the taxonomy beforehand, and validateInstance method only validates instance. The following shows an example. // loading a taxonomy document by using XBRL Processor XBRLProcessor xbrlProc = new XBRLProcessor(); TaxonomySet taxSet = xbrlProc.loadTaxonomySet(new StreamSource(taxonomyFile)); // Dimension processor XBRLDimensionProcessor dimProc = new XBRLDimensionProcessor(); // validates taxonomy and creates data model DimensionalTaxonomy dimTax = dimProc.createDimensionalTaxonomy(taxSet); // loading an instance document by using XBRL Processor Instance instance = xbrlProc.loadInstance(taxSet, new StreamSource(instanceFile)); // validates instance only dimProc.validateInstance(dimTax, instance);


8

2.4 Referring to the XBRL Dimensions

Specification standard schema

All the dimensional taxonomies refer to the XML schema defined by XBRL Dimensions Specification (i.e. the XBRL Dimensions Specification standard schema). This means that they are all required to import the standard schema located at www.xbrl.org. XBRL processor contains these schemas distributed by XBRL International. In processing the dimensional taxonomies and instances, XBRL and Dimension processor use these schemas instead of accessing the www.xbrl.org site. But when you want to use these schemas from www.xbrl.org site, for example these schemas are updated and you want to use the latest, you can use the following way: Using XBRLEntityResolver:

XBRL Processor provides com.fujitsu.xml.xbrl.xwand.processor.XBRLEntityResolver interface. This gives you a mechanism of switching from an XML resource to another for loading. Using this interface, when you need the schemas for XBRL Dimensions specification you can let the processor load a local file downloaded beforehand, or access to the www.xbrl.org. For details of this interface, refer to "XBRL API Reference".

When you do HTTP access to www.xbrl.org via a proxy server, you need to let your Java Runtime Environment (JRE) know your proxy information. This can be achieved by adding the following options in your starting command of Java Virtual Machine (JVM): -Dhttp.proxyHost=<network address of your proxy server> -Dhttp.proxyPort=<port number of your proxy server> -Dhttp.nonProxyHosts=<host address for which you do not use your proxy server> Note that these options should be written in one line. White space character is treated as a separator. Given below are examples of these three options: -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=8080 -Dhttp.nonProxyHosts="*.mycompany.com|localhost" For details of your proxy server configuration, consult your network administrator.

Chapter 3 Data model

9


This chapter explains the data models like Hypercube, Dimension Item and so on described in

XBRL Dimensions specification. This chapter also explains how to use the API of the

Dimension processor to traverse taxonomy and instance.

The operation to traverse taxonomy and instance is carried out by using classes in

com.fujitsu.xml.xbrl.dimension, com.fujitsu.xml.xbrl.dimension.taxonomy and

com.fujitsu.xml.xbrl.dimension.instance package. This manual describes an outline. For more

details, refer to "Dimension Processor API Reference".


10

3.1 Outline

The XBRL Processor provides data models for taxonomy and instance. The Dimension processor provides data models based on XBRL Dimensions specification. For the information not defined in XBRL Dimensions specification, use the data models provided in XBRL processor. The following explains the relation between the data model in XBRL processor and the data model in Dimension processor.

3.1.1 Creating a Dimension processor data model

Use the methods createDimensionalTaxonomy or createDimensionalTaxonomy of XBRLDimensionProcessor class to create a new Dimension processor data model. In those calls, not only data model creation but also validation for XBRL Dimensions specification is processed. For the way to receive errors detected in XBRL Dimensions validation, refer to "Chapter 2 Validation".


11

3.1.2 Taxonomy

To get data defined in XBRL Dimensions specification like Hypercube, Dimension Item and so on, use the data model DimensionalTaxonomy in Dimension processor. To get data not defined in XBRL Dimensions specification like Presentation Linkbase, Label Linkbase and so on, use the data model TaxonomySet in XBRL processor. The following shows the relation between TaxonomySet and DimensionalTaxonomy.

<<interface>> TaxonomySet

<<interface>> XMLSchema

<<interface>> PresentationLink

1 *

1 *

<<interface>> CalculationLink 1 *

<<interface>> DefinitionLink 1 *

<<interface>> LabelLink 1 1

<<interface>> ReferenceLink 1 1

<<interface>>XMLSchema 1 *

<<interface>>ElementDecl 1 *

The data model in XBRL processor

<<interface>>DimensionalTaxonomy

The data model in Dimension processor

Create

<<interface>> HypercubeSet

<<interface>> DimensionItemSet

<<interface>> PrimaryItemList

<<interface>> RootDomainMemberSet 1 1

1 1

1 1

1 1


12

3.1.3 Instance

To get segment and scenario data in context based on XBRL Dimensions specification, use the data model DimensionalInstance in Dimension processor. To get the data like unit, the value of the item, use the data model Instance in XBRL processor. The following shows the relation between Instance and DimensionalInstance.

<<interface>>

Instance

<<interface>> Context

<<interface>>Period

<<interface>>Scenario

<<interface>> Unit

<<interface>> FootnoteLink

<<interface>>ContextEntity

<<interface>>Segment

<<interface>> InstanceElement

<<interface>>Item / Tuple

1 *

1 *

1 *

1 1

1 1

1 1

1 1

1 1

<<interface>>DimensionalInstance

<<interface>> DimensionalContextList 1 1

<<interface>> ContextSubElementList 1 1

Create


13

3.2 The data model for taxonomy

This section explains how to create the DimensionalTaxonomy object in the Dimension processor from the TaxonomySet object in the XBRL processor. This section also explains how to access a detailed data model like PrimaryItem, Hypercube from the DimensionalTaxonomy. The data models for the taxonomy are defined in com.fujitsu.xml.xbrl.dimension.taxonomy package.

3.2.1 Creating a data model for taxonomy

Use createDimensionalTaxonomy method in the XBRLDimensionProcessor class to create a DimensionalTaxonomy object. This method validates TaxonomySet according to XBRL Dimensions specification, and creates the data model of the Dimension processor based on the Definition Linkbase. The following shows an example // loading a taxonomy document by using XBRL Processor XBRLProcessor xbrlProc = new XBRLProcessor(); TaxonomySet taxSet = xbrlProc.loadTaxonomySet(new StreamSource(taxonomyFile)); // Dimension processor XBRLDimensionProcessor dimProc = new XBRLDimensionProcessor(); // creating a DimensionalTaxonomy object DimensionalTaxonomy dimTax = dimProc.createDimensionalTaxonomy(taxSet);

3.2.2 Traversing a data model for taxonomy

The following explains how to access a detailed data model from the DimensionalTaxonomy with a taxonomy example. This taxonomy example is installed in the <installation folder>¥XWand-dev¥java¥samples¥xbrl21¥dimension2¥data¥t-onedimension.xsd The taxonomy which has the following Definition Linkbase is used as an example.


14

The data model structure in the DimensionalTaxonomy object from the above taxonomy is the following.


15

The rectangle in the above figures shows an object of the data model, the bold-faced string drawn up the square shows the interface name of the data model. The interface which has element declaration contains it. The arrow between each object shows that the object of the source of the arrow has method near the arrow and the method returns the object of the target of the arrow. Using the data model by Dimension processor, when the data has a relation with another extended link role with targetRole attribute in Definition Linkbase, application can traverse the information without special consideration. For example in the above Definition Linkbase, "Dimension(Area)" and "Total(Area)" belong to a different extended link role and are related to with targetRole attribute. The application can get the DomainMember object which means "Total(Area)" from the ExplicitDimensionItem object which means "Dimension(Area)" via DimensionDomainRelationship object. The following explains the outline of the main interface and the method. For more details, refer to "Dimension Processor API Reference".

DimensionalTaxonomy

This interface shows the taxonomy based on XBRL Dimensions specification. The application can


16

access a detailed data model based on this interface. The application can get a list of the root Primary Item by getRootPrimaryItems method. The root Primary Item means that the item is related to a Hypercube by "all" or "notAll" relation, and has no ancestor with domain-member relation or all ancestor has no relation with a Hypercube by "all" or "notAll" relation. The application can also get a HypercubeSet object which includes Hypercube information by getHypercubeSet method, a DimensionItemSet object which includes Dimension Item information by getDimensionItemSet method, and a RootDomainMemberSet object which includes Domain Member information by getRootDomainMemberSet method.

PrimaryItem

This interface shows the Primary Item in XBRL Dimensions specification. The application can get the element declaration (ElementDecl) by getElementDecl method. The application can get a list of the child Primary Item by getChildPrimaryItems method. The application can get a list of the HasHypercubeRelationship object which is related to itself by getHasHypercubeRelationships method. The HasHypercubeRelationship object means "all/notAll" relation. The application can also get a list of the HasHypercubeRelationship object which is related to itself and its ancestor by getInheritedHasHypercubeRelationships method.

Hypercube

This interface shows the Hypercube in XBRL Dimensions specification. The application can get the element declaration by getElementDecl method. The application can get a list of the HypercubeDimensionRelationship object which is related to itself by getHasHypercubeRelationships method. The HypercubeDimensionRelationship means hypercube-dimension relation.

DimensionItem

This interface shows the Dimension Item in XBRL Dimensions specification. The application can get the element declaration by getElementDecl method. This is a super interface of ExplicitDimensionItem interface which means Explicit Dimension and TypedDimensionItem interface which means Typed Dimension. The application can know either by the returned value of getType method. The object of this interface can be cast to ExplicitDimensionItem if the returned value of getType method is DimensionItemType.EXPLICIT. Same as for TypedDimensionItem if the returned value of getType method is DimensionItemType.TYPED.

ExplicitDimensionItem

This interface shows the Explicit Dimension in XBRL Dimensions specification. The application can get a list of the DimensionDomainRelationship object which is related to itself by getDimensionDomainRelationships method. The DimensionDomainRelationship means dimension-domain relation. The application can get an element declaration of the default Domain Member by getDefaultDomainMemberDecl method.

TypedDimensionItem

This interface shows the typed Dimension in XBRL Dimensions specification.


17

The application can get an element declaration in the typedDomainRef attribute by getDomainElementDecl method. The application can also get the value itself in the typedDomainRef attribute by getTypedDomainRef method.

DomainMember

This interface shows the Domain Member in XBRL Dimensions specification. The application can get the element declaration by getElementDecl method. The application can get a list of the child Domain Member by getChildren method.

HasHypercubeRelationship

This interface shows the "all/notAll" relation in XBRL Dimensions specification. The application can get the PrimaryItem object which is related to itself by getPrimaryItem method. The application can also get the Hypercube object which is related to itself by getHypercube method. The application can know either by the returned value of getType method. The object means "all" relation if the returned value of getType method is HasHypercubeRelationshipType.ALL. Same as for "notAll" relation if the returned value of getType method is HasHypercubeRelationshipType.NOT_ALL. The application can also get the attribute value, closed attribute value by isClosed method, and contextElement attribute value by getContextElement method.

HypercubeDimensionRelationship

This interface shows the "hypercube-dimension" relation in XBRL Dimensions specification. The application can get the Hypercube object which is related to itself by getHypercube method. The application can also get the DimensionItem object which is related to itself by getDimensionItem method.

DimensionDomainRelationship

This interface shows the "dimension-domain" relation in XBRL Dimensions specification. The application can get the ExplicitDimensionItem object which is related to itself by getExplicitDimensionItem method. The application can get the DomainMember object which is related to itself by getDomainMember method. The application can also get the attribute value, usable attribute value by isUsable method.


18

3.3 The data model for instance

This section explains how to create the DimensionalInstance object in the Dimension processor from the Instance object in the XBRL processor. This section also explains how to access a detailed data model like DimensionalContext, ExplicitMemberElement from the DimensionalInstance. The data models for the instance are defined in com.fujitsu.xml.xbrl.dimension.instance package.

3.3.1 Creating a data model for instance

Use createDimensionalInstance method in the XBRLDimensionProcessor class to create a DimensionalInstance object. There are two kinds of this method. One takes only Instance in the argument, another takes DimensionalTaxonomy and Instance. The following shows the description and the sample code.

createDimensionalInstance(Instance)

This method validates the taxonomy and the instance for specified Instance object according to XBRL Dimensions specification, and creates the data model of the Dimension processor. The following shows an example. // loading an instance and its taxonomy document by using XBRL Processor XBRLProcessor xbrlProc = new XBRLProcessor(); Instance instance = xbrlProc.loadInstance(new StreamSource(instanceFile)); // Dimension processor XBRLDimensionProcessor dimProc = new XBRLDimensionProcessor(); // creating a DimensionalInstance object DimensionalInstance dimInstance = dimProc.createDimensionalInstance(instance);

createDimensionalInstance(DimensionalTaxonomy, Instance)

This method takes the DimensionalTaxonomy object by the XBRLDimensionProcessor and Instance object by the XBRLProcessor in the argument, validates the instance according to XBRL Dimensions specification, and creates the data model of the Dimension processor. This method does neither validate the taxonomy nor create the data model of taxonomy. When the application handles many instances based on the same taxonomy, the application should use this method with the DimensionalTaxonomy object created beforehand. The following shows an example. // loading a taxonomy document by using XBRL Processor XBRLProcessor xbrlProc = new XBRLProcessor(); TaxonomySet taxSet = xbrlProc.loadTaxonomySet(new StreamSource(taxonomyFile)); // Dimension processor XBRLDimensionProcessor dimProc = new XBRLDimensionProcessor(); // creating a DimensionalTaxonomy object DimensionalTaxonomy dimTax = dimProc.createDimensionalTaxonomy(taxSet); // loading an instance document by using XBRL Processor Instance instance = xbrlProc.loadInstance(taxSet, new StreamSource(instanceFile)); // creating a DimensionalInstance object DimensionalInstance dimInstance = dimProc.createDimensionalInstance(dimTax, instance);


19

3.3.2 Traversing a data model for instance

The following explains how to access a detailed data model from the DimensionalInstance with an instance example.

The data model structure in the DimensionalInstance object from the above instance is the following.


20

The rectangle in the above figures shows an object of the data model, the bold-faced string drawn up the square shows the interface name of the data model. The arrow between each object shows that the object of the source of the arrow has method near the arrow and the method returns the object of the target of the arrow. The following explains the outline of the main interface and the method. For more details, refer to "Dimension Processor API Reference".

DimensionalInstance

This interface shows the instance based on XBRL Dimensions specification. The application can access a detailed data model based on this interface. The application can get a DimensionalTaxonomy object which corresponds to the taxonomy referred from this instance. The application can get a list of DimensionalContext object by getDimensionalContexts method. The application can also get a DimensionalContext object by getDimensionalContext method with a Context object.

DimensionalContext

This interface provides the methods to access xbrldi:typedMember element and xbrldi:explicitMember element which are included in segment or scenario element in context. This interface contains a Context object and returns it by getContext method. The application can get a list of ContextSubElement object by getSegmentElements method which returns element information in segment and getScenarioElements method which returns element information in scenario. The application can check that this context contains the dimension member by calling containsDomainMemberDecl method with the element declaration of Dimension Item and Domain Member.


21

ContextSubElement

This interface shows an element in segment or scenario of context. The application can get a org.w3c.dom.Element object by getElement method. The application can get the kind of the element by getType method. If the returned value of getType method is ContextSubElementType.EXPLICIT_MEMBER, it means that the element is xbrldi:explicitMember and the object can be cast to ExplicitMemberElement. If the returned value of getType method is ContextSubElementType.TYPED_MEMBER, same as for xbrldi:typedMember and the object can be cast to TypedMemberElement. If the returned value of getType method is ContextSubElementType.OTHER, it means that the element is other element.

ExplicitMemberElement

This interface shows a xbrldi:explicitMember in segment or scenario of context. The application can get the element declaration of Dimension Item which is specified in dimension attribute of xbrldi:explicitMember by getDimensionItemDecl method. The application can also get the element declaration of Domain Member which is specified in xbrldi:explicitMember by getDomainMemberDecl method.

TypedMemberElement

This interface shows a xbrldi:typedMember in segment or scenario of context. The application can get the element declaration of Dimension Item which is specified in dimension attribute of xbrldi:typedMember by getDimensionItemDecl method. The application can also get the child element of xbrldi:typedMember by getTypedDomainElement method.

Chapter 4 Tutorial

22

Chapter 4 Tutorial

This chapter explains the use of the main API provided in Dimension processor through the

procedure for making the sample program. The sample program checks the value of the

instance.

The sample program and the data in this chapter are installed in

the <installation folder>¥XWand-dev¥java¥samples¥xbrl21¥dimension2 folder.

Chapter 4 Tutorial

23

4.1 Outline

The outline of the sample program is the following. The application takes an instance based on XBRL Dimension specification as the input. For each dimension defined in the taxonomy, the application checks that the value of the parent

is equal to the total of the value of the children. The application returns a list of the parent member which violates the above check.

Chapter 4 Tutorial

24

4.2 Sample data

The outline of the sample program is the following. This instance refers the taxonomy in "3.2.2".

period : 2006/1/1 - 2006/12/31 identifier : Fujitsu segment : none

Total(Area)

North America Europe Asia Sales 2,000 3,000 4,000 5,000

Cost of Sales 1,600 2,400 3,200 7,200 Gross Profit 400 600 800 1,800

The sample application checks the following calculation for the above instance.

Sales[Total(Area)] = Sales[North America] + Sales[Europe] + Sales[Asia] Cost of Sales[Total(Area)] = Cost of Sales[North America] + Cost of Sales[Europe] + Cost of Sales[Asia] Gross Profit[Total(Area)] = Gross Profit[North America] + Gross Profit[Europe] + Gross Profit[Asia]

Actually, the value violates like the following. Sales[Total(Area)] = 5000 Sales[North America] + Sales[Europe] + Sales[Asia] = 2000 + 3000 + 4000 = 9000 In this case, the sample application returns the value 5000 of Sales[Total(Area)].

Chapter 4 Tutorial

25

4.3 Sample program

This section explains the use of the API provided in Dimension processor with the sample source code.

4.3.1 Program flow

The flow of the program is the following. 1. loads the instance by XBRL processor 2. creates a DimensionalInstance object by Dimension processor 3. takes a DimensionalTaxonomy object from the DimensionalInstance object and takes Primary

Item 4. gets a Hypercube object related to the Primary Item 5. gets a DimensionItem object related to the Hypercube 6. gets a DomainMember object related to the Dimension Item 7. gets an item value of the Primary Item related to the context which refers the Domain Member in

6) 8. gets an item value for all children of the Domain Member in 6) in the same way as 7) 9. checks the value by 7) and the total by 8) and adds them if the both are not equal. DimensionalInstanceCalculationCheckerMain.java contains the step 1 and 2. DimensionalInstanceCalcurationChecker.java contains the step 3 and the later. The previous chapter already explains the step 1 and 2. The following explains the step 3 and the later.

4.3.2 Processing the Primary Item

The sample program can get a list of root Primary Item by getRootPrimaryItems method of DimensionalTaxonomy object. In the case of the sample instance shown in 4.2, the sample program gets one PrimaryItem which refers the element declaration of the Gross Profit. The following code shows : - gets a list of root Primary Item - for each Primary Item, calls calculationCheckForPrimaryItem to check // List to store the error Item List errorItemList = new ArrayList(); // gets a DimensionalTaxonomy object DimensionalTaxonomy dimTaxonomy = dimInstance.getDimensionalTaxonomy(); // gets a list of root Primary Item PrimaryItemList rootPrimaryItems = dimTaxonomy.getRootPrimaryItems(); for (int i = 0, n = rootPrimaryItems.size(); i < n; i++){ PrimaryItem primaryItem = rootPrimaryItems.get(i); // check for Primary Item calculationCheckForPrimaryItem(primaryItem, errorItemList); }

Chapter 4 Tutorial

26

In the start of the calculationCheckForPrimaryItem method, the sample program gets the child PrimaryItem objects of the PrimaryItem specified in the argument by getChildPrimaryItems. The sample program calls calculationCheckForPrimaryItem recursively for them. In the case of the sample instance shown in 4.2, the method is called with the PrimaryItem object which refers the element declaration of Gross Profit at first. The getChildPrimaryItmes method returns two Primary Item, Sales and Cost of Sales. Therefore the check is also applied for the 2 Primary Item. The sample program gets the element declaration of PrimaryItem by getElementDecl method and ignores the element declaration if its value of the abstract attribute equals true or it is non numeric. The following is the source of the above. private void calculationCheckForPrimaryItem(PrimaryItem primaryItem, List errorItemList) { // calls recursively for the child PrimaryItem PrimaryItemList childPrimaryItemList = primaryItem.getChildPrimaryItems(); for (int i = 0, n = childPrimaryItemList.size(); i < n ; i++){ PrimaryItem childPrimaryItem = childPrimaryItemList.get(i); calculationCheckForPrimaryItem(childPrimaryItem, errorItemList); } // gets the element declaration ElementDecl elementDecl = primaryItem.getElementDecl(); if (elementDecl.isAbstract() || !elementDecl.isNumericItemDecl()){ // ignores return; } ... (processing Hypercube) }

4.3.3 Processing the Hypercube

The sample program gets a HasHypercubeRelationship object which shows all/notAll relation between PrimaryItem and Hypercube in order to get a Hypercube object related to Primary Item. The application gets a list of all/notAll relation of PrimaryItem by getHasHypercubeRelationships method of the PrimaryItem. The application can also gets a list of all/notAll relation of PrimaryItem and its ancestor by getInheritedHasHypercubeRelationships. The sample program uses the latter method. This sample program does not need to process Hypercube which shows notAll relation. Therefore this processes only if the returned value of getType method of HasHypercubeRelationship equals HasHypercubeRelationshipType.ALL. The application can get a Hypercube object by getHypercube method of HasHypercubeRelationship. In the case of the sample instance shown in 4.2, the application gets a Hypercube object which refers "Hypercube(Area)". The following source code corresponds to "(processing Hypercube)" of calculationCheckForPrimaryItem method in the previous section. // gets "all/notAll" relation HasHypercubeRelationshipList hhRelList = primaryItem.getInheritedHasHypercubeRelationships(); for (int i = 0, n = hhRelList.size(); i < n; i++){ HasHypercubeRelationship hhRel = hhRelList.get(i); if (hhRel.getType() != HasHypercubeRelationshipType.ALL){ // ignore notAll relation continue;

Chapter 4 Tutorial

27

} // gets Hypercube Hypercube hypercube = hhRel.getHypercube(); ... (processing Dimension Item) } ...

4.3.4 Processing the Dimension Item

The sample program gets a HypercubeDimensionRelationship object which shows hypercube-dimension relation between Hypercube and Dimension Item to get a DimensionItem object related to Hypercube. The sample program gets a list of hypercube-dimension relation of Hypercube by getHypercubeDimensionRelationships method of the Hypercube. The application can also gets a DimensionItem object by getDimensionItem method. There are 2 kind in DimensionItem, ExplicitDimensionItem and TypedDimensionItem. The sample program handles the ExplicitDimensionItem only. Therefore the sample program process if the returned value of getType equals DimensionItemType.EXPLICIT. In the case of the sample instance shown in 4.2, the application gets a ExplicitDimensionItem object which refers "Dimension(Area)". The following source code corresponds to "(processing Dimension Item)" in the previous section. // gets "hypercube-dimension" relation HypercubeDimensionRelationshipList hdRelList = hypercube.getHypercubeDimensionRelationships(); for (int j = 0, nn = hdRelList.size(); j < nn ; j++){ HypercubeDimensionRelationship hdRel = hdRelList.get(j); // gets a Dimension Item object DimensionItem dimItem = hdRel.getDimensionItem(); if (dimItem.getType() != DimensionItemType.EXPLICIT){ // ignore if this is not Explicit Dimension continue; } ExplicitDimensionItem exDimItem = (ExplicitDimensionItem)dimItem; ... (processing Domain Member) }

4.3.5 Processing the Domain Member

The sample program gets a DimensionDomainRelationship object which shows dimension-domain relation between Dimension Item and Domain Member to get a Domain Member related to Dimension Item. The sample program gets a list of dimension-domain relation of Dimension Item by getDimensionDomainRelationships method of the ExplicitDimensionItem. The application can get a DomainMember object by getDomainMember method of DimensionDomainRelationship. The application can also get the value of xbrldt:usable attribute specified in the dimension-domain relation. In the case of the sample instance shown in 4.2, the application gets a DomainMember object which refers "Total(Area)".

Chapter 4 Tutorial

28

The following source code corresponds to "(processing Domain Member)" in the previous section. The sample program calls calculationCheckForDimension method for each DomainMember to check. // gets "dimension-domain" relation DimensionDomainRelationshipList ddRels = exDimItem.getDimensionDomainRelationships(); for (int k = 0, nnn = ddRels.size(); k < nnn ; k++){ DimensionDomainRelationship ddRel = ddRels.get(k); calculationCheckForDimension(primaryItem, exDimItem, ddRel.getDomainMember(), ddRel.isUsable(), errorItemList); } The calculationCheckForDimension method checks the value for Primary Item, Dimension Item, and Domain Member. This method calls the method itself recursively for the children of Domain Member. This method also gets the value of xbrldt:usable attribute for DomainMember by isUsable method. In the case of the sample instance shown in 4.2, the application calls a getChildren method for DomainMember object which refers "Total(Area)", and gets DomainMember objects which refers "North America", "Europe" and "Asia". Afterwards, the sample program processes only when usable is true and the DomainMember object has children. If usable is false, the check processing is unnecessary because the corresponding value is not in the instance. private void calculationCheckForDimension(PrimaryItem primaryItem, ExplicitDimensionItem exDimItem, DomainMember domainMember, boolean usable, List errorItemList) { // checks for the ancestor of the specified Domain Member DomainMemberList children = domainMember.getChildren(); for (int i = 0, n = children.size(); i < n; i++){ DomainMember childDomainMember = children.get(i); calculationCheckForDimension(primaryItem, exDimItem, childDomainMember, childDomainMember.isUsable(), errorItemList); } // processes only when usable is true and // the DomainMember object has children. // If usable is false, the check processing is unnecessary // because the corresponding value is not in the instance. if (usable && domainMember.getChildren().size() > 0){ ... (processing the total value check) } }

4.3.6 Processing the total value check

As next step, the sample program gets a value whose item is the Primary Item specified at calculationCheckForDimension method and whose context refers the Domain Member specified at calculationCheckForDimension method. This is the value of the parent in processing the total value check. The following is the source of the above. The following considers the value right under the root element to explain in simple case. At first, the sample program checks that the value in instance is from the specified Primary Item. Next, the sample program gets the context of the value and checks that the context refers the specified Dimension and Domain Member. To process this, the sample program gets a DimensionalContext object by getDimensionalContext method of DimensionalInstance and calls pointsDomainMember method with it in the argument. If the returned value is true, the sample program adds it into the result

Chapter 4 Tutorial

29

list. private List getItems(ElementDecl elementDecl, ExplicitDimensionItem exDimItem, DomainMember domainMember) { List itemList = new ArrayList(); Instance instance = dimInstance.getInstance(); InstanceElementList elements = instance.getChildren(); for (int i = 0, n = elements.size(); i < n; i++){ InstanceElement element = elements.get(i); if (element.getElementType() != Item.ELEMENT_TYPE_NUMERIC_ITEM){ continue; } NumericItem numItem = (NumericItem)element; if (numItem.getElementDecl() != elementDecl){ continue; } Context ctx = numItem.getContext(); DimensionalContext dc = dimInstance.getDimensionalContext(ctx); // checks if the context refers refers the specified Dimension and Domain Member if (pointsDomainMember(dc, exDimItem, domainMember)){ itemList.add(numItem); } } return itemList; } The pointsDomainMember method checks that the specified member of the dimension is the default member of the dimension at first. The application can gets an element declaration of the default member of the dimension by getDefaultDomainMemberDecl method of the ExplicitDimensionItem. The pointsDomainMember method compares the element declaration of the specified member and default member. When the specified member is not a default member, the application can understand that the context refers the specified Dimension and Domain Member if the context contains the xbrldi:explicitMember which shows the specified Dimension and Domain Member in the segment or scenario element. The application can check this by containsDomainMemberDecl method of DimensionalContext with the element declaration of the specified dimension and member in the argument. When the specified member is a default member, the application can understand that the context refers the specified Dimension and Domain Member if the context does not contain the xbrldi:explicitMember which shows the specified Dimension and Domain Member in the segment or scenario element. The application can check this by containsDimensionItemDecl method of DimensionalContext with the element declaration of the specified dimension in the argument. The following is the code of pointsDomainMember method. private boolean pointsDomainMember(DimensionalContext dc, ExplicitDimensionItem exDimItem, DomainMember domainMember){ if (exDimItem.getDefaultDomainMemberDecl() != domainMember.getElementDecl()){ return (dc.containsDomainMemberDecl(exDimItem.getElementDecl(), domainMember.getElementDecl())); } else { // When the specified member is a default member, // checks that the context does not contain the xbrldi:explicitMember // which shows the specified Dimension Item return (!dc.containsDimensionItemDecl(exDimItem.getElementDecl())); } }

Chapter 4 Tutorial

30

Next, the sample program gets a list of the item by getItems method and calculates the total value for its children. If the value of the parent and the total value is not equal, this sample program adds it into the result list. The code to get the value of the children is written in getItemsForCalculation method. // gets a list of the Item to process total value check List targetItemList = getItems(primaryItem.getElementDecl(), exDimItem, domainMember); for (int i = 0, n = targetItemList.size(); i < n; i++){ NumericItem numItem = (NumericItem)targetItemList.get(i); BigDecimal total = null; // calculates the total for (int j = 0, nn = children.size(); j < nn; j++){ DomainMember childDomainMember = children.get(j); List childItemList = getItemsForCalculation(primaryItem.getElementDecl(), exDimItem, childDomainMember, numItem.getContext(), numItem.getUnit()); if (childItemList.size() == 1){ // calculates only if the count of the child Item is one. // If the count is more than one, they are duplicated. NumericItem childItem = (NumericItem)childItemList.get(0); BigDecimal value = childItem.getRoundedValue(); if (total == null){ total = value; } else { total = total.add(value); } } } if (total != null){ if (total.compareTo(numItem.getRoundedValue()) != 0){ // adds the item into the error list errorItemList.add(numItem); } } } There are the following notes when the application get a value from the child item. The following explains based on the instance example. To check the parent value 9,000 at "Total(Area)" in 2005, the application needs to get the child value from "North America", "Europe" and "Asia" in 2005. If the application gets the value list only with the condition "North America", "Europe" and "Asia", the list contains the value in 2006 and the application may get the wrong result. The application needs to consider not only the period but also identifier, unit, and other dimension.

item: Sales identifier : Fujitsu segment : none

Total(Area)

North America Europe Asia 2005/1/1 – 2005/12/31 2,000 3,000 4,000 9,000 2006/1/1 – 2006/12/31 4,000 6,000 8,000 18,000

Therefore, the application needs to get the child value with the condition like the following. The context of the child value is equal to the context of the parent value except for the

xbrldi:explicitMember which refers the dimension in calculation process.

Chapter 4 Tutorial

31

The unit of the child value is equal to the unit of the parent value. The application can check if two contexts are equal except for the specified dimension by equalsExceptOneDimension method of DimensionalContext. The following is the code of getItemsForCalculation method. private List getItemsForCalculation(ElementDecl elementDecl, ExplicitDimensionItem exDimItem, DomainMember domainMember, Context context, Unit unit) { DimensionalContext dimContext = dimInstance.getDimensionalContext(context); List itemList = new ArrayList(); Instance instance = dimInstance.getInstance(); InstanceElementList elements = instance.getChildren(); for (int i = 0, n = elements.size(); i < n; i++){ InstanceElement element = elements.get(i); if (element.getElementType() != Item.ELEMENT_TYPE_NUMERIC_ITEM){ continue; } NumericItem numItem = (NumericItem)element; if (numItem.getElementDecl() != elementDecl){ continue; } if (!unit.s_equals(numItem.getUnit())){ // checks if the unit is equal. continue; } Context ctx = numItem.getContext(); DimensionalContext dc = dimInstance.getDimensionalContext(ctx); if (!dimContext.equalsExceptOneDimension(dc, exDimItem)){ // checks if the context is equal except for the specified dimension continue; } if (pointsDomainMember(dc, exDimItem, domainMember)){ itemList.add(numItem); } } return itemList; }

Chapter 5 Changes in API Specifications

32



33

5.1 Changes / Differences in API specifications

from V8

The following changes in API specifications have been made.

Class Method / Field

Change Program Compatibility Data Compatibility

Note

com.fujitsu.xml.xbrl.dimension.XBRLDimensionException INSTANCE_ERROR_NAMESPACE_URI

Previous Version: http://xbrl.org/2006/xbrldi/errors Current Version: http://xbrl.org/2005/xbrldi/errors

If your program uses this field, you will need to re-compile the program.

No influence.

This is a bug fix.

XBRLDTE_TARGET_ROLE_NOT_RESOLVED_ERROR

Previous Version: When a Definition Linkbase has a prohibiting arc or a prohibited arc which has a targetRole attribute and the Definition Linkbase does not have a roleRef definition based on the targetRole, the processor does not report this error. Current Version: The processor reports an error which has this error code.

Exception will be thrown when the processor loads the taxonomy mentioned in the “Change” column. Set the com.fujitsu.xml.xbrl.dimension.XBRLDimensionException.TargetRoleNotResolvedError=lax in system property not to receive this error in this case.

No influence.

This is an improvement based on the spec WG discussion.

dimension processor development guide

Documents