Community articleupdateXFormsInstance method (Streaming API)
Added by IBM contributorIBM on July 26, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Inserts data anywhere within the XForms instance data, or replaces it entirely. It automatically updates the XForms data model.

Description

Call this method on the root node of the form or an instance node.
Note: Use caution when calling this method. It can silently break a digital signature if signed instance data is modified.

Method

READING A FILE:
   public void updateXFormsInstance(
      String theModelID,
      String theNodeRef,
      FormNodeP theNSNode,
      String theFilename,
      byte[] theMemoryBlock,
      int updateType
      ) throws UWIException;

READING FROM A STREAM:
   public void updateXFormsInstance(
      String theModelID,
      String theNodeRef,
      FormNodeP theNSNode,
      java.io.InputStream theStream,
      int updateType
      ) throws UWIException;


READING FROM A READER:
   public void updateXFormsInstance(
      String theModelID,
      String theNodeRef,
      FormNodeP theNSNode,
      java.io.Reader theReader,
      int updateType
      ) throws UWIException;


Parameters

Table 1. Method parameters
ExpressionTypeDescription
theModelIDStringThe ID of the affected model. You must use null to use the default model.
theNodeRefStringAn XPath reference to the instance (or portion of an instance) you want to insert data into or replace. An empty string indicates the default instance of the selected model.
theNSNodeFormNodePA node that inherits the namespaces used in the reference. This node defines the namespaces for the method. Use null if the node that this method is operating on has inherited the necessary namespaces.
theFilenameStringThe file to read the instance data from. That this file must be UTF-8. Note that if both a file and a memory block are provided, the file will take precedence.
theStream java.io.InputStreamThe input stream that provides the data that replaces or adds to the XForms instance. Note that this data must be UTF-8.
theReader java.io.ReaderThe Java Reader that provides the data that replaces or adds to the XForms instance. Note that this data must be UTF-8.
theMemoryBlockbyte[]The memory block that contains the instance if you are not reading from a file, input stream, or Reader. Use null if theFilename is used.
updateTypeintOne of the following constants:
XFDL.UFL_XFORMS_UPDATE_REPLACE — Replaces the node that is referenced by theNodeRef with the data from theFilename, theStream, or theReader.
XFDL.UFL_XFORMS_UPDATE_APPEND — Adds the node that is supplied by theFilename, theStream, or theReader as the last child of the node that is referenced by theNodeRef.
XFDL.UFL_XFORMS_UPDATE_INSERT_ BEFORE — Adds the node that is supplied by theFilename, theStream, or theReader as a sibling of the node that is referenced by theNodeRef. You cannot insert before the top-level element of the instance.


Returns

Nothing. Throws a UWIException if an error occurs.

Notes

The updateXFormsInstance and the extractXFormsInstance methods are the only methods that are intended to modify the XForms data model.

Example

The following example shows a method that replaces an XForms instance.
Instance data:
   <xforms:instance id="instance1" xmlns="">
      <loanrecord>
         <user_personal_info>
            <firstname></firstname>
            <lastname></lastname>
            <middleinitial></middleinitial>
            <address>
               <street></street>
               <city></city>
               <state></state>
               <country></country>
               <postalcode></postalcode>
            </address>
         </user_personal_info>
      </loanrecord>
   </xforms:instance>


Method:
   private static void updateDataInstance(String theFileName)
   {
      theForm.updateXFormsInstance("model1", 
         "instance('instance1')/user_personal_info",
          null, "c:\\InstanceData.xml", null, XFDL.UFL_XFORMS_UPDATE_REPLACE);
   }


Parent topic:
FormNodeP class