Community articleextractInstance method (Streaming API)
Added by IBM contributorIBM on August 16, 2011
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 instance from a form's XML model to a file. Note that this method does not remove the instance from the form.
Call this method on the root node of the form or an XML instance node.

Method

WRITING TO A FILE:
   public void extractInstance(
      String theInstanceID,
      FormNodeP theFilter,
      String includedNamespaces,
      String theFile,
      int theFlags,
      String theScheme,
      String theRootReference,
      FormNodeP theNSNode
      ) throws UWIException;


WRITING TO A STREAM:
   public void extractInstance(
      String theInstanceID,
      FormNodeP theFilter,
      String includedNamespaces,
      java.io.OutputStream theStream,
      int theFlags,
      String theScheme,
      String theRootReference,
      FormNodeP theNSNode
      ) throws UWIException;
	  


WRITING TO A WRITER:
   public void extractInstance(
      String theInstanceID,
      FormNodeP theFilter,
      String includedNamespaces,
      java.io.Writer theWriter,
      int theFlags,
      String theScheme,
      String theRootReference,
      FormNodeP theNSNode
      ) throws UWIException;


Parameters

Table 1. Method parameters
ExpressionTypeDescription
theInstanceIDStringThe ID of the instance node to extract. This is defined by the id attribute of that node.
To extract the root node of the form, set this parameter to null.
theFilterFormNodePThis parameter must be null. This version of the API does not allow filtering.
includedNamespacesString If set to null, a definition for each inherited namespace is added to the root node of the instance when it is extracted.
To filter the namespaces, list the prefixes for those namespaces you want to include in the instance, separated by spaces.
For example, to include only the xfdl and custom namespaces, set this parameter to:
   xfdl custom


Use #default to indicate the default namespace for the instance.
Use an empty string ("") to include only those namespaces that are used by the instance.
Namespaces that are used in the instance re always included, regardless of this setting.
theFileStringThe path to the file on the local drive that will contain the XML instance.
theStream java.io.OutputStreamThe output stream that will write the data instance. Note that the data must be UTF-8.
theWriter java.io.WriterThe Java Writer that will write the data instance.
theFlagsintReserved. This must be 0.
theSchemeStringReserved. Must be null.
theRootReferenceStringA reference to the node you want to extract. This reference is relative to the instance node.
Use null to default to the instance node.
theNSNodeFormNodePA node that inherits the namespaces used in the reference. It defines the namespaces for the method. Use null if the node that this method is operating on has inherited the necessary namespaces.


Returns

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

Example

The following example shows a method that takes the root node of a form and extracts an XML instance.
   private static void updateDataInstance(formNodeP theForm)
   {
      theForm.extractInstance("data", null, null,
         "c:\Instance Files\Personnel\tempdata.dat", 0, null, null, null);
   }


Parent topic:
FormNodeP class