Community articleextractXFormsInstance method
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

Description

This method copies an entire XForms instance or a portion of an XForms instance to a file or a memory block. This method does not remove the instance from the form.
Call this method on the root node of the form or an instance node.

Method

WRITING TO A FILE:
   public void extractXFormsInstance(
      String theModelID,
      String theNodeRef,
      boolean writeRelevant,
      boolean ignoreFailures,
      FormNodeP theNSNode,
      String theFilename
   ) throws UWIException;

WRITING TO A STREAM:
   public void extractXFormsInstance(
      String theModelID,
      String theNodeRef,
      boolean writeRelevant,
      boolean ignorefailures,
      FormNodeP theNSNode,
      java.io.OutputStream theStream
   ) throws UWIException;

WRITING TO A WRITER:
   public void extractXFormsInstance(
      String theModelID,
      String theNodeRef,
      boolean writeRelevant,
      boolean ignorefailures,
      FormNodeP theNSNode,
      java.io.Writer theWriter
   ) throws UWIException;


Parameters

Table 1. Method parameters
ExpressionTypeDescription
theModelIDStringThe ID of the model to extract. Use null to extract the default model.
theNodeRefStringAn XPath reference to a node in the instance. This node and all of its children are copied. Leave blank to extract the entire instance.
writeRelevantbooleanIf true, writes only relevant instance data, else use false.
ignoreFailuresbooleanIf true, ignores constraint or validation failures, else use false.
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 name and path of the file to write to. Use null to write to the output memory block.
theStream java.io.OutputStreamThe output stream that will write the XForms data instance. Note that the data must be UTF-8.
theWriter java.io.WriterThe Java Writer that will write the XForms data instance.


Returns

Nothing if call is successful or throws a generic exception (UWIException) if an error occurs.

Usage details

XForms data model
The updateXFormsInstance and the extractXFormsInstance methods are the only methods that are intended to modify the XForms data model.
Using extractXFormsInstance with readForm
If a form is read with XForms processing off, you must set the writeRelevant parameter to false and the ignoreFailures parameter to true.

Example

The following example shows an XForms instance and a method that takes the root node of a form, extracts an XForms instance, and writes it to a file called "InstanceData.xml".
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(java.io.Writer theWriter)
   {
      theForm.extractXFormsInstance("model1", 
         "instance('instance1')/user_personal_info", false, true, null,
          "c:\\InstanceData.xml");
   }


Parent topic:
FormNodeP class