Formula Processor Development Guide - Fujitsu · What This Guide Is About This is Formula Processor...

B1WD-3108-01ENZ0(00)

Interstage XWand V12

Formula Processor Development Guide

Java Interface (XBRL 2.1)

ii

Preface

What This Guide Is About This is Formula Processor User’s Guide. It contains the outline, functions, and usage of Formula Processor.

Intended Readership This guide is designed for developers of applications that use the Formula Processor. The reader is expected to understand XBRL 2.1 specifications and Formula 1.0 specifications.

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

Reference") - Formula Processor XBRL 2.1 Java Interface API Reference (hereafter referred to as "Formula

Processor API Reference")

About this Software A feature of multi-instance processing contained in this software based on Candidate Recommendation specification, therefore the specification for it may change when the final Recommendation specification is published. For this reason, the following notes apply in relation to the use of this software API: - If the Formula processor corresponding to the Recommendation specification is provided in the

future, the specification for this software API may change according to the changed specification content.

- If the Formula processor corresponding to the Recommendation is provided, the Formula processor implementation provided in this software will be replaced. That is to say, in future, processor implementations based on the Proposed Recommendation and Candidate Recommendation specification will not be provided.

- The user may need to correct data containing multi-instance processing and applications that use it because of changes made to its specification content.

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.

iii

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.

Date of Issue - December 2011: 1st edition

iv

Contents

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

CHAPTER 1 THE OUTLINE OF FORMULA PROCESSOR ............................ 1

1.1 PURPOSE ............................................................................ 2 1.2 OUTLINE OF FUNCTIONS ................................................................ 3

CHAPTER 2 METHOD OF USE ................................................... 4

2.1 CREATING A PROCESSOR ................................................................ 5 2.2 PROCESSING AN XBRL INSTANCE ........................................................ 7

2.2.1 Evaluation processing ................................................................. 7 2.2.2 Validation processing ................................................................. 8 2.2.3 Selecting which calculation expressions and validation expressions are to be executed ......... 9

2.3 IMPLEMENTING CUSTOM FUNCTIONS ...................................................... 10 2.3.1 Implementation of custom function logic ................................................ 10 2.3.2 Implementation of resolver ............................................................ 12

2.4 PROCESSING MULTIPLE INSTANCES ....................................................... 13 2.4.1 Setup of non-standard instances ....................................................... 13 2.4.2 Handling of non-standard output instances .............................................. 15

2.5 OBTAINING VALIDATION MESSAGES ....................................................... 17 2.6 NOTES ............................................................................. 19

CHAPTER 3 SPECIFICATIONS BASIS ............................................ 23

3.1 OVERVIEW .......................................................................... 24 3.2 RESTRICTIONS ....................................................................... 26

Chapter 1 The Outline of Formula Processor

1



2

1.1 Purpose The Formula 1.0 specifications define the syntax required for coding business rules to be used to evaluate and validate XBRL instances. For evaluations, for example, the business rules can be used to calculate the indices required for financial analysis, and for validations, the business rules can be used to validate the item values in submitted financial statements. Formula Processor executes evaluations and validations of entered XBRL instances in accordance with the various Formula definitions, and provides functions that output those results.


3

1.2 Outline of Functions This processor provides the following functions: Processor creation

The factory analyses the entered Formula definitions and creates a processor that processes XBRL instances on the basis of that analysis information. The user utilizes the API provided by the factory to fetch the processor.

XBRL instance evaluation The processor evaluates entered XBRL instances in accordance with the calculation expressions coded in the Formula definitions. The user utilizes the API provided by the processor to fetch the XBRL instance evaluation results.

XBRL instance validation The processor validates entered XBRL instances in accordance with the validation expressions coded in the Formula definitions. The user utilizes the API provided by the processor to fetch the XBRL instance validation results.

Custom function implementation

The processor provides a way of implementing custom functions defined in formula definitions. The user utilizes the API provided by the processor to apply custom functions implemented by an application to formula processing.

Multiple instance processing The processor provides a way of assigning multiple input instances and obtaining multiple evaluation results (output instances). The user can execute the evaluation of the Formula definitions containing multiple input/output instance processes using the API provided by the processor.

Obtaining validation messages

The processor provides a way of creating validation messages defined in the Formula definition. The user can obtain the validation messages in a plain text format that is easy to read, or in XML format, using the API provided by the processor.

Chapter 2 Method of Use

4


Follow the procedures described in this chapter to use Formula Processor (the classes of com.fujitsu.xml.xbrl.formula package). This manual provides an overview. Refer to "Formula Processor API Reference" for details.


5

2.1 Creating a processor First, create a Formula Processor (FormulaLinkProcessor class). Use the processor factory, that is the FormulaLinkProcessorFactory class, to create the Formula Processor, and use the createFormulaLinkProcessor() method to create the processor. In order to receive errors issued during Formula Processor creation, create a class in which the FormulaLinkErrorHandler interface is implemented, and use the setErrorHandler method of the FormulaLinkProcessorFactory class to set the error handler. An example of loading the taxonomy of input instance and the Formula definitions that are to be applied and creating a processor is shown below (when the taxonomy of input instance does not refer the Formula definitions): // To create the Formula processor factory FormulaLinkProcessorFactory formulaProcFactory = FormulaLinkProcessorFactory.newInstance(); // To create a class object for accepting errors that occur during processor creation // For the UserFormulaLinkErrorHandler, set the class that has implemented FormulaLinkErrorHandler UserFormulaLinkErrorHandler handler = new UserFormulaLinkErrorHandler(); formulaProcFactory.setErrorHandler(handler); // To create an XBRL processor XBRLProcessor xbrlProc = new XBRLProcessor(); // To create a class object for receiving error information from the XBRL processor // For the UserXBRLErrorHandler, set the class that has implemented XBRLErrorHandler UserXBRLErrorHandler xbrlErrorHandler = new UserXBRLErrorHandler(); xbrlProc.setErrorHandler(xbrlErrorHandler); // To set up the XBRL processor FormulaLinkProcessorFactory.setUpXBRLProcessor(xbrlProc); // Schema input source Source[] xsSources = new Source[] {new StreamSource("localfiles/smp_schema.xsd")}; // Linkbase (including Formula definitions) input source Source[] lbSources = new Source[] {new StreamSource("localfiles/smp_linkbase.xml")}; // To create Formula processor FormulaLinkProcessor formulaProc =

formulaProcFactory.createFormulaLinkbaseProcessor(xsSources,lbSources); // Check errors while creating the Formula processor if(handler.isErrorDetected()){

System.err.println("Errors were detected while creating the Formula processor."); return;

} The result of the above is that a FormulaLinkProcessor class object is created. If an error occurs during creation of the processor, depending on the error type, the method of the class that implemented FormulaLinkErrorHandler is called. When the input XBRL taxonomy does not conform to the specification XBRL 2.1 and the specification Formula, the processing of the created processor is not guaranteed. Therefore, after removing the detected errors, create a processor again. If you want to reuse an already loaded Formula, and if large numbers of XBRL instances are processed in multiple threads (one processor is assigned to one thread, and the same Formula definition is applied in each processor), it is efficient to use the method below to create a processor.


6

// To load a taxonomy containing a Formula definition TaxonomySet taxSet = xbrlProc.loadTaxonomySet(new StreamSource("localfiles/smp_formula.xsd")); // Check errors while loading the Taxonomy if(xbrlErrorHandler.isErrorDetected()){

System.err.println("Errors were detected while loading the Taxonomy."); return;

} // To create the Formula processor FormulaLinkProcessor formulaProc = formulaProcFactory.createFormulaLinkbaseProcessor(taxSet);.


7

2.2 Processing an XBRL Instance The processing of XBRL instances in accordance with Formula definitions can be broadly divided into two types of processing (evaluation processing and validation processing) in accordance with the business rules (calculation expressions and validation expressions) coded in the Formula definitions. Also, filters can be used if you want more precise control of the business rules applied to XBRL instances.

2.2.1 Evaluation processing

Use the evaluate() method of the FormulaLinkProcessor class to evaluate an XBRL instance. The input required for this method is specification of the input instance targeted for evaluation. In addition, when the input XBRL instance does not conform to the specification XBRL 2.1, the evaluation processing of the processor is not guaranteed. Therefore, a valid XBRL instance must be input.Note that the instance to be specified must be loaded by the XBRLProcessor that has been configured using FormulaLinkProcessorFactory.setUpXBRLProcessor(XBRLProcessor). In order to receive errors issued from Formula Processor during evaluation, create a class in which the FormulaLinkErrorHandler interface is implemented, and use the setErrorHandler method of the FormulaLinkProcessor class to set the error handler. To receive the evaluation results, create a class in which the FormulaLinkResultHandler interface is implemented, and use the setResultHandler method to set the result handler. An example is shown below: // To create a class object for receiving error information from the processor // For the UserFormulaLinkErrorHandler, set the class that has implemented FormulaLinkErrorHandler. UserFormulaLinkErrorHandler errorHandler = new UserFormulaLinkErrorHandler(); formulaProc.setErrorHandler(errorHandler); // To create a class object for receiving evaluation results information from the processor // For the UserFormulaLinkResultHandler, set the class that has implemented FormulaLinkResultHandler. UserFormulaLinkResultHandler resutlHandler = new UserFormulaLinkResultHandler(); formulaProc.setResultHandler(resultHandler); // To create the XBRL processor XBRLProcessor xbrlProc = new XBRLProcessor(); // To create a class object for receiving error information from the XBRL processor // For the UserXBRLErrorHandler, set the class that has implemented XBRLErrorHandler UserXBRLErrorHandler xbrlErrorHandler = new UserXBRLErrorHandler(); xbrlProc.setErrorHandler(xbrlErrorHandler); // To set up the XBRL processor FormulaLinkProcessorFactory.setUpXBRLProcessor(xbrlProc); // To load the instance to be evaluated Instance inputInstance = xbrlProc.loadInstance(new StreamSource("localfiles/smp_evaluate.xml")); // Check errors while loading the XBRL instance if(xbrlErrorHandler.isErrorDetected()){

System.err.println("Errors were detected while loading the XBRL instance.") return;

} // To execute the evaluation Instance outputInstance = formulaProc.evaluate(inputInstance, null, null, null); The result of the above is that the XBRL instance is evaluated in accordance with the Formula definitions, and the resulting XBRL instance is output. If an error occurs during evaluation, depending


8

on the error type, the method of the class that implemented FormulaLinkErrorHandler is called. The evaluation results are posted to the class that implemented FormulaLinkResultHandler. If the evaluate() method does not use the filter described in Section 2.2.3, all calculation expressions and validation expressions coded in the Formula definitions are executed. If you want to perform only validation processing, use the validate() method described in Section 2.2.2.

2.2.2 Validation processing

Use the validate() method of the FormulaLinkProcessor class to validate XBRL instances. The input required for this method is specification of the input instance targeted for validation. In addition, when the input XBRL instance does not conform to the specification XBRL 2.1, the validation processing of the processor is not guaranteed. Therefore, a valid XBRL instance must be input. Note that the instance to be specified must be loaded by the XBRLProcessor that has been configured using FormulaLinkProcessorFactory.setUpXBRLProcessor(XBRLProcessor). In order to receive errors issued from Formula Processor during validation, create a class in which the FormulaLinkErrorHandler interface is implemented, and use the setErrorHandler method of the FormulaLinkProcessor class to set the error handler. To receive the validation results, create a class in which the FormulaLinkResultHandler interface is implemented, and use the setResultHandler method to set the result handler. An example is shown below: // To create a class object for receiving error information from the processor // For the UserFormulaLinkErrorHandler, set the class that has implemented FormulaLinkErrorHandler. UserFormulaLinkErrorHandler errorHandler = new UserFormulaLinkErrorHandler(); formulaProc.setErrorHandler(errorHandler); // To create a class object for receiving validation results information from the processor // For the UserFormulaLinkResultHandler, set the class that has implemented FormulaLinkResultHandler. UserFormulaLinkResultHandler resutlHandler = new UserFormulaLinkResultHandler(); formulaProc.setResultHandler(resultHandler); // To create the XBRL processor XBRLProcessor xbrlProc = new XBRLProcessor(); // To create a class object for receiving error information from the XBRL processor // For the UserXBRLErrorHandler, set the class that has implemented XBRLErrorHandler UserXBRLErrorHandler xbrlErrorHandler = new UserXBRLErrorHandler(); xbrlProc.setErrorHandler(xbrlErrorHandler); // To set up the XBRL processor FormulaLinkProcessorFactory.setUpXBRLProcessor(xbrlProc); // To load the instance you want to validate Instance inputInstance = xbrlProc.loadInstance(new StreamSource("localfiles/smp_validate.xml")); // Check errors while loading the XBRL instance if(xbrlErrorHandler.isErrorDetected()){


} // To execute validation bool result = formulaProc.validate(inputInstance, null, null); The result of the above is that the XBRL instance is validated in accordance with the Formula definitions, and the result is returned as Boolean values. If an error occurs during validation, depending on the error type, the method of the class that implemented FormulaLinkErrorHandler is called. The validation results are posted to the class that implemented FormulaLinkResultHandler.


9

The validate() method does not execute the calculation expressions coded in the Formula definitions. Therefore, if you want to perform evaluation processing, use the evaluate() method described in Section 2.2.1.

2.2.3 Selecting which calculation expressions and validation

expressions are to be executed

Multiple calculation expressions and validation expressions are defined in Formula definitions. If you want to select specific calculation expressions and validation expressions, create a class in which the FormulaLinkFilter interface (filter) is implemented and specify this as the second argument in the evaluate() method of the FormulaLinkProcessor class. If a filter is not specified (if null is specified), all calculation expressions and validation expressions are executed. An example is shown below. // To create a class object for receiving the information needed to distinguish which calculation expressions are to be executed // For the UserFormulaLinkFilter, set the class that has implemented FormulaLinkFilter. UserFormulaLinkFilter filter = new UserFormulaLinkFilter(); // To create the XBRL processor XBRLProcessor xbrlProc = new XBRLProcessor(); // To create a class object for receiving error information from the XBRL processor // For the UserXBRLErrorHandler, set the class that has implemented XBRLErrorHandler UserXBRLErrorHandler xbrlErrorHandler = new UserXBRLErrorHandler(); xbrlProc.setErrorHandler(xbrlErrorHandler); // To set up the XBRL processor FormulaLinkProcessorFactory.setUpXBRLProcessor(xbrlProc); // To load the instance you want to evaluate Instance inputInstance = xbrlProc.loadInstance(new StreamSource("localfiles/smp_evaluate.xml")); // Check errors while loading the XBRL instance if(xbrlErrorHandler.isErrorDetected()){


} // To execute evaluation Instance outputInstance = formulaProc.evaluate(inputInstance, filter, null, null); Formula Processor posts to the filter the information of the calculation expressions and validation expressions to be processed next and asks the filter whether or not these expressions should be executed. If the filter does not authorize execution, Formula Processor skips that calculation expression or validation expression and queries whether the next calculation expression or validation expression should be executed. The user can select which validation expressions they want to be executed by specifying a filter in the validate() method. If a filter is not specified (if null is specified), all validation expressions are executed.


10

2.3 Implementing custom functions Formula specification allow user to define non standard XPath functions which are not defined in XPath, XQuery and XBRLFunction as custom functions. For instance, custom functions may be used, for the specific calculation to be executed efficiently. Or they may be used for the calculation through other systems like databases. Formula processor provides the way of implementing custom function by an application. The following implementation is needed for custom function implementation. (1) Logic for a custom function. (2) Resolver which resolves the custom functions corresponding to inquiries from the processor.

2.3.1 Implementation of custom function logic

Take, for example, power calculation. Let the following custom function be defined.

This custom function declaration includes the following information. - Function name(QName) : my-fn:funcPower (*) let ‘my-fn’ be the prefix for the namespace URI “http://www.user/sample”. - 1st argument : xs:double datatype (always one value) - 2nd argument : xs;double datatype (always one value) - Return values : xs:double datatype (always one value)

(*) The definitions of the argument and the return values are specified with SequenceType Syntax. For more information about SequenceType Syntax, see 2.5.3 section(SequenceType Syntax) in XML Path Language (XPath) 2.0 (http://www.w3.org/TR/xpath20/).

The implementation of a custom function logic is created by implementing evaluate() method of com.fujitsu.xml.xbrl.formula.function.CustomFunction interface. This implementation includes the implementation of the following processes

(1) getting argument values (2) computation of custom function (3) returning result values.


11

The following codes are an implementation example.

public class CustomFunctionPower implements CustomFunction { public Object[] evaluate(List args) { //======== (1) getting argument values ========= // 1st argument - xs:double Object[] cardinalNumbers = (Object[])args.get(0); // (step1) getting a list of argument values Double cardinalNumber = (Double)cardinalNumbers[0]; // (step2) getting each argument value // 2nd argument - xs:double Object[] exponents = (Object[])args.get(1); Double exponent = (Double)exponents[0]; //======== (2) computation of custom function ========= // computing by using Java math function double power = Math.pow(cardinalNumber.doubleValue(), exponent.doubleValue())); //======== (3) returning result values ======== // return values – xs:double Object[] returnValues = new Object[] { Double.valueOf( power ) }; return returnValues; }

}

(1) Getting argument values The argument(‘args’) is a list which stores argument information arranged in order of which they are specified to this custom function.N th argument can be obtained from the description ‘args.get(N)’. ( -> see step1) Each value in a argument can be obtained as an array of Java objects(*1) corresponding to the XML datatype. (-> see step2) If empty sequence is given as a argument, note that the value obtained from the list(args) is null. For instance, if 1st argument is defined as ‘’, the consideration for null is needed as follows.because the empty sequence can be specified.

Double cardinalNumber = ( cardinalNumbers !=null) ? (Double)cardinalNumbers[0] : null ; (2) Computing of custom function In this case, the calculation of power is implemented in Java math function. (3) Returning result values The computed result of custom function has to be returned as an array of Java objects(*1) corresponding to the XML datatype of the return value of the custom function.In this case, the empty sequence can not be returned because the definition of the return value is ‘output=”xs:double”’.But, if the empty sequence is allowable, returning an empty array or null means returning the empty sequence. (*1) The argument values and the return values are transferred with Java objects defined according to the XML schema datatype. As regards the mapping between XML datatype and Java objects, see “Mapping between XML datatype and Java Object” page which is referable from the description of evaluate() method of com.fujitsu.xml.xbrl.formula.function.CustomFunction interface in "Formula Processor API Reference".


12

2.3.2 Implementation of resolver

To enable Formula processor to access to custom function implementations, it is necessary to impl implement a resolver which notifies Formula processor of the corresponding custom function implementation for the inquiries by Formula processor and register it to Formula processor. The resolver is created by implementing resolveCustomFunction() method of com.fujitsu.xml.xbrl.CustomFunctionResolver interface.

The following codes are an implementation example. public class CustomFunctionResolverImpl implements CustomFunctionResolver { public CustomFunctionResolverImpl() {} // custom function implementation shown in section 2.3.1 private CustomFunction customFuncPower = new CustomFunctionPower(); public CustomFunction resolveCustomFunction(String namespaceURI, String name, int argNum){ if ("http://www.user/sample".equals(namespaceURI)

&& ("funcPower".equals(name) && (argNum == 2)){ return customFuncPower;

} // return null if there is no corresponding custom function for inquiries return null; } }

Formula processor inquires the custom function implementation by calling this resolveCustomFunction() method. Inquire information is consist of function name(namespace URI and local name) and the number of arguments. resolveCustomFunction() method has to return the corresponding custom function implementation. If there is no corresponding custom function, return null. The resolver can be registered to Formula processor by setCustomFunctionResolver() method of FormulaLinkProcessor class.Registration must be done before calling evaluate() method or validate() method The following codes are a registration example. FormulaLinkProcessorFactory factory = FormulaLinkProcessorFactory.newInstance(); FormulaLinkProcessor formulaProc = factory.createFormulaLinkProcessor(...); // registration of resolver for custom function to Formula processor formulaProc.setCustomFunctionResolver( new CustomFunctionResolverImpl());


13

2.4 Processing multiple instances In the Formula Extension Module (Variable Instances for Multi-Instance Processing and Chaining 1.0) specification, multiple input/output instances can be handled. In addition to the input/output instances in the Formula1.0 specification, other input/output instances can also be defined. In this chapter, the Formula1.0 specification input instance is called standard input instance, the output instance are called standard output instance, and the other instances that can be handled by the Formula Extension Module are called non-standard instances. For the non-standard instances, there are input and output types. The FormulaLinkParameterList class and FormulaLinkResultHandlerEx interface are used in order to handle the non-standard instance.

2.4.1 Setup of non-standard instances

The non-standard instance information is assigned to the Formula processor after being set as a parameter in FormulaLinkParameterList. The instance name is specified for the parameter name. The prescribed value is specified as the parameter value according to the instance type (input or output). For the input instance information, specify the com.fujitsu.xml.xbrl.xwand.instance.Instance object, which is the actual XBRL document, as the parameter value. For the output instance information, specify the DTS com.fujitsu.xml.xbrl.xwand.taxonomy.TaxonomySet object as the parameter value. Note that consistent input DTSes are needed to be given when specifying multiple input instances. If the DTSes of input instances have inconsistencies, for example, where there are concepts, dimensions or data types with the same name which have different definitions in each DTS, the validity of formula processing is not guaranteed. Instance types (input or output) and instance names: This software treats the instances specified for the Formula processing result output destination by using formula-instance relationships as the output instance, and other ones the input instances.The instance name is defined in the name attribute (this resource is used to define the instance). An example of the Formula definition in which the output instance is defined is shown below:

… … …

In this example, an instance with the name (QName) "i:inst-b" is defined. (*) "i" is the prefix that belongs to the equivalent namespace URI. As seen from variable "variable_a ", instance "i:inst-b" is an input instance by instance-variable relationships. However, since it will be specified for the Formula processing result output destination using formula-instance relationships, it is partitioned as an output instance.

Output

Instance definition: Name is “i:inst-b”

Variable “variable_a”

Input


14

An example of specifying the non-standard input/output instances is shown below:

// To create Formula processor FormulaLinkProcessorFactory formulaProcFactory = FormulaLinkProcessorFactory.newInstance(); FormulaLinkProcessor formulaProc = formulaProcFactory.createFormulaLinkbaseProcessor(...); XBRLProcessor xbrlProc = new XBRLProcessor(); FormulaLinkProcessorFactory.setUpXBRLProcessor(xbrlProc); //======== (1) Load input instances ========= // Standard input Instance stdIns = xbrlProc.loadInstance(new StreamSource("stdInstance.xml")); // Non-standard input Instance nonStdInsA = xbrlProc.loadInstance(new StreamSource("nonStdInstanceA.xml")); Instance nonStdInsB = xbrlProc.loadInstance(new StreamSource("nonStdInstanceB.xml")); //======== (2) Load output DTSes ========= // Standard output TaxonomySet stdOutputTaxSet = xbrlProc.loadTaxonomySet(new StreamSource("stdOutput.xsd")); // Non-standard output TaxonomySet nonStdOutputTaxSetX

= xbrlProc.loadTaxonomySet(new StreamSource("nonStdOutputX.xsd")); TaxonomySet nonStdOutputTaxSetY

= xbrlProc.loadTaxonomySet(new StreamSource("nonStdOutputY.xsd")); //======== (3) Specify non-standard instances as parameters ========= FormulaLinkParameterList paraList = new FormulaLinkParameterList(); // Set non-standard input instance information paraList.setParameter("http://foo", "instanceA", nonStdInsA); paraList.setParameter("http://foo", "instanceB", nonStdInsB); // Set non-standard output instance information paraList.setParameter("http://foo", "instanceX", nonStdOutputTaxSetX); paraList.setParameter("http://foo", "instanceY", nonStdOutputTaxSetY); //======== (4) Excecute evaluation ========= formulaProc.evaluate(stdIns, null, paraList, stdOutputTaxSet);

(1) Load input instances The Instance objects to be specified for the standard input instance and non-standard input instance information respectively are loaded by the XBRLProcessor. The Instance objects must be loaded by the XBRLProcessor that has been configured using FormulaLinkProcessorFactory.setUpXBRLProcessor(XBRLProcessor). (2) Load output DTSes The TaxonomySet objects to be specified for the standard output instance and non-standard output instance information are loaded. (3) Specify non-standard instances as parameters The instance name (QName) is set as the parameter name, and the objects created in (1) and (2) above are set as the parameter values in FormulaLinkParameterList. The non-standard input instance information (XBRL document) cannot be omitted, however the non-standard output instance information (DTS) can be omitted. If this is omitted, the standard output instance DTS will be applied by default. (4) Execute evaluation The evaluation with the non-standard instance information can be executed by specifying FormulaLinkParameterList that was set in (3) above in the FormulaLinkProcessor evaluate or validate methods.The standard input instance information (Instance object) is specified directly in the first argument of the evaluate and validate methods. The standard output instance information (TaxonomySet object) is specified directly in the evaluate method. In this example, the Formula evaluation is executed after a total of six instances are assigned (one standard input instance, one standard output instance, two non-standard input instances and two non-standard output instances).


15

2.4.2 Handling of non-standard output instances

By using the FormulaLinkResultHandlerEx interface instead of the FormulaLinkResultHandler interface, in addition to the standard output instance it is also possible to obtain multiple output instances including non-standard output instances. FormulaLinkResultHandlerEx inherits FormulaLinkResultHandler. In the same way as for FormulaLinkResultHandler, set the implementation of the FormulaLinkResultHandlerEx in the FormulaLinkProcessor setResultHandler method. FormuaLinkResultHandlerEx interface has the following two methods, which do not exist in FormulaLinkResultHandler.

(1) void formulaResult(Item, FormulaContext, InstanceResourceInformation); (2) void formulaFinalResult(Instance, InstanceResourceInformation);

The instance definition information for the Formula definition (InstanceResourceInformation) is notified to each final argument. From this information, the instance name can be obtained. This name identifies which output instance defined in the Formula definition are related to the output instance or output fact notified in the first argument. Note that the name of standard output instance has already been defined in the Variable Instances for Multi-Instance Processing and Chaining 1.0 specification. The name (QName) of standard output instance: Namespace URI: "http://xbrl.org/2010/variable/instance" Local name: "standard-output-instance"


16

An example of the FormulaLinkResultHandlerEx implementation that obtains multiple output instances is shown below:

public class ResultHandlerExImpl implements FormulaLinkResultHandlerEx { public void assertionFinalResult(boolean result) { // The same information as for FormulaLinkResultHandler is notified. } public void assertionResult(boolean result, AssertionContext cxt) { // The same information as for FormulaLinkResultHandler is notified. } public void formulaFinalResult(Instance ins, InstanceResourceInformation res) { // The instance passed in the first argument can be identified from the second argument information. if (res == null) { // This is a standard output instance for which there is no instance definition in the Formula definition. } else { // There is explicitly an instance definition in the Formula definition String insNamespaceURI = res.getInstanceNamespaceURI(); // the namespace URI of Instance String insLocalName = res.getInstanceLocalName(); // the local name of Instance if ("http://xbrl.org/2010/variable/instance".equals(insNamespaceURI) && "standard-output-instance".equals(insLocalName)) { // This is a standard output instance. … } else { // This is a non-standard output instance. … } } } public void formulaResult(Item item, FormulaContext cxt, InstanceResourceInformation res) { // In the same way as for the above formulaFinalResult method implementation, // the output instance that item of the first argument belongs to can be identified from // the second argument information. } public void formulaFinalResult(Instance instance) { // This is not called. } public void formulaResult(Item item, FormulaContext cxt) { // This is not called. } }

For a standard output instance, note that omission of the instance definition from the Formula definition is allowed. If this is omitted, null will be notified for the instance definition information (InstanceResourceInformation) in the formulaResult and formulaFinalResult methods. All Formula evaluation results (standard and non-standard output instances) are notified to the formulaFinalResult method. A standard output instance is also returned as a FormulaLinkProcessor evaluate method return value, however non-standard output instances are only notified to the formulaFinalResult method. So where necessary, the application should retain the non-standard output instance which is notified to this method.


17

2.5 Obtaining validation messages In the Formula Extension Module (Validation messages 1.0) specification, an output message can be defined for the validation processing results (satisfied or unsatisfied). Since the validation processing context information (such as variable values used in an operation) can be embedded in the message, the user can read off the processes that have led to the validation results from the message. The validation message can be obtained from the following four methods in the AssertionContext interface: (1) Method that obtains the message as string (java.lang.String)

(a) getExpandedValidationMessage (b) getExpandedValidationMessages

(2) Method that obtains the message as DOM (org.w3c.dom.DocumentFragment) (a) getExpandedValidationMessageAsDocumentFragment (b) getExpandedValidationMessagesAsDocumentFragment

AssertionContext is the information notified in assertionResult method of the FormulaLinkResultHandler (or FormulaLinkResultHandlerEx) interface. The above method obtains the validation message that corresponds to the validation result type (true or false) notified in the first argument of assertionResult method. If the message is defined in plain text, use the method in (1). If the message is defined using structured XML, use the method in (2). Multiple validation messages may be defined, with extended link roles, message roles, and languages differentiated. These three conditions can be specified in the above method, and only the validation messages that meet the conditions can be obtained. If it is necessary to obtain all the validation messages that meet the condition, use the methods in (b) of (1) and (2). If it is only necessary to obtain one validation message, use the methods in (a) of (1) and (2).


18

An example of the implementation of assertionResult method of FormulaLinkResultHandler is shown below:

public void assertionResult(boolean result, AssertionContext assertionContext) { try { String resRole="http://www.xbrl.org/2010/role/verboseMessage"; String extRole="http://www.xbrl.org/2008/role/link"; String lang="en"; String[] messages = assertionContext.getExpandedValidationMessages(extRole, resRole, lang); if (messages.length >0){ String resultString = (result) ? "Satisfied " : "Unsatisfied "; for (int i = 0; i < messages.length; i++) { System.out.println(resultString + " message["+i+"]:"+ messages[i]); } } } catch (FormulaLinkEvaluateException e) { // When evaluation of the XPath expression embedded in the message fails } }

In this example, all the validation messages related to the assertion evaluation result (true or false) passed in the result argument are obtained as plain text under the following conditions:

- Extended link role: "http://www.xbrl.org/2008/role/link" - Message role: "http://www.xbrl.org/2010/role/verboseMessage" - Language: "en"

If you want to omit any of the three above conditions, specify null for that condition. Note that, when the XPath expression embedded in the validation message is evaluated and an XPath evaluation error occurs, the exception FormulaLinkEvaluateException is thrown. In this example, the getExpandedValidationMessages method that obtains the validation message string (java.lang.String) is used, however the implementation is also the same as for when the method that obtains DOM (DocumentFragment) is used.


19

2.6 Notes The following notes apply for Formula Processor:

- Name space declarations declared in child elements or descendent elements of the following elements are ignored:

- formula:formula element - cf:conceptName element - cf:conceptCustomAttribute element - cf:conceptDataType element - cf:conceptSubstitutionGroup element - df:explicitDimension element - df:typedDimension element - tf:parentFilter element - tf:ancestorFilter element - uf:singleMeasure element - variable:function element - acf:aspectCover element - crf:conceptRelation element - cfi:implementation

- When equivalent facts are compared during evaluation or validation, the value of the fact itself and the character data in descendent elements of a segment element or scenario element in the context referenced by the fact are compared without changing the original values. (For example, white spaces before or after the values are not removed.)

- When a result fact is output after evaluation ends, the value of the fact itself and the character data in

descendent elements of a segment element or scenario element in the context referenced by the fact are output without changing the original values. (For example, white spaces before or after the values are not removed.)

- Notes on the usage of “com.fujitsu.xml.xbrl.formula.ConsistencyAssertionContext” class

The following two methods are provided for getting the input facts that aspect-match the derived fact produced when evaluating the formula.

(a) Returns all of the aspect-matched facts com.fujitsu.xml.xbrl.xwand.instance.Item[] getMatchedFacts()

(b) Returns the aspect-matched fact found first in document order of the input instance com.fujitsu.xml.xbrl.xwand.instance.Item getMatchedFact()

If you know beforehand that the input instance does not contain duplicated items, the source program can be simplified by using the method (b), because the aspect-matched fact is only one. On the other hand, you must use the method (a), because two or more aspect-matched facts might exist.

- The following new functions were added to the XBRL Functions. Our implementation newly supports

them. * xff.uncovered-aspect, * xfi.linkbase-link-roles * xfi.concept-label, * xfi.arcrole-definition * xfi.role-definition, * xfi.fact-footnotes * xfi.concept-relationships, * xfi.relationship-from-concept * xfi.relationship-to-concept, * xfi.distinct-nonAbstract-parent-concepts * xfi.relationship-attribute, * xfi.relationship-link-attribute * xfi.relationship-name, * xfi.relationship-link-name * xfi.format-number


20

- API points that have changed

[V11 → V12] There are newly added APIs, and APIs for which the behavior specifications have been extended.Refer to "Formula Processor API Reference" for details.

Changes for errata corrections in the Variables1.0 specification:

[Added error codes]

com.fujitsu.xml.xbrl.formula.FormulaLinkException XBRLVE_PARAMETER_CYCLIC_DEPENDENCIES_ERROR

[Added methods] com.fujitsu.xml.xbrl.formula.AssertionContext

getGlobalParameters com.fujitsu.xml.xbrl.formula.FormulaContext

getGlobalParameters

Changes for errata corrections in the Dimension Filters 1.0 specification:

[Error codes (deprecated) ] com.fujitsu.xml.xbrl.formula.FormulaLinkException

XBRLDFE_INVALID_DOMAINMEMBER_ERROR XBRLDFE_AMBIGUOUS_FILTER_MEMBER_NETWORK_ERROR

Since the corresponding error codes have been removed from the specification, these errors no longer occur.

Changes for the Formula Extension Modules:

Support for multiple instance processing

[Added interfaces]

com.fujitsu.xml.xbrl.formula.FormulaLinkResultHandlerEx com.fujitsu.xml.xbrl.formula.InstanceResourceInformation

[Added resource type constants] com.fujitsu.xml.xbrl.formula.ResourceInformation

RESOURCE_TYPE_INSTANCE [Added error codes and related definitions]

com.fujitsu.xml.xbrl.formula.FormulaLinkException VARIABLE_INSTANCE_ERROR_NAMESPACE_URI VARIABLE_INSTANCE_ERROR_PREFIX XBRLVARINSTE_INSTANCE_VARIABLE_RECURSION_CYCLE_ERROR

[Expanded class behavior specification] com.fujitsu.xml.xbrl.formula.FormulaLinkParameterList

[Expanded method behavior specification] com.fujitsu.xml.xbrl.formula.BoundVariable

getVariableType getValue getResourceInformation

com.fujitsu.xml.xbrl.formula.FormulaLinkProcessor evaluate(Instance, …) validate(Instance, …)

com.fujitsu.xml.xbrl.formula.ResourceInformation getResourceType


21

Support for validation messages

[Added interfaces]

com.fujitsu.xml.xbrl.formula.GenericMessage [Added resource type constants]

com.fujitsu.xml.xbrl.formula.ResourceInformation RESOURCE_TYPE_GENERIC_MESSAGE

[Added error codes and related definitions] com.fujitsu.xml.xbrl.formula.FormulaLinkException

GENERIC_MESSAGES_ERROR_NAMESPACE_URI GENERIC_MESSAGES_ERROR_PREFIX XBRLMSGE_MISSING_LEFT_CURLY_BRACKET_ERROR XBRLMSGE_MISSING_RIGHT_CURLY_BRACKET_ERROR

[Added methods] com.fujitsu.xml.xbrl.formula.AssertionContext

getExpandedValidationMessages getExpandedValidationMessage getExpandedValidationMessagesAsDocumentFragment getExpandedValidationMessageAsDocumentFragment

com.fujitsu.xml.xbrl.formula.ResourceInformation getGenericMessages

[Expaneded method behavior specifications] com.fujitsu.xml.xbrl.formula.BoundVariable

getResourceInformation com.fujitsu.xml.xbrl.formula.ResourceInformation

getResourceType

Support for Custom Function Implementation

[Added error codes and related definitions] com.fujitsu.xml.xbrl.formula.FormulaLinkException

CUSTOM_FUNCTION_IMPLEMENTATION_ERROR_NAMESPACE_URI CUSTOM_FUNCTION_IMPLEMENTATION_ERROR_PREFIX XBRLCFIE_INPUT_MISMATCH_ERROR XBRLCFIE_MISSING_CFI_RELATIONSHIP_ERROR XBRLCFIE_TOO_MANY_CFI_RELATIONSHIPS_ERROR

Support for Aspect Cover filter

[Added error codes and related definitions]

com.fujitsu.xml.xbrl.formula.FormulaLinkException ASPECT_COVER_FILTER_ERROR_NAMESPACE_URI ASPECT_COVER_FILTER_ERROR_PREFIX XBRLACFE_INCONSISTENT_ASPECT_COVER_FILTERS_ERROR

Added convienient API

The same context information as xff.uncovered-aspect function can be obtained.

[Added interfaces] com.fujitsu.xml.xbrl.formula.AspectValue

[Added methods] com.fujitsu.xml.xbrl.formula.ValueAssertionContext

getUncoverAspectValues com.fujitsu.xml.xbrl.formula.FormulaContext

getUncoverAspectValues com.fujitsu.xml.xbrl.formula.BoundVariable

getAspectValues


22

Added evaluation/validation API

The XBRL Dimensions data model (com.fujitsu.xml.xbrl.dimension.instance.DimensionalInstance) can be specified as the evaluation/validation target input XBRL instance.It is strongly recommended to use this API for faster Formula processing.

[Added methods]

com.fujitsu.xml.xbrl.formula.FormulaLinkProcessor evaluate(DimensionalInstance, …) validate(DimensionalInsance, …)

- Problem correction history

[V12] If the dimension axis information has not been explicitly defined in the context, it will be

assumed that there is no dimension information, even where the default dimension value exists. The problem where implicit filtering and relative filter do not always run correctly in such cases has been fixed.

Chapter 3 Specifications Basis

23



24

3.1 Overview Formula Processor conforms to the following specifications:

- Formula Specification 1.0 (2009 - 2011) [Recommendation]

- Boolean Filters 1.0 - Concept Filters 1.0 - Consistency Assertions 1.0 - Dimension Filters 1.0 (includes errata corrections to 2011-03-10) - Entity Filters 1.0 - Existence Assertions 1.0 - Formula 1.0 - General Filters 1.0 - Generic labels 1.0 - Generic references 1.0 - Implicit Filters 1.0 - Match Filters 1.0 - Period Filters 1.0 - Relative Filters 1.0 - Segment and scenario filters 1.0 - Tuple Filters 1.0 - Unit Filters 1.0 - Validation 1.0 - Value Assertions 1.0 - Value Filters 1.0 - Variables 1.0 (includes errata corrections to 2010-03-16)

- Aspect Cover Filters 1.0

- Concept Relation Filters 1.0

- XBRL Custom Function Implementation Specification 1.0

- Generic messages 1.0

- Validation messages 1.0

- Formula Extension Modules-Instances-(2011-10-19) [Candidate Recommendation]

Variable Instances for Multi-Instance Processing and Chaining 1.0 (4th CR)


25

- XBRL Functions [Recommendation]

xfi:context xfi:duplicate-item xfi:unit xfi:duplicate-tuple xfi:unit-numerator xfi:p-equal xfi:unit-denominator xfi:cu-equal xfi:measure-name xfi:pc-equal xfi:period xfi:pcu-equal xfi:context-period xfi:start-equal xfi:is-start-end-period xfi:end-equal xfi:is-forever-period xfi:nodes-correspond xfi:is-duration-period xfi:facts-in-instance xfi:is-instant-period xfi:items-in-instance xfi:period-start xfi:tuples-in-instance xfi:period-end xfi:items-in-tuple xfi:period-instant xfi:tuples-in-tuple xfi:entity xfi:non-nil-facts-in-instance xfi:context-entity xfi:concept-balance xfi:identifier xfi:concept-period-type xfi:context-identifier xfi:concept-custom-attribute xfi:entity-identifier xfi:concept-data-type xfi:identifier-value xfi:concept-data-type-derived-from xfi:identifier-scheme xfi:concept-substitutions xfi:segment xfi:filter-member-network-selection xfi:entity-segment xfi:fact-segment-remainder xfi:context-segment xfi:fact-scenario-remainder xfi:scenario xfi:fact-has-explicit-dimension xfi:context-scenario xfi:fact-has-typed-dimension xfi:fact-identifier-value xfi:fact-has-explicit-dimension-value xfi:fact-identifier-scheme xfi:fact-explicit-dimension-value xfi:is-non-numeric xfi:fact-typed-dimension-value xfi:is-numeric xfi:fact-dimension-s-equal2 xfi:is-fraction xfi:linkbase-link-roles xfi:precision xfi:concept-label xfi:decimals xfi:arcrole-definition xff:uncovered-aspect xfi:role-definition xfi:identical-nodes xfi:fact-footnotes xfi:s-equal xfi:concept-relationships xfi:u-equal xfi:relationship-from-concept xfi:v-equal xfi:relationship-to-concept xfi:c-equal xfi:distinct-nonAbstract-parent-concepts xfi:identical-node-set xfi:relationship-attribute xfi:s-equal-set xfi:relationship-link-attribute xfi:v-equal-set xfi:relationship-name xfi:c-equal-set xfi:relationship-link-name xfi:u-equal-set xfi:format-number xfi:x-equal


26

3.2 Restrictions The following restrictions apply to Formula Processor:

- Restrictions for custom functions defined in the Variables1.0 specifications(Section 3.1, "Custom function signatures"].

Supported datatypes of the arguments and the return values are a part of the atomic data types defined in XML Schemas, or simple data derived from them. For details, see “Mapping between XML datatype and Java Object” page which is referable from the description of evaluate() method of com.fujitsu.xml.xbrl.formula.function.CustomFunction interface in "Formula Processor API Reference".

- Restrictions for parameters defined in the Variables 1.0 specifications(Section 3.2, "Parameters").

Supported datatypes of the parameters are a part of the atomic data types defined in XML Schemas, or simple data derived from them. For details, see “Mapping between XML datatype and Java Object” page which is referable from the description of com.fujitsu.xml.xbrl.formula.FormulaLinkParameterList class in "Formula Processor API Reference".

ContentsChapter 1 The Outline of Formula Processor1.1 Purpose1.2 Outline of Functions

Chapter 2 Method of Use2.1 Creating a processor2.2 Processing an XBRL Instance2.2.1 Evaluation processing2.2.2 Validation processing2.2.3 Selecting which calculationexpressions and validation expressions are to be executed

2.3 Implementing custom functions2.3.1 Implementation of custom function logic2.3.2 Implementation of resolver

2.4 Processing multiple instances2.4.1 Setup of non-standard instances2.4.2 Handling of non-standard output instances

2.5 Obtaining validation messages2.6 Notes

Chapter 3 Specifications Basis3.1 Overview3.2 Restrictions

Formula Processor Development Guide - Fujitsu · What This Guide Is About This is Formula Processor...

Documents

Transcript of Formula Processor Development Guide - Fujitsu · What This Guide Is About This is Formula Processor...