The StaxReader class

Summary:

Syntax
Methods
Examples

Syntax

The StaxReader class provides methods compatible with StAX (Streaming API for XML), for reading XML documents. Notice that status is set to zero after a successful method call.

Syntax:

xml.StaxReader

Methods:

Creation
Configuration
Input
Access
Document
Nodes
Processing Instructions
Attributes
Namespaces
Navigation

Creation Methods

Class Methods
Name	Description
`xml.StaxReader.Create() RETURNING xml.StaxReader`	Constructor of a StaxReader object; returns the object.

Back to the top

Configuration Methods

Object Methods
Name	Description
`setFeature( feature STRING, value STRING )`	Sets a feature of a StaxReader object, where feature is the name of a feature, and value is the value of the feature. The features can be changed at any time, but will only be taken into account at the beginning of a new stream (see `readFrom` or `readFromDocument`). Throws an exception in case of errors, and updates status with an error code.
`getFeature( feature STRING ) RETURNING STRING`	Gets a feature of a StaxReader object; where feature is the name of a feature. Returns the feature value. Status is updated with an error code.

Back to the top

Input Methods

Object Methods
Name	Description
`readFrom( url STRING)`	Sets the input stream of the StaxReader object to a file or an URL, and starts the streaming; url is a valid URL or the name of the file to read. Throws an exception in case of errors, and updates status with an error code. Note: Only the following kinds of URLs are supported: http://, https://, tcp://, tcps://, file:/// and alias://. See FGLPROFILE Configuration for more details about URL mapping with aliases, and for proxy and security configuration.
`readFromDocument( doc xml.DomDocument )`	Sets the input stream of the StaxReader object to a DomDocument object, and starts the streaming; doc is an xml.DomDocument object that contains an XML document. Raises a 4GL exception in case of errors, and updates status with an error code.
`close()`	Closes the StaxReader streaming, and releases all associated resources.

Back to the top

Access Methods

Object Methods
Name	Description
`getEventType() RETURNING STRING`	Returns a string that indicates the type of event the cursor of the StaxReader object is pointing to. Status is updated with an error code.
`hasName() RETURNING INTEGER`	Checks whether the StaxReader cursor points to a node with a name. Returns TRUE if the current XML node has a name, FALSE otherwise. This method returns TRUE for START_ELEMENT and END_ELEMENT, FALSE for all other nodes. Throws an exception in case of errors, and updates status with an error code.
`hasText() RETURNING INTEGER`	Checks whether the StaxReader cursor points to a node with a text value. Returns TRUE if the current XML node has a text value, FALSE otherwise. This method returns TRUE for CHARACTERS, SPACE, CDATA, COMMENT, ENTITY_REFERENCE and DTD, FALSE for all other nodes. Throws an exception in case of errors, and updates status with an error code.
`isEmptyElement() RETURNING INTEGER`	Checks whether the StaxReader cursor points to an empty element node. Returns TRUE if the current XML element node has no children, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.
`isStartElement() RETURNING INTEGER`	Checks whether the StaxReader cursor points to a start element node. Returns TRUE if the current XML node is a start element node, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.
`isEndElement() RETURNING INTEGER`	Checks whether the StaxReader cursor points to an end element node. Returns TRUE if the current XML node is an end element node, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.
`isCharacters() RETURNING INTEGER`	Checks whether the StaxReader cursor points to a character node. Returns TRUE if the current XML node is a character node, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.
`isIgnorableWhitespace() RETURNING INTEGER`	Checks whether the StaxReader cursor points to ignorable whitespace. Returns TRUE if the current XML node is an ignorable character node, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Document Methods

Object Methods
Name	Description
`getEncoding() RETURNING STRING`	Returns the document encoding defined in the XML Document declaration, or NULL. Throws an exception in case of errors, and updates status with an error code.
`getVersion() RETURNING STRING`	Returns the document version defined in the XML Document declaration, or NULL. Throws an exception in case of errors, and updates status with an error code.
`isStandalone() RETURNING STRING`	Checks whether the document standalone attribute defined in the XML Document declaration is set to yes. Returns TRUE if the standalone attribute in the XML declaration is set to yes, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.
`standaloneSet() RETURNING STRING`	Checks whether the document standalone attribute is defined in the XML Document declaration. Returns TRUE if the standalone attribute in the XML declaration is set, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Nodes Methods

Object Methods
Name	Description
`getPrefix() RETURNING STRING`	Returns the prefix of the current XML node, or NULL. Throws an exception in case of errors, and updates status with an error code.
`getLocalName() RETURNING STRING`	Returns the local name of the current XML node, or NULL. Throws an exception in case of errors, and updates status with an error code.
`getName() RETURNING STRING`	Returns the qualified name of the current XML node, or NULL. Throws an exception in case of errors, and updates status with an error code.
`getNamespace() RETURNING STRING`	Returns the namespace URI of the current XML node, or NULL. Throws an exception in case of errors, and updates status with an error code.
`getText() RETURNING STRING`	Returns as a string the value of the current XML node, or NULL. This method is only valid on CHARACTERS, CDATA, SPACE, COMMENT, DTD and ENTITY_REFERENCE nodes. For an ENTITY_REFERENCE, this method returns the replacement value, or NULL if none. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Processing Instructions Methods

Object Methods
Name	Description
`getPITarget() RETURNING STRING`	Returns the target part of an XML ProcessingInstruction node, or NULL. This method is only valid on a PROCESSING_INSTRUCTION node. Throws an exception in case of errors, and updates status with an error code.
`getPIData() RETURNING STRING`	Returns the data part of an XML ProcessingInstruction node,or NULL. This method is only valid on a PROCESSING_INSTRUCTION node. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Attributes Methods

Object Methods
Name	Description
`getAttributeCount() RETURNING INTEGER`	Returns the number of XML attributes defined on the current XML node. Returns the number of attributes defined on the current XML node, or zero. This method is only valid on a START_ELEMENT node. Throws an exception in case of errors, and updates status with an error code.
`getAttributeLocalName( pos INTEGER ) RETURNING STRING`	Returns the local name of an XML attribute defined at a given position on the current XML node, where pos is the position of the attribute to return (Index starts at 1). Returns the local name of an attribute defined at given position on the current XML node, or NULL. Note: This method is only valid on a START_ELEMENT node. Throws an exception in case of errors, and updates status with an error code.
`getAttributeNamespace( pos INTEGER ) RETURNING STRING`	Returns the namespace URI of an XML attribute defined at a given position on the current XML node; pos is the position of the attribute to return (Index starts at 1). Returns the namespace URI of an attribute defined at the given position on the current XML node, or NULL. Note: This method is only valid on a START_ELEMENT node. Throws an exception in case of errors, and updates status with an error code.
`getAttributePrefix( pos INTEGER ) RETURNING STRING`	Returns the prefix of an XML attribute defined at a given position on the current XML node; pos is the position of the attribute to return (Index starts at 1). Returns the prefix of an attribute defined at the given position on the current XML node, or NULL. Note: This method is only valid on a START_ELEMENT node. Throws an exception in case of errors, and updates status with an error code.
`getAttributeValue( pos INTEGER ) RETURNING STRING`	Returns the value of an XML attribute defined at a given position on the current XML node; pos is the position of the attribute to return (Index starts at 1). Returns the value of an attribute defined at the given position on the current XML node, or NULL. Note: This method is only valid on a START_ELEMENT node. Throws an exception in case of errors, and updates status with an error code.
`findAttributeValue( name STRING, ns STRING ) RETURNING STRING`	Returns the value of an XML attribute of a given name and/or namespace on the current XML node, or NULL; name is the name of the attribute to retrieve, cannot be NULL; ns is the namespace URI of the attribute to retrieve, or NULL if the attribute is not namespace-qualified. Note: This method is only valid on a START_ELEMENT node. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Namespace Methods

Object Methods
Name	Description
`lookupNamespace( prefix STRING ) RETURNING STRING`	Looks up the namespace URI associated with a given prefix starting from the current XML node the StaxReader cursor is pointing to, where prefix is the prefix to look for; if NULL the default namespace URI will be returned. Returns the namespace URI associated with the prefix, or NULL if there is none. Throws an exception in case of errors, and updates status with an error code.
`lookupPrefix( ns STRING ) RETURNING STRING`	Looks up the prefix associated with a given namespace URI, starting from the current XML node the StaxReader cursor is pointing to, where ns is the namespace URI to look for, cannot be NULL. Returns the prefix associated with this namespace URI, or NULL if there is none. Throws an exception in case of errors, and updates status with an error code.
`getNamespaceCount() RETURNING INTEGER`	Returns the number of namespace declarations defined on the current XML node, or zero. Note: This method is only valid on a START_ELEMENT node. Throws an exception in case of errors, and updates status with an error code.
`getNamespacePrefix( pos INTEGER ) RETURNING STRING`	Returns the prefix of a namespace declaration defined at a given position on the current XML node, or NULL; pos is the position of the namespace declaration (Index starts at 1). Note: This method is only valid on a START_ELEMENT node. Throws an exception in case of errors, and updates status with an error code.
`getNamespaceURI( pos INTEGER ) RETURNING STRING`	Returns the URI of a namespace declaration defined at a given position on the current XML node, or NULL; pos is the position of the namespace declaration (Index starts at 1). Note: This method is only valid on a START_ELEMENT node. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Navigation Methods

Object Methods
Name	Description
`hasNext() RETURNING INTEGER`	Checks whether the StaxReader cursor can be moved to a XML node next to it. Returns TRUE if there is still an XML node in the stream, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.
`next()`	Moves the StaxReader cursor to the next XML node. Raises a 4GL exception in case of errors, and updates status with an error code.
`nextTag()`	Moves the StaxReader cursor to the next XML open or end tag. The cursor points to the end of the document if there is no tag any longer. Raises a 4GL exception in case of errors, and updates status with an error code.
`nextSibling()`	Moves the StaxReader cursor to the immediate next sibling XML Element of the current node, skipping all its child nodes. The cursor points to the parent end tag if there are no siblings any longer. Raises a 4GL exception in case of errors, and updates status with an error code.

Back to the top

Examples

    

    IMPORT xml
    
    FUNCTION parse(file)
      DEFINE file     String
      DEFINE event    String
      DEFINE ret      INTEGER
      DEFINE ind      INTEGER
      DEFINE reader   xml.StaxReader
      TRY 
    
        LET reader=xml.StaxReader.Create()
        CALL reader.readFrom(file)
         
        WHILE (true)
          LET event=reader.getEventType()
          CASE event
            WHEN "START_DOCUMENT"
              DISPLAY "Document reading started"
              DISPLAY "XML Version  : ",reader.getVersion()
              DISPLAY "XML Encoding : ",reader.getEncoding()
              IF reader.standaloneSet() THEN
                IF reader.isStandalone() THEN
                  DISPLAY "Standalone   : yes"
                ELSE
                  DISPLAY "Standalone   : no"
                END IF
              END IF
            WHEN "END_DOCUMENT"
              DISPLAY "Document reading finished"
            WHEN "START_ELEMENT"
              IF reader.isEmptyElement() THEN
                DISPLAY "<"||reader.getName()||"/>"
              ELSE
                DISPLAY "<"||reader.getName()||">"
              END IF
              FOR ind=1 TO reader.getNamespaceCount()
                DISPLAY "xmlns:"||reader.getNamespacePrefix(ind)||"="||reader.getNamespaceURI(ind)
              END FOR
              FOR ind=1 TO reader.getAttributeCount()
                IF reader.getAttributePrefix(ind) THEN
                  DISPLAY reader.getAttributePrefix(ind)||":"||reader.getAttributeLocalName(ind)||"="||reader.getAttributeValue(ind)
                ELSE
                  DISPLAY reader.getAttributeLocalName(ind)||"="||reader.getAttributeValue(ind)
                END IF
              END FOR
            WHEN "END_ELEMENT"
              DISPLAY "</"||reader.getName()||">"
            WHEN "CHARACTERS"
              IF reader.hasText() AND NOT reader.isIgnorableWhitespace() THEN
                DISPLAY "CHARACTERS :",reader.getText()
              END IF
            WHEN "COMMENT"
              IF reader.hasText() THEN
                DISPLAY "Comment :",reader.getText()
              END IF
            WHEN "CDATA"
              IF reader.hasText() THEN
                DISPLAY "CDATA :", reader.getText()
              END IF
            WHEN "PROCESSING_INSTRUCTION"
              DISPLAY "PI :",reader.getPITarget(),reader.getPIData()
            WHEN "ENTITY_REFERENCE"
              DISPLAY "Entity name :",reader.getName()
            OTHERWISE
              DISPLAY "Unknown "||event||" node"
          END CASE
          IF reader.hasNext() THEN
            CALL reader.next()
          ELSE
            CALL reader.close()
            EXIT WHILE
          END IF
        END WHILE
      CATCH
        DISPLAY "StaxReader ERROR :",STATUS||" ("||SQLCA.SQLERRM||")"      
      END TRY
    END FUNCTION

Back to the top

StaxReader event types

Type	Description	XML sample
START_DOCUMENT	StaxReader cursor points to the beginning of the XML document.	`<?xml version="1.0" standalone="no"?>`
END_DOCUMENT	StaxReader cursor has reached the end of the XML document. Note : No additional parsing operation will succeed.
START_ELEMENT	StaxReader cursor points to an XML start element or empty element node.	`<p:elt attr="val">` or `<p:elt attr="val"/>`
END_ELEMENT	StaxReader cursor points to an XML end element node.	`</p:elt>`
CHARACTERS	StaxReader cursor points to an XML text node.	`... eltA/>This is text<eltB ...`
CDATA	StaxReader cursor points to an XML CData node.	`<![CDATA[<Hello, world!>]]>`
SPACE	StaxReader cursor points to an XML text node containing only whitespaces.	`... eltA/> <eltB ...`
COMMENT	StaxReader cursor points to an XML comment node.	`<!-- a comment -->`
DTD	StaxReader cursor points to a DTD string.	`<!DOCTYPE A [ <!ELEMENT B (C+)> ]>`
ENTITY_REFERENCE	StaxReader cursor points to an XML entity reference node.	`&ref;`
PROCESSING_INSTRUCTION	StaxReader cursor points to an XML processing instruction node.	`<?target data?>`
ERROR	StaxReader cursor points to an unexpected XML node.

Back to the top

StaxReader Features

Feature	Description
expand-entity-references	Defines whether XML EntityReference nodes are kept or replaced during the parsing of an XML document. Note: default value is TRUE.

Back to the top