Replace the child node refChild with newChild in the list of childs and returns the node refChild. If newChild is an object DocumentFragment, refChild is replaced for all the childs of DocumentFragment, which are inserted in the same order. If the newChild is already in the tree is deleted.

A child is a first-level descendant, if it is indicated a non first-level descendant, it will be generated the exception NOT_FOUND_ERR.

1 dom.node.replaceChild

<dom.node.replaceChild>
    <node /> !
    <newChild /> !
    <refChild /> !
</dom.node.replaceChild>

Returns

HIERARCHY_REQUEST_ERR

Appears if this node is of a type that not allow childs of the newChild node, if the type of the node to put is one of the ancestors of the node itself or the node itself, also if the node is of the Document type and the result of the substitution operation will add a second DocumentType or Element in the Document node.

WRONG_DOCUMENT_ERR

Appears if newChild has been created of a different document than the one created by this node.

NO_MODIFICATION_ALLOWED_ERR

Appears if the node is readonly or if the previous parent of the node being inserted is readonly.

NOT_FOUND_ERR

Appears if refChild is not a child of this node. A child is a first-level descendant.

NOT_SUPPORTED_ERR

If this node is of the type Document, this exception can appear if the DOM implementation does not suppourt the replace of the DocumentType child or Element child.

Remarks

If the node to be added does not belong to the document to which it belongs to the node in which it is to be added, is necessary to perform first an import of the node which will be added, to decontextualize it, it means, to unlink it of its owner document and in this way can use it in a different document. This operation should be performed when adding ( dom.node.insertBefore), replacing( dom.node.replaceChild) or inserting ( dom.node.insertBefore).

The function replaceChild replaces a node child of the indicated node. A node child is a first-level descendant. If it is not indicated a first-level descendant in the argument refChild it will be generated the exception NOT_FOUND_ERR.

Example

Replaces a node of a document with another node of a different document.

Copy 
<xsql-script name='dom_node_appendChild'>
    <body>
        <set name='root_ori'><dom.parse><file name='data1.xml' type='absolute' /></dom.parse></set>
        <set name='root_rpl'><dom.parse><file name='data2.xml' type='absolute' /></dom.parse></set>
        <!-- The node should be imported to unlink it of its                       -->
        <!-- owner document, and be able to use it in a new document.              -->
        <set name='node_rpl'>
            <dom.document.importNode>
                <root_ori/>
                <dom.node.getFirstChildElement><root_rpl/></dom.node.getFirstChildElement>
            </dom.document.importNode>
        </set>

        <!-- Replace the first element chiñd (first-level descendant) of the original   -->
        <!-- document with the node of the replacement document.                        -->
        <dom.node.replaceChild>
            <root_ori/>
            <node_rpl/>
            <dom.element.getFirstChildElement><root_ori /></dom.element.getFirstChildElement>
        </dom.node.replaceChild>
<!--
Retorna:

<xsql-script name="print">
    <HOLA>
        <test/>
        <string>HELLO ECHO</string>
    </HOLA>
</xsql-script>
-->
        <println>
            <root_ori/>
        </println>

    </body>
</xsql-script>
Example

Replace a node of a document using the function getElementByXPath.

Copy 
<xsql-script name='dom_node_replaceChild'>

    <body>
        <set name='root_ori'><dom.parse><file name='data1.xml' type='absolute' /></dom.parse></set>
        <set name='root_rpl'><dom.parse><file name='data2.xml' type='absolute' /></dom.parse></set>

        <!-- The node should be imported to unlink it of its                       -->
        <!-- owner document, and be able to use it in a new document.              -->
        <set name='node_rpl'>
            <dom.document.importNode>
                <root_ori/>
                <dom.node.getFirstChildElement><root_rpl/></dom.node.getFirstChildElement>
            </dom.document.importNode>
        </set>

        <!-- Replace the first element child (first-level descendant) of the original   -->
        <!-- document with the node of the replacement document. -->
        <dom.node.replaceChild>
            <root_ori/>
            <node_rpl/>
            <dom.element.getFirstChildElement><root_ori /></dom.element.getFirstChildElement>
        </dom.node.replaceChild>
<!--
Returns:


<xsql-script name="print">
    <HOLA>
        <test/>
        <string>HELLO ECHO</string>
    </HOLA>
</xsql-script>
-->
        <println>
            <root_ori/>
        </println>

    </body>
</xsql-script>

Replace the node document/body/s1[@title='Programación']/s2[@title='Árbol'] , it means, the first tag s2 by:

Copy 
<document>
    <element>hello</element>
    <element>world</element>
</document>

The function replaceChild replaces a node child. A node child is a first-level descendant, so it is not correct:

Copy 
<dom.node.replaceChild>
    <prv_data />
    <node_rpl_new />
    <dom.getElementByXPath xpath="#m_xpath"><prv_data /></dom.getElementByXPath>
</dom.node.replaceChild>

And generates the exception:

Copy 
org.w3c.dom.DOMException: NOT_FOUND_ERR:
        An attempt is made to reference a node in a context where it does not exist.

Sinche the node founded with dom.getElementByXPath is not a child of the document prv_data because it is not first-level descendant, it is a descendant but not of first-level. The correct form is:

Copy 
<dom.node.replaceChild>
    <dom.node.getParentNode><dom.getElementByXPath xpath="#m_xpath"><prv_data /></dom.getElementByXPath></dom.node.getParentNode>
    <node_rpl_new />
    <dom.getElementByXPath xpath="#m_xpath"><prv_data /></dom.getElementByXPath>
</dom.node.replaceChild>

Now the childRef is really a first-level descendant of the node of the node from which the substitution is made.