Modification Methods

Modification Methods
Prev	Appendix A. Updating Documents with XmlModify	Next

XmlModify provides a series of methods that you use to identify how a document is to be modified. To define your document modification, you call these methods as many times as is required. When XmlModify::execute() is called, the documents are modified according to the instructions provided in the order that they were provided.

The XmlModify modification methods are:

XmlModify::addAppendStep()

Appends the provided content to the targeted node's content.

If you are appending an element node, then the new node is by default appended immediately after the targeted node's last child node. Note, however, that this method provides a location parameter that identifies the index of the child node at which the append operation is to be performed. Note also that if the location parameter is specified, then the new node is inserted immediately prior to the identified child node.

For example, consider the following document:

<a>
   <b1>first child</b1>
   <b2>second child</b2>
   <b3>third child</b3>
</a>

For this document, if you:

Provide an XQuery selection expression of:
```
/a
```
Indicate you are inserting an element node.
Provide a name of "b4".
Provide "my inserted child".
Leave the location parameter blank.

Then when the modification is executed against the document, the resulting document is:

<a>
   <b1>first child</b1>
   <b2>second child</b2>
   <b3>third child</b3>
   <b4>my inserted child</b4>
</a>

However, if you give the location parameter a value of "0" (modify at the first child node), then the resulting document is:

<a>
   <b4>my inserted child</b4>
   <b1>first child</b1>
   <b2>second child</b2>
   <b3>third child</b3>
</a>

If you indicate that the type of information to be inserted is an attribute node, then the location parameter is always ignored and the new attribute is inserted at the node selected by the selection expression. So for a selection expression of

/a

The resulting document is:

<a  b4="my inserted child">
   <b1>first child</b1>
   <b2>second child</b2>
   <b3>third child</b3>
</a>

If you indicate that the type of information to be inserted is a comment node, and you leave the location parameter blank, then the resulting document is:

<a>
   <b1>first child</b1>
   <b2>second child</b2>
   <b3>third child</b3>
<!-- my inserted child -->
</a>

If you indicate a location of 0, then the resulting document is:

<a>
<!-- my inserted child -->
   <b1>first child</b1>
   <b2>second child</b2>
   <b3>third child</b3>
</a>

And finally, if you are inserting a text node with no location parameter, the resulting document is:

<a>
   <b1>first child</b1>
   <b2>second child</b2>
   <b3>third childmy inserted child</b3>
</a>

Note that the selection expression you provide here must not select an attribute node or an exception is thrown when the modification is executed.

XmlModify::addInsertAfterStep()

Inserts the identified content after the selected node. Note that the node that you target for this operation cannot select the document root node or an attribute node, or an exception is thrown.

If you are inserting an element node, then the new node is inserted after the closing tag of the targeted node.

For example, consider the following document:

<a>
   <b>
     text node
   </b>
</a>

For this document, if you:

Provide an XQuery selection expression of:
```
/a/b
```
Indicate you are inserting an element node.
Provide a name of "b2".
Provide "my inserted node".

Then when the modification is executed against the document, the resulting document is:

<a>
   <b>
     text node
   </b>
<b2>my inserted node</b2>
</a>

If you are inserting an attribute, then the new attribute is placed on the selected node's parent node. So for this example, the resulting document would be:

<a b2="my inserted node">
   <b>
     text node
   </b>
</a>

XmlModify::addInsertBeforeStep()

Identical to XmlModify::addInsertAfterStep() , except that element nodes, text, comments, and processing instructions are inserted prior to the node selected by the selection expression.

Again, you cannot select the root node or an attribute node or an exception is thrown when this instruction is executed.

For example, consider the following document:

<a>
   <b>
     text node
   </b>
</a>

For this document, if you:

Provide an XQuery selection expression of:
```
/a/b
```
Indicate you are inserting an element node.
Provide a name of "b2".
Provide "my inserted node".

Then when the modification is executed against the document, the resulting document is:

<a>
<b2>my inserted node</b2>
   <b>
     text node
   </b>
</a>

Attribute insertion is handled identically to XmlModify::addInsertAfterStep(). If you are inserting an attribute, then the new attribute is placed on the selected node's parent node. So for this example, the resulting document would be:

<a b2="my inserted node">
   <b>
     text node
   </b>
</a>

XmlModify::addRemoveStep()

Removes the node targeted by the selection expression. For example, if you have the following document:

<a>
   <b>
     <c>
        text node
     </c>
   </b>
</a>

and you provide a selection expression of:

/a/b/c

then the resulting document is:

<a>
   </b>
</a>

Similarly, if you have the following document:

<a>
   <b>
     <c attr1="foo">
        text node
     </c>
   </b>
</a>

and you provide a selection expression of:

/a/b/c/@attr1

then the resulting document is:

<a>
   <b>
     <c>
        text node
     </c>
   </b>
</a>

Again, it is an error to target the document's root node with this method.

XmlModify::addRenameStep()

This method renames the selected node. For example, if you have the following document:

<a>
   <b>
     <c attr1="foo">
        text node
     </c>
   </b>
</a>

and you provide a selection expression of:

/a

and you provide a new name of 'z', then the resulting document is:

<z>
   <b>
     <c attr1="foo">
        text node
     </c>
   </b>
</z>

Similarly, a selection expression of:

/a/b/c/@attr1

and a new name of 'z' leaves you with:

<a>
   <b>
     <c z="foo">
        text node
     </c>
   </b>
</a>

XmlModify::addUpdateStep()

This method updates (replaces) the contents of the targeted node with new content. If an element node is targeted, the content here is expected to be a text node. For example, given the following document:

<a>
   <b>
     <c attr1="foo">
        text node
     </c>
   </b>
</a>

providing a selection expression of:

/a

and replacement content:

Update content

Then the resulting document is:

<a>
Update content
</a>

If, however, you provide replacement content of:

<z>Update content</z>

(which includes the reserved characters '<' and '>'), then the method translates this into content that is appropriate for a text node. In this case, the resulting document is:

<a>
&lt;z>Update content&lt;/z>
</a>

Similarly, providing a selection expression of:

/a/b/c/@attr1

and replacement content:

Update content

results in the following document:

<a>
   <b>
     <c attr1="Update content">
        text node
     </c>
   </b>
</a>