Community articleupdateXFormsValue method
Added by IBM contributorIBM on August 15, 2011
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars


Updates the value of an XForms instance data node. This method can modify existing data and build new pieces of instance data as necessary for the update.


   public boolean updateXFormsValue(
      String modelID,
      String instanceXPathExp,
      FormNodeP nsNode,
      int updateFlags
      String extensionPath
      String updateValue
   ) throws UWIException;


Table 1. Method parameters
modelIDStringThe ID of the model to update. If null or empty, the default model is updated.
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.
updateFlagsintSpecifies the behavior of the function. Must be one of the following values:
0 — Default behavior is performed. If the XForms processor is on, then updates are automatically implemented after a change is made to the data. See the "Notes" section below for details.
XFDL.UFL_XFORMS_DEFER MODEL_UPDATE — Marks the model for a deferred update. In a deferred update, the data model is not changed immediately; instead, the model is flagged to indicate that there are changes that need to be implemented. To enact a deferred update and implement the changes to the model, use the xFormsModelUpdate method.
XFDL.UFL_XFORMS_SUPPRESS_MODEL_UPDATE — Prevents any automatic updating of the model. See the "Notes" section below for usage details.
Note: You can only use the XFDL.UFL_XFORMS_DEFER MODEL_UPDATE and XFDL.UFL_XFORMS_SUPPRESS_MODEL_UPDATE flags when XForms processing is turned on.
extensionPathStringName of an element or attribute to be created. This new element or attribute is created as a child of the node that is specified by instanceXPathExp. Supported values include the name of the new child element and the @name of the new child attribute.
For example, entering Title as a value would create an element called "Title", while entering @Title would create an attribute called "Title".
updateValueStringThe value to set into the given node during the update process.


true if the update was successful, or false if it was not.


Default behavior of the method
When the updateFlags parameter is set to 0, updateXFormsValue performs its default behavior. This default behavior varies depending on how the form is loaded:
  • If the form is opened without using the readForm method, or the form is loaded using the readForm method but the flags parameter is set to 0, then updateXFormsValue automatically updates the data model each time that a change is made to the form.
  • If the form is loaded using the readForm method with the flags parameter set to XFDL.UFL_SERVER_SPEED_FLAGS_WITH_XFORMS or XFDL.UFL_XFORMS_INITIALIZE_ONLY, then updateXFormsValue marks the data model for a deferred update when a change is made to the form. To enact this update, use the xFormsModelUpdate method.
  • If the form is loaded using the readForm method with the flags parameter set to XFDL.UFL_SERVER_SPEED_FLAGS, then updateXFormsValue does not update the data model or mark the model for a later update. You cannot update the data model if XForms processing is turned off completely.
You can override these default behaviors by using the updateFlags parameter.
Suppressing updates to the model
Automatically updating the data model each time that a change is made to the form causes an unnecessary expenditure of computing resources. Each time that updateXFormsValue is called in an application, the method will check every node in the model for potential updates. Use the XFDL.UFL_XFORMS_SUPPRESS_MODEL_UPDATE flag to prevent unnecessary updating, and then call updateXFormsValue at the very end of the application to implement all of the model updates with one method call.


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");

Parent topic:
FormNodeP class