Back to Contents

The XmlReader class

Summary:

See also: Built-in Classes, XML Utils

Basics

Purpose:

The XmlReader class provides methods to read and process a file written in XML format, following the SAX standards.

Syntax:

om.XmlReader

Methods:

Class Methods
Name Description
createFileReader( file STRING )
  RETURNING om.XmlReader		 Creates an XmlReader reading from a file.
Object Methods
Name Description
getAttributes( )
  RETURNING om.SaxAttributes		 Returns the attribute list of the current element. 
getCharacters( )
  RETURNING STRING		 Returns the string value of the current text element.
getTagName( )
  RETURNING STRING		 Returns the tag name of the current element.
read( )
  RETURNING STRING		 Reads the next XML fragment and returns the name of the SAX event that occurs. This can be one of StartDocument, StartElement, Characters, EndElement, EndDocument.

Usage:

The processing of the XML file is streamed-data based; the file is loaded and processed sequentially with events. To process element attributes, an XmlReader object must cooperate with a SaxAttributes object. The XmlReader class can only read from a file. To write to a file, you must use the XmlWriter class.

First, you must declare a variable of type om.XmlReader, and use the XmlReader.createFileReader(filename) method to create the object; where filename is a string expression defining the name of the file to be read.

As with the standard SAX API, the XML file is parsed on the basis of events. Once the XmlReader object is created with the XmlReader.createFileReader() method, you can successively call the XmlReader.read() method to get named events indicating how to parse the XML file.

The following events can be returned by the XmlReader.read()method:

Event name Description Action
StartDocument Beginning of the document Prepare processing (allocate resources)
StartElement Beginning of a node Get current element's tagname or attributes
XmlReader.getTagName()
XmlReader.getAttributes()
Characters Value of the current element Get current element's value
XmlReader.getCharacters()
EndElement Ending of a node Get current element's tagname
XmlReader.getTagName()
EndDocument Ending of the document Finish processing (release  resources)

To process element attributes, you must declare a variable of type SaxAttributes. This object represents a set of attributes of an element. You get an object of this class with the XmlReader.getAttributes() method. Once created from the XmlReader, the SaxAttributes object is automatically updated based on the element currently processed by the XmlReader.

Examples

Example:

01 MAIN
02    DEFINE i, l INTEGER
03    DEFINE r om.XmlReader
04    DEFINE e String
05    DEFINE a om.SaxAttributes
06    LET r = om.XmlReader.createFileReader("myfile.xml")
07    LET a = r.getAttributes()
08    LET l = 0
09    LET e = r.read()
10    WHILE e IS NOT NULL
11      CASE e
12        WHEN "StartDocument"
13          DISPLAY "StartDocument:"
14        WHEN "StartElement"
15          LET l=l+1
16          DISPLAY l SPACES, "StartElement:", r.getTagName()
17          FOR i=1 to a.getLength()
18            DISPLAY l SPACES,"  ",
19              a.getName(i)," = ",
20              a.getValueByIndex(i)
21          END FOR
22        WHEN "Characters"
23          DISPLAY l SPACES, "  Characters:'",r.getCharacters(),"'"
24        WHEN "EndElement"
25          DISPLAY l SPACES, "EndElement:", r.getTagName()
26          LET l=l-1
27        WHEN "EndDocument"
28          DISPLAY "EndDocument:"
29        OTHERWISE
30          DISPLAY "Invalid event: ",e
31      END CASE
32      LET e=r.read()
33    END WHILE
34 END MAIN