Back to Contents

The DomDocument class

Summary:

• Syntax
• Methods
• DomDocument Features
• Examples
  • Create a namespace qualifed XML document
  • Validating a document against XML schemas or an embedded DTD

See also: The Genero Web Services XML Extension Library

Syntax

The DomDocument class provides methods to manipulate a data tree, following the DOM standards.

The status is set to zero after a successful method call.

Syntax

Methods

• Creation
• Navigation
• Management
• Node creation
• Load and save
• Configuration
• Validation
• Error management

Creation methods

Usage

xml.domDocument.create()

Create a DomDocument without a root node.

xml.domDocument.create("ARoot")

Create a DomDocument with an initial root node named ARoot.

xml.domdocument.createDocumentNS("fjs","List","http://www.mysite.com/xmlapi")

Produces:
<fjs:List xmlns:fjs="http://www.mysite.com/xmlapi">
[...]
</fjs:List>

Create a DomDocument with an initial root node named List with fjs as the prefix and http://www.mysite.com/xmlapi as the namespace.

Back to the top

Navigation methods

Usage

DomDocument navigation functions deal with nodes immediately under the DomDocument object, except for search features. To navigate through all the nodes, you can refer to the navigation functions of  the class xml.DomNode.

<?xml version="1.0" encoding="ISO-8859-1"?><?xml-stylesheet type="text/xsl" href="card.xsl"?><!-- demo card --><CardList xml:id="1" >[...]</CardList>

The first node of the document is xml-stylesheet. Use getFirstDocumentNode to get the node.
The element at position 2 is the comment <!-- demo card -->. Use getDocumentNodeItem function to get the node.
The last node of the document is CardList. Use getLastDocumentNode to get the node.
The number of node of the document is 3. This is result of function getDocumentNodesCount. This function only count the number of children immediately under the DomDocument.
Note that the first line of the example, <?xml version="1.0" encoding="ISO-8859-1"?>, is not considered as a node. To access to the information of the first line, use getXmlVersion and getXmlEncoding functions.
Caution, if the example is in pretty printed format, the results are not the same. There are addition text nodes representing the carriage returns.

<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="card.xsl"?>
<!-- demo card -->
<CardList xml:id="1" >
[...]
</CardList>

See Cautions section for more details.

You can select nodes using their tag names, by XPath, or by their attributes value (if of type ID, xml:id for example). The getElementsbyTagName and getElementsbyTagNameNS methods return a DomNodeList object, unlike the other methods that return a DomNode object. The DomNodeList is restricted to contain objects with the same tag name and/or namespace. The selectByXPath method also returns a DomNodeList object, but each node can have a different name.

getElementsByTagNameNS("message","http://schemas.xmlsoap.org/wsdl/")

Get the message nodes that have http://schemas.xmlsoap.org/wsdl/ as the namespace.

getElementsByTagNameNS("message","*")

Get all the message nodes, regardless of the namespace they have.

getElementsByTagName("message")

Get all the message nodes that do not have any namespace.

selectByXPath("//xs:element", NULL)

Get all the xs:element nodes that has a namespace corresponding to prefix xs.

selectByXPath("//Card", NULL)

Get all the Card nodes that do not have any namespace.

getElementById("1")

Get the unique node whose attribute of type ID has a value of "1".

Back to the top

Management methods

Back to the top

Node creation methods

Usage

Creating a node for the DomDocument are done in two steps:

• create the node
• add the node to the DomDocument

Each time you create a node you need to append it at the right place in the DomDocument. To add a node the document use the DomDocument management methods or the DomNode manipulation methods.

createNode("<LastName>PATTERSON</LastName><FirstName>Andrew</FirstName>")

Creates a structure of nodes.

createElement("CardList")

Produces
<CardList>

createElementNS("cny","Company","http://www.mysite.com/")

Produces
<cny:Company xmlns:cny="http://www.mysite.com/" /> or <cny:Company />. See Cautions for more details.

createAttribute("Country")

Creates a Country attribute node.
To set a value to the attribute use the method setNodeValue of the xml.DomNomde class. To add the attribute to an element node use the method setAttributeNode of the xml.DomNode class.

createAttributeNS("tw","Town","http://www.mysite.com/cities")

Produces
xmlns:tw="http://www.mysite.com/cities" tw:Town=""
To set a value to the attribute use the method setNodeValue of the xml.DomNomde class. To add the attribute to an element node use the method setAttributeNodeNS of the xml.DomNode class. For optimization reasons, the namespace is not written aside the attribute until the saving of the DomDocument. When accessing the element node, the namespace is not listed in the list of children. In the example above, tw:Town="" is in the list of children not xmlns:tw="http://www.mysite.com/cities". To access the namespace during the DomDocument building use the method normalize first. Normalize write the namespace declaration at the appropriate place. If there is no previous declaration, it will be accessible as an attribute of this element otherwise it will be an attribute of one of the ancestors of the element.

createTextNode("My Company")

Creates a text node.

createComment("End of the card")

Produces
<!--End of the card-->

createCDATASection("<website><a href=\"www.mysite.com\">My Company</a></website>")

Produces
<![CDATA[<website><a href="www.mysite.com">My Company</a></website>]]>

createEntityReference("title")

Creates the entity reference &title.

createProcessingInstruction("xml-stylesheet","type=\"text/xsl\" href=\"card.xsl\"")

Produces
<?xml-stylesheet type="text/xsl" href="card.xsl"?>

createDocumentType("Card",NULL,NULL,"<!ELEMENT Card (lastname,firstname,company,location)>")

Produces
<!DOCTYPE Card [ <!ELEMENT Card (lastname , firstname , company , location)>]>
Only inline DTD are supported. The DTD has to been inserted in the DomDocument at an appropriate place.

createDocumentFragment

Is a method that creates a lighweight DomDocument. It represents a sub-tree of nodes that do not need to conform to well-formed XML rules. This makes DocumentFragment easier to manipulate than a DomDocument.

for i=1 to 5
  let node = doc.createelement("Card")
  call root.appendchild(node)
end for

This produces a sub-tree with 5 Card nodes that do not have any root node. Once the sub-tree is completed, it can be added to the DomDocument object like any other node.

Back to the top

Load and save methods

Usage

You can load an existing xml document. Before loading an xml document you need to create the DomDocument object.

A DomDocument can load files using different URI: http://, https://, tcp://, tcps://, file:// and alias://. Use getErrorsCount() and getErrorDescription() to display errors about the document loading.

load("data.xml")
load("http://www.w3schools.com/xml/cd_catalog.xml")
load("https://localhost:6394/ws/r/calculator?WSDL")
load("file:///data/cd_catalog.xml")
load("tcp://localhost:4242/")
load("tcps://localhost:4243/")
load("alias://demo")
where demo alias is defined in fglprofile as ws.demo.url = "http://www.w3schools.com/xml/cd_catalog.xml"

loadfromstring("<List><elt>First element</elt><elt>Second element</elt><elt>Third element</elt></List>")

Produces a sub-tree with a root node List and three nodes elt and three textnode.

A DomDocument can be saved at different URI begining with: http://, https://, tcp://, tcps://, file:// and alias://. Use getErrorsCount() and getErrorDescription() to display errors about the document saving.

save("myfile.xml")
save("http://myserver:8080/data/save1.xml")
save("file:///data/save.xml")
save("tcp://localhost:4242/")
save("alias://test")
where test alias is defined in fglprofile as ws.test.url = "http://localhost:8080/data/save3.xml"

saveToString saves the DomDocument in a string. Use getErrorsCount() and getErrorDescription()to display errors about the document saving

normalize function emulates a DomDocument save and load. It can be called at any stage of the DomDocument building. This removes empty Text nodes and sets namespace declarations as if the document had been saved.

Back to the top

Configuration methods

Back to the top

Validation methods

Back to the top

Error management methods

Usage

for i=1 to doc.getErrorsCount()
  display "[", i, "] ", doc.getErrorDescription(i)
end for

Displays all the errors encountered in the save, load or validate of doc DomDocument.

To display other errors, use the global variable status to get the error code and err_get(status) or sqlca.sqlerrm to get the description of the error. See error code for more details.

Back to the top

Cautions

Whitespaces, line feeds and carriage returns between elements are represented as text nodes in memory. An XML document written in a single line and a human readable (pretty printed format) do not have the same representation in the DomDocument. Take this under account when navigating in the document.

If a DomNode is not attached to a DomDocument and not referenced by any variable it can be destroyed. If one child of this node is still referenced, this child is not destroyed but its parent and the others node of the sub-tree are destroyed. To check if a node is attached to a DomDocument use isAttached method.

DomDocument remains in memory if any of its node is still referenced in a variable.

Back to the top

DomDocument Features

Examples

Example 1 : Create a namespace qualified document with processing instructions

   <?Target1 This is my first PI ?>
   <MyPre:RootNode xmlns:MyPre="http://www.tempuri.org" >
     <MyPre:Element />
   </MyPre:RootNode>
   <?Target2 This is my last PI ?>
    

    IMPORT xml
    
    MAIN 
      DEFINE doc      xml.DomDocument
      DEFINE pi       xml.DomNode
      DEFINE node     xml.DomNode
      DEFINE elt      xml.DomNode
    

      # Create a document with an initial namespace qualified root node
      LET doc = xml.DomDocument.CreateNS("MyPre","RootNode","http://www.tempuri.org") 
      # Create a Processing instruction
      LET pi = doc.createProcessingInstruction("Target1,"This is my first PI")
      # And add it at the begining of the document
      CALL doc.prependDocumentNode(pi)
      # Create another Processing instruction
      LET pi = doc.createProcessingInstruction("Target2,"This is my last PI")
      # And add it at the end of the document
      CALL doc.appendDocumentNode(pi)
      # Retrieve initial root node of the document
      LET elt = doc.getDocumentElement()     
      # Create a new Element node
      LET node = doc.createElement("MyPre","Element","http://www.tempuri.org") 
      # And add it as child of the RootNode    
      CALL elt.appendChild(node)
      # Then save the document on disk
      CALL doc.save("MyFile.xml")
    END MAIN
    

Example 2 : Validating a document against XML schemas or a DTD

    
    IMPORT xml
    
    MAIN    
        DEFINE location STRING
        DEFINE xmlfile  STRING
        DEFINE doc      xml.DomDocument
        DEFINE ind      INTEGER
       
        IF num_args()<2 THEN
          # Checks the number of arguments
          CALL ExitHelp()  
        ELSE
          LET doc = xml.DomDocument.Create()
          LET xmlfile = arg_val(num_args())
          IF num_args() == 2 AND arg_val(1) == "-dtd" THEN
            # User choosed DTD validation
            CALL doc.setFeature("validation-type","DTD")
          ELSE    
            # User choosed XML Schema validation
            IF arg_val(1) == "-ns" THEN
              # Handle namespace qualified XML schemas
              IF num_args() MOD 2 != 0 THEN
                CALL ExitHelp()
              END IF
              FOR ind = 2 TO num_args()-1 STEP 2
                IF location IS NULL THEN
                  LET location = arg_val(ind) || " " || arg_val(ind+1)
                ELSE
                  LET location = location || " " || arg_val(ind) || " " || arg_val(ind+1)
                END IF
              END FOR
              TRY
                CALL doc.setFeature("external-schemaLocation",location)
              CATCH
                FOR ind = 1 TO doc.getErrorsCount()
                    DISPLAY "Schema error ("||ind||") :",doc.getErrorDescription(ind)
                END FOR          
                EXIT PROGRAM (-1)
              END TRY
            ELSE
              # Handle unqualified XML schemas
              FOR ind = 1 TO num_args()-1 
                IF location IS NULL THEN
                  LET location = arg_val(ind)
                ELSE
                  LET location = location || " " || arg_val(ind)
                END IF
              END FOR
              TRY
                CALL doc.setFeature("external-noNamespaceSchemaLocation",location)
              CATCH
                FOR ind = 1 TO doc.getErrorsCount()
                  DISPLAY "Schema error ("||ind||") :",doc.getErrorDescription(ind)
                END FOR          
                EXIT PROGRAM (-1)
              END TRY
            END IF
          END IF
        END IF
        TRY
          # Load XML document from disk
          CALL doc.load(xmlfile)
        CATCH
          # Display errors if loading failed
          IF doc.getErrorsCount()>0 THEN
            FOR ind = 1 TO doc.getErrorsCount()
              DISPLAY "LOADING ERROR #"||ind||" :",doc.getErrorDescription(ind)
            END FOR
            EXIT PROGRAM(-1)
          ELSE
            DISPLAY "Unable to load file :",xmlfile
            EXIT PROGRAM(-1)
          END IF
        END TRY
        TRY
          # Validate loaded document 
          LET ind = doc.validate()
          IF ind == 0 THEN
            # Successful validation
            DISPLAY "OK"
          ELSE
            # Display validation errors
            FOR ind = 1 TO doc.getErrorsCount()
              DISPLAY "VALIDATING ERROR #"||ind||" :",doc.getErrorDescription(ind)
            END FOR
            EXIT PROGRAM(-1)
          END IF    
        CATCH
          DISPLAY "Unable to validate file :",xmlfile
          EXIT PROGRAM(-1)
        END TRY      
      END MAIN
    
      # Display help
      FUNCTION ExitHelp()
        DISPLAY "Validator < -dtd | -ns [namespace schema]+ | [schema]+ > xmlfile"
        EXIT PROGRAM
      END FUNCTION
    

Back to the top