com.ihr.xbrl.om.formula
Class XBRLFormulaProcessor

java.lang.Object
  com.ihr.xbrl.om.formula.XBRLFormulaProcessor

All Implemented Interfaces:

XBRLPlugInProcessor

public class XBRLFormulaProcessor
extends java.lang.Object
implements XBRLPlugInProcessor

Author:

Ignacio

Field Summary

static java.lang.String	assertion_satisfied_message_URI http://xbrl.org/arcrole/2010/assertion-satisfied-message
static java.lang.String	assertion_set_arcrole_URI http://xbrl.org/arcrole/2008/assertion-set
static java.lang.String	assertion_unsatisfied_message_URI http://xbrl.org/arcrole/2010/assertion-unsatisfied-message
static java.lang.String	boolean_filter_arcrole_URI http://xbrl.org/arcrole/2008/boolean-filter
static java.lang.String	consistency_assertion_formula_URI http://xbrl.org/arcrole/2008/consistency-assertion-formula
static java.lang.String	consistency_assertion_parameter_URI http://xbrl.org/arcrole/2008/consistency-assertion-parameter
static java.lang.String	equality_definition_arcrole_URI http://xbrl.org/arcrole/2008/equality-definition
static java.lang.String	PROCESSORNAME
static javax.xml.namespace.QName	qError
static java.lang.String	variable_filter_arcrole_URI http://xbrl.org/arcrole/2008/variable-filter
static java.lang.String	variable_set_arcrole_URI http://xbrl.org/arcrole/2008/variable-set
static java.lang.String	variable_set_filter_arcrole_URI http://xbrl.org/arcrole/2008/variable-set-filter
static java.lang.String	variable_set_precondition_arcrole_URI http://xbrl.org/arcrole/2008/variable-set-precondition

Method Summary

void	addAssertion(XBRLAssertion assertion)
void	addConsistencyAssertion(XBRLConsistencyAssertion consistencyAssertion)
void	addCustomFunctionDeclaration(XBRLCustomFunction customFunction)
void	addCustomFunctionLibrary(XBRLRSCustomFunctionLibrary fl) Adds a Function Library to the set of function libraries available to the processor.
void	addFormula(XBRLFormula formula)
void	addInScopeInstance(XBRLInstance doc)
void	addVariableParameter(XBRLVariableParameter variableParameter)
void	addXFFLibrary(net.sf.saxon.expr.StaticContext sc)
void	addXFILibrary(net.sf.saxon.expr.StaticContext sc)
static java.lang.String	cleanFormulaExpression(java.lang.String expression) Helper function that cleans up the content of an XPath expression so it can be used as a text string in a GUI.
void	collectVariables(java.util.Collection<javax.xml.namespace.QName> hsVars) Add parameter variables to the collection received as a parameter This method can add only global variables available to all formulas
static net.sf.saxon.s9api.XPathExecutable	compileExpressionAndCollectRequiredVariables(java.lang.String selectExpression, java.util.Collection<javax.xml.namespace.QName> requiredVariables, java.util.Collection<net.sf.saxon.s9api.QName> preDefinedVariables, net.sf.saxon.om.NamespaceResolver nsResolver, XBRLFormulaResource fragment)
void	compileResources()
void	configure(java.util.Properties properties) Configures the processor according with the properties passed in in the properties parameter
static XBRLFormulaProcessor	create(DTSContainer dts)
static void	declareNamespaces(XBRLResource resource, net.sf.saxon.s9api.XPathCompiler compiler) Helper method to declare all namespaces in the resource indicated as a parameter in the XPath compiler received as a parameter
XBRLValidationReport	evaluate(XBRLResource resource, XBRLInstance instance) Evaluates one resource and returns an XBRLValidationReport instance.
void	evaluateFormulaSet(java.util.Collection<XBRLFormula> formulas, XBRLValidationReport valReport, XBRLInstance doc, ExecutionTargetType targetType) Evaluates a collection of formulas and put the result inside the validation report passed in as parameter valReport.
AspectsCache	getAspectsCache() The aspects cache is used internally by the processor in order to accelerate implicit filtering.
XBRLArcroleType	getAssertionSatisfiedMessageArcroleType()
XBRLArcroleType	getAssertionUnsatisfiedMessageArcroleType()
XBRLArcroleType	getAssetionSetArcroleType()
XBRLArcroleType	getBooleanFilterArcroleType()
XBRLFact	getCacheFact(net.sf.saxon.s9api.XdmNode factNode) Search for a fact using the fact node.
XBRLArcroleType	getConsistencyAssertionFormulaArcroleType()
XBRLArcroleType	getConsistencyAssertionParameterArcroleType()
DTSContainer	getContainer()
XBRLContext	getContextById(java.lang.String id, java.net.URI documentURI)
java.lang.String	getDescription() Returns the processor description so it can be written in validation reports
static java.lang.String	getDescriptionStatic()
XMLFragment	getElementById(java.lang.String id, java.net.URI documentURI)
XBRLArcroleType	getEqualityDefinitionArcroleType()
FilterMemberCache	getFilterMemberCache()
XBRLFilterOrderTool	getFilterOrderInstance() The formula specification is not defining the order in which filters shall be arranged to create the XPath evaluation expression.
net.sf.saxon.s9api.XPathCompiler	getFPXPathCompiler(net.sf.saxon.om.NamespaceResolver namespaceResolver, XMLFragment fragment, boolean schemaAware) Always return a new XPathCompiler object with the IndependentContext namespace Resolver set to the namespaceResolver supplied as a parameter.
java.lang.String	getName() Returns the processor name so it can be written in validation reports
XBRLFormulaParametersResolver	getParameterResolver()
java.util.Vector<XBRLVariableResourceUse>	getParametersForBinding() Creates a new Vector of XBRLVariableResourceUse and returns it to the calling application.
FormulaProcessorStatus	getStatus() Normally called from another thread, this method returns an instance of a FormulaProcessorStatus class that provides information about the number of formulas, number of assertions, number of consistency assertions. number of running threads, maximum time of a thread and what every thread is doing.
XBRLFormula	getUnderEvaluationFormula() This method returns the formula that is being evaluated.
XBRLInstance	getUnderEvaluationInstance()
HasUncoveredAspectValueResolver	getUnderEvaluationUncoveredAspectValue() Access to the value of the instance of the class that will resolve values for the xff:uncovered-aspect function.
javax.xml.namespace.QName	getUnderEvaluationVariableName() During the evaluation of an XPath expression in order to set the value of a variable name, the variable name of the variable that is being evaluated can be obtained by a call to this method.
XBRLUnit	getUnitById(java.lang.String id, java.net.URI documentURI)
XBRLValidationReport	getValidationReport() Access to the validation report that is active during formula validation.
XBRLArcroleType	getVariableFilterArcroleType()
XBRLArcroleType	getVariableSetArcroleType()
XBRLArcroleType	getVariableSetFilterArcroleType()
XBRLArcroleType	getVariableSetPreconditionArcroleType()
void	informEnd(AssertionExecutor ae, long elapsedTime) Called from other threads once execution ends.
void	informRunning(AssertionExecutor ae) Called from the thread running the XBRLFormulaProcessor instance.
boolean	matcheable(XBRLFact fact1, XBRLFact fact2, int aspectModel, XMLFragment context) Computes if two facts are aspect-matched input facts as defined in the Formula specification.
void	removeFormula(XBRLFormula xbrlFormula) Marks a formula to be removed from the formula list.
void	removeInScopeInstance(XBRLInstance doc)
void	setParametersResolver(XBRLFormulaParametersResolver pResolver) Sets the external parameters resolver to the instance of the class indicated by the parameter
void	setUnderEvaluationFormula(XBRLFormula formula) This method sets the value of the formula that is being evaluated.
void	setUnderEvaluationInstance(XBRLInstance valInstance) Sets or clear the instance document that is in the scope of formula functions.
void	setUnderEvaluationUncoveredAspectValue(HasUncoveredAspectValueResolver resolver) Sets the value for the resolver of the xff:uncovered-aspect function.
void	setUnderEvaluationVariable(javax.xml.namespace.QName variableName)
XBRLValidationReport	validate() Validates the content of the DTS according to the rules indicated in this plug-in processor.
XBRLValidationReport	validate(XBRLDocument doc) Validates the document according to the rules indicated in this plug-in processor.
XBRLValidationReport	validate(XBRLInstance doc) This method validates an instance document (doc) against the content of the formula linkbase.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

qError

public static javax.xml.namespace.QName qError

PROCESSORNAME

public static final java.lang.String PROCESSORNAME

See Also:

Constant Field Values

variable_set_arcrole_URI

public static final java.lang.String variable_set_arcrole_URI

http://xbrl.org/arcrole/2008/variable-set

See Also:

Constant Field Values

variable_filter_arcrole_URI

public static final java.lang.String variable_filter_arcrole_URI

http://xbrl.org/arcrole/2008/variable-filter

See Also:

Constant Field Values

variable_set_filter_arcrole_URI

public static final java.lang.String variable_set_filter_arcrole_URI

http://xbrl.org/arcrole/2008/variable-set-filter

See Also:

Constant Field Values

variable_set_precondition_arcrole_URI

public static final java.lang.String variable_set_precondition_arcrole_URI

http://xbrl.org/arcrole/2008/variable-set-precondition

See Also:

Constant Field Values

equality_definition_arcrole_URI

public static final java.lang.String equality_definition_arcrole_URI

http://xbrl.org/arcrole/2008/equality-definition

See Also:

Constant Field Values

consistency_assertion_formula_URI

public static final java.lang.String consistency_assertion_formula_URI

http://xbrl.org/arcrole/2008/consistency-assertion-formula

See Also:

Constant Field Values

consistency_assertion_parameter_URI

public static final java.lang.String consistency_assertion_parameter_URI

http://xbrl.org/arcrole/2008/consistency-assertion-parameter

See Also:

Constant Field Values

assertion_satisfied_message_URI

public static final java.lang.String assertion_satisfied_message_URI

http://xbrl.org/arcrole/2010/assertion-satisfied-message

See Also:

Constant Field Values

assertion_unsatisfied_message_URI

public static final java.lang.String assertion_unsatisfied_message_URI

http://xbrl.org/arcrole/2010/assertion-unsatisfied-message

See Also:

Constant Field Values

boolean_filter_arcrole_URI

public static final java.lang.String boolean_filter_arcrole_URI

http://xbrl.org/arcrole/2008/boolean-filter

See Also:

Constant Field Values

assertion_set_arcrole_URI

public static final java.lang.String assertion_set_arcrole_URI

http://xbrl.org/arcrole/2008/assertion-set

See Also:

Constant Field Values

Method Detail

configure

public void configure(java.util.Properties properties)

Description copied from interface: XBRLPlugInProcessor

Configures the processor according with the properties passed in in the properties parameter

Specified by:

configure in interface XBRLPlugInProcessor

addXFILibrary

public void addXFILibrary(net.sf.saxon.expr.StaticContext sc)

addXFFLibrary

public void addXFFLibrary(net.sf.saxon.expr.StaticContext sc)

create

public static XBRLFormulaProcessor create(DTSContainer dts)
                                   throws com.rs.lic.LicenseVerificationException,
                                          XBRLValidationException

Throws:

com.rs.lic.LicenseVerificationException

XBRLValidationException

getVariableSetArcroleType

public XBRLArcroleType getVariableSetArcroleType()

getVariableFilterArcroleType

public XBRLArcroleType getVariableFilterArcroleType()

getVariableSetFilterArcroleType

public XBRLArcroleType getVariableSetFilterArcroleType()

getVariableSetPreconditionArcroleType

public XBRLArcroleType getVariableSetPreconditionArcroleType()

getEqualityDefinitionArcroleType

public XBRLArcroleType getEqualityDefinitionArcroleType()

getConsistencyAssertionParameterArcroleType

public XBRLArcroleType getConsistencyAssertionParameterArcroleType()

getConsistencyAssertionFormulaArcroleType

public XBRLArcroleType getConsistencyAssertionFormulaArcroleType()

getAssertionSatisfiedMessageArcroleType

public XBRLArcroleType getAssertionSatisfiedMessageArcroleType()

getAssertionUnsatisfiedMessageArcroleType

public XBRLArcroleType getAssertionUnsatisfiedMessageArcroleType()

getBooleanFilterArcroleType

public XBRLArcroleType getBooleanFilterArcroleType()

getAssetionSetArcroleType

public XBRLArcroleType getAssetionSetArcroleType()

validate

public XBRLValidationReport validate()

Description copied from interface: XBRLPlugInProcessor

Validates the content of the DTS according to the rules indicated in this plug-in processor.

This is the method that is called by the DTSContainer on each XBRLPlugInProcessor when the validation() method is called on the DTSContainer instance.

Specified by:

validate in interface XBRLPlugInProcessor

Returns:

an XBRLValidationReport object XBRLValidationReport

validate

public XBRLValidationReport validate(XBRLDocument doc)

Description copied from interface: XBRLPlugInProcessor

Validates the document according to the rules indicated in this plug-in processor.

Specified by:

validate in interface XBRLPlugInProcessor

Returns:

an XBRLValidationReport object XBRLValidationReport

validate

public XBRLValidationReport validate(XBRLInstance doc)

This method validates an instance document (doc) against the content of the formula linkbase. The validation result is returned in a XBRLValidationReport object. That object includes exceptions, assertion results and the output instance.

Parameters:

doc - input instance document

Returns:

XBRLValidationReport validation report object with errors

getAspectsCache

public AspectsCache getAspectsCache()

The aspects cache is used internally by the processor in order to accelerate implicit filtering. It is not available to users for their own use.

For internal use only.

Returns:

null if the processor is not evaluating formulas or the instance of the AspectsCache for the running processor

getFilterMemberCache

public FilterMemberCache getFilterMemberCache()

Returns:

informRunning

public void informRunning(AssertionExecutor ae)

Called from the thread running the XBRLFormulaProcessor instance. This method copies the assertion executor into the list of running executors

Parameters:

ae -

informEnd

public void informEnd(AssertionExecutor ae,
                      long elapsedTime)

Called from other threads once execution ends.

Parameters:

ae -

elapsedTime -

removeInScopeInstance

public void removeInScopeInstance(XBRLInstance doc)

Parameters:

doc -

addInScopeInstance

public void addInScopeInstance(XBRLInstance doc)

Parameters:

doc -

setUnderEvaluationFormula

public void setUnderEvaluationFormula(XBRLFormula formula)

This method sets the value of the formula that is being evaluated.

Parameters:

formula - instance of an XBRLFormula or null to unset the value after formula execution is finished

See Also:

getUnderEvaluationFormula()

getUnderEvaluationFormula

public XBRLFormula getUnderEvaluationFormula()

This method returns the formula that is being evaluated. This method can be used by functions that requires access to variables and the assigned value for a variable during the evaluation of an XPath expression

Returns:

XBRLFormula

See Also:

setUnderEvaluationFormula(XBRLFormula)

evaluateFormulaSet

public void evaluateFormulaSet(java.util.Collection<XBRLFormula> formulas,
                               XBRLValidationReport valReport,
                               XBRLInstance doc,
                               ExecutionTargetType targetType)

Evaluates a collection of formulas and put the result inside the validation report passed in as parameter valReport.

This method is called from the processor in order to evaluate the formula set and from assertions that contains dependant formulas before the assertion is evaluated.

Parameters:

formulas - the collection of formulas to evaluate

valReport - the validation report where the results will be placed. The returned instance document will he here too.

doc - the contextual information for the formulas to evaluate.

consistencycheck -

getValidationReport

public XBRLValidationReport getValidationReport()

Access to the validation report that is active during formula validation.

This method is used internally by the API in order to add warning messages generated by the evaluation of filters and other areas of the formula processor.

Returns:

the validationReport which is an instance of XBRLValidationReport or null if the processor is not under validation

getContainer

public DTSContainer getContainer()

compileResources

public void compileResources()
                      throws XFValidationException

Throws:

XFValidationException

net.sf.saxon.trans.XPathException

addVariableParameter

public void addVariableParameter(XBRLVariableParameter variableParameter)
                          throws XFxbrlveParameterNameClash

Parameters:

variableParameter -

Throws:

XFxbrlveParameterNameClash

addCustomFunctionLibrary

public void addCustomFunctionLibrary(XBRLRSCustomFunctionLibrary fl)

Adds a Function Library to the set of function libraries available to the processor. Function Libraries implements XPath functions that may be referenced from within XPath 2.0 expressions and extends the functionality of the formula processor.

Parameters:

fl - the new FunctionLibrary instance

addFormula

public void addFormula(XBRLFormula formula)

Parameters:

formula -

declareNamespaces

public static void declareNamespaces(XBRLResource resource,
                                     net.sf.saxon.s9api.XPathCompiler compiler)

Helper method to declare all namespaces in the resource indicated as a parameter in the XPath compiler received as a parameter

Parameters:

resource - the source element where the namespaces are declared

compiler - the target XPath compiler where namespaces will be copied to

getUnderEvaluationInstance

public XBRLInstance getUnderEvaluationInstance()

Returns:

setUnderEvaluationInstance

public void setUnderEvaluationInstance(XBRLInstance valInstance)

Sets or clear the instance document that is in the scope of formula functions. If the argument is null, all instances in the scope are removed.

Parameters:

valInstance -

getFPXPathCompiler

public net.sf.saxon.s9api.XPathCompiler getFPXPathCompiler(net.sf.saxon.om.NamespaceResolver namespaceResolver,
                                                           XMLFragment fragment,
                                                           boolean schemaAware)

Always return a new XPathCompiler object with the IndependentContext namespace Resolver set to the namespaceResolver supplied as a parameter. This function also adds the XFI function library to the XPath compiler.

Parameters:

namespaceResolver -

fragment - XMLFragment used to obtain the Base URI for the XPathCompiler

schemaAware - if true, the new XPathCompiler will be Schema Aware. All schemas currently loaded will be in the scope schemas for XPath compilation. It is safe to always put 'true' here.

Returns:

XPathCompiler

collectVariables

public void collectVariables(java.util.Collection<javax.xml.namespace.QName> hsVars)

Add parameter variables to the collection received as a parameter This method can add only global variables available to all formulas

Parameters:

hsVars -

declaredVars -

getParametersForBinding

public java.util.Vector<XBRLVariableResourceUse> getParametersForBinding()

Creates a new Vector of XBRLVariableResourceUse and returns it to the calling application.

When a parameter is found during the compilation phase it is stored in the XBRLFormulaProcessor instance as an instance of a XBRLVariableParameter. When this function is called, a new Vector with XBRLVariableResourceUse is created so the parameter can be evaluated by multiple threads in parallel.

The class XBRLVariableParameter contains information about the parameter that can be shared across threads. the class XBRLVariableResourceUse is associated with the running thread.

Returns:

new Vector of XBRLVariableResourceUse with all parameters registered in the DTS.

setParametersResolver

public void setParametersResolver(XBRLFormulaParametersResolver pResolver)

Sets the external parameters resolver to the instance of the class indicated by the parameter

Parameters:

pResolver -

getParameterResolver

public XBRLFormulaParametersResolver getParameterResolver()

removeFormula

public void removeFormula(XBRLFormula xbrlFormula)

Marks a formula to be removed from the formula list. This happens if the formula contains unrecoverable errors during static checking or when an assertion will use this formula internally.

The function does nothing if the formula is already removed.

Parameters:

xbrlFormula -

getDescription

public java.lang.String getDescription()

Description copied from interface: XBRLPlugInProcessor

Returns the processor description so it can be written in validation reports

Specified by:

getDescription in interface XBRLPlugInProcessor

getName

public java.lang.String getName()

Description copied from interface: XBRLPlugInProcessor

Returns the processor name so it can be written in validation reports

Specified by:

getName in interface XBRLPlugInProcessor

getDescriptionStatic

public static java.lang.String getDescriptionStatic()

Returns:

addAssertion

public void addAssertion(XBRLAssertion assertion)

Parameters:

xbrlAssertion -

addCustomFunctionDeclaration

public void addCustomFunctionDeclaration(XBRLCustomFunction customFunction)

Parameters:

xbrlCustomFunction -

addConsistencyAssertion

public void addConsistencyAssertion(XBRLConsistencyAssertion consistencyAssertion)

Parameters:

xbrlConsistencyAssertion -

matcheable

public boolean matcheable(XBRLFact fact1,
                          XBRLFact fact2,
                          int aspectModel,
                          XMLFragment context)

Computes if two facts are aspect-matched input facts as defined in the Formula specification.

Parameters:

fact1 -

fact2 -

Returns:

getCacheFact

public XBRLFact getCacheFact(net.sf.saxon.s9api.XdmNode factNode)

Search for a fact using the fact node. This search traverses all in scope instance documents until one is found.

Parameters:

fact2 -

Returns:

getUnitById

public XBRLUnit getUnitById(java.lang.String id,
                            java.net.URI documentURI)

Parameters:

id -

documentURI -

Returns:

getElementById

public XMLFragment getElementById(java.lang.String id,
                                  java.net.URI documentURI)

Parameters:

id1 -

documentURI -

Returns:

getContextById

public XBRLContext getContextById(java.lang.String id,
                                  java.net.URI documentURI)

Parameters:

id -

documentURI -

Returns:

compileExpressionAndCollectRequiredVariables

public static net.sf.saxon.s9api.XPathExecutable compileExpressionAndCollectRequiredVariables(java.lang.String selectExpression,
                                                                                              java.util.Collection<javax.xml.namespace.QName> requiredVariables,
                                                                                              java.util.Collection<net.sf.saxon.s9api.QName> preDefinedVariables,
                                                                                              net.sf.saxon.om.NamespaceResolver nsResolver,
                                                                                              XBRLFormulaResource fragment)
                                                                                       throws XFValidationException

Parameters:

selectExpression -

requiredVariables -

Returns:

Throws:

XFValidationException

getStatus

public FormulaProcessorStatus getStatus()

Normally called from another thread, this method returns an instance of a FormulaProcessorStatus class that provides information about the number of formulas, number of assertions, number of consistency assertions. number of running threads, maximum time of a thread and what every thread is doing.

Returns:

FormulaProcessorStatus instance

setUnderEvaluationVariable

public void setUnderEvaluationVariable(javax.xml.namespace.QName variableName)

Parameters:

variableName -

getUnderEvaluationVariableName

public javax.xml.namespace.QName getUnderEvaluationVariableName()

During the evaluation of an XPath expression in order to set the value of a variable name, the variable name of the variable that is being evaluated can be obtained by a call to this method.

The method will return null if there are no variable being evaluated. extension functions may access this method in order to access to the variable resource use and examine filters as is the case of the relative filter.

Returns:

QName

setUnderEvaluationUncoveredAspectValue

public void setUnderEvaluationUncoveredAspectValue(HasUncoveredAspectValueResolver resolver)

Sets the value for the resolver of the xff:uncovered-aspect function.

Parameters:

xbrlConsistencyAssertion - an instance of a class implementing the HasUncoveredAspectValueResolver interface or null to unset the value

getUnderEvaluationUncoveredAspectValue

public HasUncoveredAspectValueResolver getUnderEvaluationUncoveredAspectValue()

Access to the value of the instance of the class that will resolve values for the xff:uncovered-aspect function.

Returns:

HasUncoveredAspectValueResolver

evaluate

public XBRLValidationReport evaluate(XBRLResource resource,
                                     XBRLInstance instance)

Evaluates one resource and returns an XBRLValidationReport instance. the parameter must be an already compiled XBRL formula resource of the following types: XBRLFormula, XBRLAssertion, XBRLConsistencyAssertion

This method is used by the GUI of the FormulaTT class.

Parameters:

resource -

Returns:

XBRLValidationReport

cleanFormulaExpression

public static java.lang.String cleanFormulaExpression(java.lang.String expression)

Helper function that cleans up the content of an XPath expression so it can be used as a text string in a GUI.

The method trims the expression and then replaces cr by spaces.

Parameters:

expression - string XPath expression

Returns:

String in a single line of text

getFilterOrderInstance

public XBRLFilterOrderTool getFilterOrderInstance()

The formula specification is not defining the order in which filters shall be arranged to create the XPath evaluation expression. Different orders may result in XPath evaluation expression errors.

Starting with version 2.8.1 it is possible to define other classes implementing the XBRLFilterOrderTool interface by providing the class name in the http://www.reportingstandard.com/FormulaProcessor/FilterOrderClass property. For convenience, that property is defined in the DTSContainer.FORMULA_PROCESSOR_FILTER_ORDER_CLASS constant.

Returns:

This method returns an instance of the class implementing the interface that provides a mechanism to define the order for filters. The default implementation of the interface is an instance of the XBRLFilterOrderTool class that is the first implementation that passes the entire formula conformance suite.

Since:

2.8.1