Back to Contents

The Stax Reader class

Summary:

See also: The Genero Web Services XML Library

Syntax

The StaxReader class provides methods compatible with StAX (Streaming API for XML) for reading XML documents.

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

Syntax

xml.StaxReader

Methods

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.
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.
readFromText(
  txt TEXT )		 Sets the input stream of the StaxReader object to a TEXT lob, and starts the streaming; txt must be a TEXT lob located in memory and containing the XML to read.
Raises a 4GL exception in case of errors, and updates status with an error code.
readFromPipe(
  cmd String )		 Sets the input stream of the StaxReader object to a PIPE, and starts the streaming; cmd is the command to start the PIPE and where the reader will get the XML from.
Throws an 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.
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.
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.
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.
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.
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.
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).
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

Example: Using StaxReader class methods

01 IMPORT xml
02
03 FUNCTION parse(file  )
04   DEFINE file         String
05   DEFINE event       String
06   DEFINE ret           INTEGER
07   DEFINE ind           INTEGER
08   DEFINE reader   xml.StaxReader
09   TRY 
10     LET reader=xml.StaxReader.Create()
11     CALL reader.readFrom(file)
12     WHILE (true)
13       LET event=reader.getEventType()
14       CASE event
15         WHEN "START_DOCUMENT"
16           DISPLAY "Document reading started"
17           DISPLAY "XML Version  : ",reader.getVersion()
18           DISPLAY "XML Encoding : ",reader.getEncoding()
19           IF reader.standaloneSet() THEN
20             IF reader.isStandalone() THEN
21               DISPLAY "Standalone   : yes"
22             ELSE
23               DISPLAY "Standalone   : no"
24             END IF
25           END IF
26         WHEN "END_DOCUMENT"
27           DISPLAY "Document reading finished"
28         WHEN "START_ELEMENT"
29           IF reader.isEmptyElement() THEN
30             DISPLAY "<"||reader.getName()||"/>"
31           ELSE
32             DISPLAY "<"||reader.getName()||">"
33           END IF
34           FOR ind=1 TO reader.getNamespaceCount()
35             DISPLAY "xmlns:"||reader.getNamespacePrefix(ind)||"="||reader.getNamespaceURI(ind)
36           END FOR
37           FOR ind=1 TO reader.getAttributeCount()
38             IF reader.getAttributePrefix(ind) THEN
39               DISPLAY reader.getAttributePrefix(ind)||":"||reader.getAttributeLocalName(ind)||"="||reader.getAttributeValue(ind)
40             ELSE
41               DISPLAY reader.getAttributeLocalName(ind)||"="||reader.getAttributeValue(ind)
42             END IF
43           END FOR
44         WHEN "END_ELEMENT"
45           DISPLAY "</"||reader.getName()||">"
46         WHEN "CHARACTERS"
47           IF reader.hasText() AND NOT reader.isIgnorableWhitespace() THEN
48             DISPLAY "CHARACTERS :",reader.getText()
49           END IF
50         WHEN "COMMENT"
51           IF reader.hasText() THEN
52             DISPLAY "Comment :",reader.getText()
53           END IF
54         WHEN "CDATA"
55           IF reader.hasText() THEN
56             DISPLAY "CDATA :", reader.getText()
57           END IF
58         WHEN "PROCESSING_INSTRUCTION"
59           DISPLAY "PI :",reader.getPITarget(),reader.getPIData()
60         WHEN "ENTITY_REFERENCE"
61           DISPLAY "Entity name :",reader.getName()
62         OTHERWISE
63           DISPLAY "Unknown "||event||" node"
64       END CASE
65       IF reader.hasNext() THEN
66         CALL reader.next()
67       ELSE
68         CALL reader.close()
69         EXIT WHILE
70       END IF
71     END WHILE
72   CATCH
73     DISPLAY "StaxReader ERROR :",STATUS||" ("||SQLCA.SQLERRM||")"      
74   END TRY
75 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.
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.
Default value is TRUE.

Back to the top