Community articleextractXFormsValue method
Added by IBM contributorIBM on May 2, 2012
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars




Description

Resolves the given XPath expression over the XForms instance data, and returns its string value.
This method can quickly run complex XPath queries over an entire XForms data model and extract data from data nodes. For example, in a single method call, extractXFormsValue can extract data from all of the nodes that are traversed by the XPath expression and then return the data as a concatenated string.

Method

   public String extractXFormsValue(
      String modelID,
      String instanceXPathExp,
      FormNodeP nsNode,
      int extractFlags
      BooleanHolder completed
   ) throws UWIException;


Parameters

Table 1. Method parameters
ExpressionTypeDescription
modelIDStringThe ID of the model to analyze. If null or empty, the default model is analyzed.
instanceXPathExpStringThe XPath expression to resolve. If null or empty, then the current context node is assumed.
nsNodeFormNodePThe namespace context for the XPath resolution. If null, then this parameter will default to the FormNodeP object that this function is being called on.
extractFlagsintSpecifies the behavior of the function. Must be one of the following values:
0 — Default behavior is performed. The method analyzes all nodes as specified by the other parameters.
XFDL.UFL_XFORMS_EXTRACT_RESPECT_RELEVANCE — Function stops and returns null if instanceXPathExp produces a node that is not relevant. For information about relevance in the context of XForms, go to Extensible Forms Description Language XFDL 8.0 -> XFDL Overview -> Structure of XFDL forms -> Overview of XForms model syntax.
XFDL.UFL_XFORMS_EXTRACT_RESPECT_VALIDITY — Function stops and returns null if instanceXPathExp produces a node that is not valid. For information about validity in the context of XForms, go to Extensible Forms Description Language XFDL 8.0 -> XFDL Overview -> Structure of XFDL forms -> Overview of XForms model syntax.
Note: Relevance and validity will only be respected if the XPath resolution produces an instance node. But if a node is not produced, the operation will still be completed successfully.
completedBooleanHolderReturns true if the specified value is successfully extracted, or false if it is not.


Returns

The string value of the given XForms instance data.

Notes

You do not need XForms processing to be turned on in order to use this method. However, if XForms processing is turned off:
  1. You cannot use the XFDL.UFL_XFORMS_EXTRACT_RESPECT_RELEVANCE and XFDL.UFL_XFORMS_EXTRACT_RESPECT_VALIDITY flags.
  2. instanceXPathExp must be an absolute XPath expression. Without XForms processing, the current FormNodeP object cannot provide an XPath resolution context that differs from that of the default context node.
If the XForms processor is fully loaded and the current FormNodeP object is an XFDL item, then the current object provides the “run-time” XPath resolution context, which allows relative XPath expressions to be resolved.

Example

The following example shows code from a "shopping cart" application (such as one that might be used for online shopping). The extractXFormsValue method is used to check if the sum of all the values in the shoppingCart element is greater than $100, and if the shipping address of the buyer is located in the continental US. If these conditions are met (the completed parameter returns true), then updateXFormsValue creates an insurance element as a child of the shipping data node, and xFormsModelUpdate updates all of the form data as necessary.
    BooleanHolder completed = new BooleanHolder();
    String pathToForm= "example.xfdl";
    // load form with server-speed + XForms flags
    FormNodeP theForm = this.theXFDL.readForm(pathToForm, XFDL.UFL_SERVER_SPEED_FLAGS_WITH_XFORMS);
    String result = theForm.extractXFormsValue(null, "sum(shoppingCart/line [@toShip]/lineTotal) > 100.0 and address/US/state != 'AK' and address/US/state != 'HI'", null, 0, completed);
    if (completed.value == true && result.equals("true"))
    {
        theForm.updateXFormsValue(null, "instance('shipping')/insurance", null, 0, "@cost", "0.00");
        theForm.xFormsModelUpdate(null);
    }


Parent topic:
FormNodeP class