Community articleupdateXFormsInstance method
Added by IBM contributorIBM | Edited by IBM contributorEric Dunn on August 17, 2012
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars





Description

Updates the XForms model by inserting, replacing, deleting, or appending data anywhere within the XForms instance data. Call this method on the root node of the form.

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
Expression Type Description
theModelID String The ID of the model to update. If null or empty, the default model is updated.
theNodeRef String An XPath reference to a node in the instance that you want to update. An empty string indicates the document node of the default instance of the selected model.
theNSNode FormNodeP This node defines the namespaces for the method. Use null if the node that this method is operating on has inherited the necessary namespaces.
theFilename String The file to read the instance data from. 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.InputStream The 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.Reader The Java Reader that provides the data that replaces or adds to the XForms instance. Note that this data must be UTF-8.
theMemoryBlock byte[] The memory block that contains the instance data. Use null if you are reading from a file, input stream, or Reader.
updateType int One of the following constants:

XFDL.UFL_XFORMS_UPDATE_REPLACE — Replaces the node that is referenced by theNodeRef with the input instance data.

XFDL.UFL_XFORMS_UPDATE_REPLACE_TEXT — Replaces the string value of the node that is referenced by theNodeRef with the input data.

XFDL.UFL_XFORMS_UPDATE_APPEND — Adds the input data as the last child node of the node that is referenced by theNodeRef.

XFDL.UFL_XFORMS_UPDATE_INSERT_ BEFORE — Adds the input data as a sibling before the node that is referenced by theNodeRef. You cannot insert data before the root element of the instance.

XFDL.UFL_XFORMS_UPDATE_DELETE — Deletes the node that is referenced by theNodeRef. You cannot delete the entire instance.

If used, the following flags must be used in conjunction with one of the updateType flags described above:

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.




Returns

Nothing. Throws a UWIException if an error occurs.


Usage details


Modifying the XForms data model

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

Default behavior of the method

When the updateFlags parameter is set to 0, updateXFormsInstance performs its default behavior. However, 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 updateXFormsInstance automatically updates the data model each time that a change is made to the model.
  • If the form is loaded using the method with the flags parameter set to XFDL.UFL_SERVER_SPEED_FLAGS_WITH_XFORMS or XFDL.UFL_XFORMS_INITIALIZE_ONLY, then updateXFormsInstance marks the data model for a later update when a change is made to the model. 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 updateXFormsInstance 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 updateXFormsInstance 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 updateXFormsInstance without using the XFDL.UFL_XFORMS_SUPPRESS_MODEL_UPDATE flag at the very end of the application to implement all of the model updates with one method call.


Example

The following example shows an XForms instance and a method that you can use to replace it.

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