The StaxWriter class

Summary:

Syntax
Methods
Example

Syntax

The StaxWriter class provides methods compatible with StAX (Streaming API for XML) for writing XML documents.

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

Syntax

xml.StaxWriter

Methods

Creation
Configuration
Output
Document
NameSpace
Nodes

Creation methods

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

Back to the top

Configuration methods

Object Methods
Name	Description
`setFeature( feature STRING, value STRING )`	Sets a feature of a StaxWriter object, where feature is 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 `writeTo` or `writeToDocument`). Throws an exception in case of errors, and updates status with an error code.
`getFeature( feature STRING ) RETURNING STRING`	Gets a feature of a StaxWriter object, where feature is the name of a feature; returns the feature value. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Output methods

Object Methods
Name	Description
`writeTo( url STRING )`	Sets the output stream of the StaxWriter object to a file or an URL, and starts the streaming; url is a valid URL or the name of the file that will contain the resulting XML document. 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.
`writeToDocument( doc xml.DomDocument )`	Sets the output stream of the StaxWriter object to an Xml.DomDocument object, and starts the streaming; doc is the empty xml.DomDocument object that will contain the resulting XML document. Throws an exception in case of errors, and updates status with an error code.
`writeToText( txt TEXT )`	Sets the output stream of the StaxWriter object to a TEXT lob, and starts the streaming; txt must be a TEXT lob located in memory that will contain the resulting XML document. Throws an exception in case of errors, and updates status with an error code.
`writeToPipe( cmd String )`	Sets the output stream of the StaxWriter object to a PIPE, and starts the streaming; cmd is the command to start the PIPE that will get the resulting XML document. Throws an exception in case of errors, and updates status with an error code.
`close()`	Closes the StaxWriter streaming, and releases all associated resources.

Usage

writeTo("printerList.xml")

writeTo("http://myserver:1100/documents/printerList.xml")

writeTo("https://myserver:1100/documents/printerList.xml")

writeTo("alias://printerlist")
where printerlist alias is defined in fglprofile as ws.printerlist.url = "http://myserver:1100/documents/ptinterList.xml".

Back to the top

Document methods

Object Methods
Name	Description
`startDocument( encoding STRING, version STRING, standalone INTEGER )`	Writes an XML declaration to the StaxWriter stream, where encoding is the encoding of the XML declaration, or NULL to use the default UTF-8 encoding; version is the XML version of the XML declaration, or NULL to use the default 1.0 version; standalone when TRUE sets the standalone of the XML declaration to "yes", when FALSE sets it to "no" or NULL. Throws an exception in case of errors, and updates status with an error code.
`endDocument()`	Closes any open tags and writes corresponding end tags. Throws an exception in case of errors, and updates status with an error code.
`dtd( data STRING )`	Writes a DTD to the StaxWriter stream, where data is a string representing a valid DTD, cannot be NULL. Throws an exception in case of errors, and updates status with an error code.

Usage

startDocument("utf-8","1.0",true)
produces
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

dtd("note [<!ENTITY writer \"Donald Duck.\">]")

Back to the top

NameSpace methods

Object Methods
Name	Description
`setPrefix( prefix STRING, ns STRING )`	Binds a namespace URI to a prefix. The prefix scope is the current START_ELEMENT / END_ELEMENT pair; prefix is the prefix to be bind to the URI, cannot be NULL; ns is the namespace URI to be bind to the prefix, cannot be NULL. Throws an exception in case of errors, and updates status with an error code.
`setDefaultNamespace( defaultNS STRING )`	Binds a namespace URI to the default namespace. The default namespace scope is the current START_ELEMENT / END_ELEMENT pair; defaultNS is the URI to bind to the default namespace, cannot be NULL. Throws an exception in case of errors, and updates status with an error code.
`declareNamespace( prefix STRING, ns STRING )`	Binds a namespace URI to a prefix, and forces the output of the XML namespace definition to the StaxWriter stream. The stream must point to a START_ELEMENT, and the prefix scope is the current START_ELEMENT / END_ELEMENT pair. prefix is the prefix to be bind to the URI, cannot be NULL; ns is the URI to bind to the default namespace, cannot be NULL. Throws an exception in case of errors, and updates status with an error code.
`declareDefaultNamespace( defaultNS STRING )`	Binds a namespace URI to the default namespace, and forces the output of the default XML namespace definition to the StaxWriter stream. The stream must point to a START_ELEMENT, and the prefix scope is the current START_ELEMENT / END_ELEMENT pair; defaultNS is the URI to bind to the default namespace, cannot be NULL. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Nodes methods

Object Methods
Name	Description
`startElement( name STRING )`	Writes an XML start element to the StaxWriter stream. All startElement methods open a new scope and set the stream to a START_ELEMENT; then, writing the corresponding endElement causes the scope to be closed. name is the local name of the XML start element, cannot be NULL. Throws an exception in case of errors, and updates status with an error code.
`startElementNS( name STRING, ns STRING )`	Writes a namespace-qualified XML start element to the StaxWriter stream. All startElementNS methods open a new scope and set the stream to a START_ELEMENT; then, writing the corresponding endElement causes the scope to be closed. name is the local name of the XML start element, cannot be NULL; ns is the namespace URI of the XML start element, cannot be NULL. If namespace URI has not been bound to a prefix with one of the functions `setPrefix()`, `declareNamespace()`, `setDefaultNamespace()` or `declareDefaultNamespace()`, the operation will fail with an exception. Throws an exception in case of errors, and updates status with an error code.
`emptyElement( name STRING )`	Writes an empty XML element to the StaxWriter stream, where name is the local name of the XML empty element, cannot be NULL. Throws an exception in case of errors, and updates status with an error code.
`emptyElementNS( name STRING, ns STRING )`	Writes an empty namespace qualified XML element to the StaxWriter stream, where name is the local name of the XML empty element, cannot be NULL; ns is the namespace URI of the XML empty element, cannot be NULL. If namespace URI has not been bound to a prefix with one of the functions: `setPrefix()`, `declareNamespace()`, `setDefaultNamespace()` or `declareDefaultNamespace()`, operation will fail with an exception. Throws an exception in case of errors, and updates status with an error code.
`endElement()`	Writes an end tag to the StaxWriter stream relying on the internal state to determine the prefix and local name of the last START_ELEMENT. Throws an exception in case of errors, and updates status with an error code.
`attribute( name STRING, value STRING )`	Writes an XML attribute to the StaxWriter stream, where name is the local name of the XML attribute, cannot be NULL; value is the value of the XML attribute, cannot be NULL. Attributes can only be written on the StaxWriter stream if it points to a START_ELEMENT or an EMPTY_ELEMENT, otherwise the operation will fail with an exception; that is, this method can only be called after a s`tartElement()`, `startElementNS()`, `emptyElement()`, `emptyElementNS()` or `attribute()` and `attributeNS()`. Throws an exception in case of errors, and updates status with an error code.
`attributeNS( name STRING, ns STRING, value STRING )`	Writes an XML namespace qualified attribute to the StaxWriter stream, where name is the local name of the XML attribute, cannot be NULL; ns: the namespace URI of the XML attribute, cannot be NULL; value is the value of the XML attribute, cannot be NULL. Attributes can only be written on the StaxWriter stream if it points to a START_ELEMENT or an EMPTY_ELEMENT, otherwise the operation will fail with an exception; that is, this method can only be called after a s`tartElement()`, `startElementNS()`, `emptyElement()`, `emptyElementNS()` or `attribute()` and `attributeNS().` If namespace URI has not been bound to a prefix with one of these functions : `setPrefix()`, `declareNamespace()`,`setDefaultNamespace()` or `declareDefaultNamespace()`, the operation will fail with an exception. Throws an exception in case of errors, and updates status with an error code.
`processingInstruction( target STRING, data STRING )`	Writes an XML ProcessingInstruction to the StaxWriter stream, where target is the target of the Processing Instruction, cannot be NULL; data is the data of the Processing Instruction, or NULL. Throws an exception in case of errors, and updates status with an error code.
`comment( data STRING )`	Writes an XML comment to the StaxWriter stream where data is the data in the XML comment, or NULL. Throws an exception in case of errors, and updates status with an error code.
`characters( text STRING )`	Writes an XML text to the StaxWriter stream, where text is the value to write. Throws an exception in case of errors, and updates status with an error code.
`cdata( data STRING )`	Writes an XML CData to the StaxWriter stream, where data is the data contained in the CData section, or NULL. Throws an exception in case of errors, and updates status with an error code.
`entityRef( name STRING )`	Writes an XML EntityReference to the StaxWriter stream, where name is the name of the entity, cannot be NULL. Throws an exception in case of errors, and updates status with an error code.

Back to the top

StaxWriter Features

Feature	Description
format-pretty-print	Formats the output by adding whitespace to produce a pretty-printed, indented, human-readable form. Default value is FALSE.
smart-ending-elements	Outputs each tag closed with an endElement() call, as empty elements if they have no children. Default value is FALSE.

Example: Using StaxWriter class methods

01 IMPORT xml
02
03 FUNCTION save(file)
04   DEFINE file STRING
05   DEFINE writer xml.StaxWriter
06   TRY
07     LET writer = xml.StaxWriter.Create()
08     CALL writer.setFeature("format-pretty-print",TRUE)
09     CALL writer.writeTo(file)
10     CALL writer.startDocument("utf-8","1.0",true)
11     CALL writer.comment("This is my first comment using a stax writer")
12     CALL writer.setPrefix("c","http://www.mycompany.com/c")
13     CALL writer.setPrefix("d","http://www.mycompany.com/d")
14     CALL writer.setDefaultNamespace("http://www.mycompany.com/d")
15     CALL writer.startElementNS("root", "http://www.mycompany.com/d")
16     CALL writer.attribute("attr1","value1")
17     CALL writer.attribute("attr2","value2")
18     CALL writer.attributeNS("attr3", "http://www.mycompany.com/d","value3")
19     CALL writer.comment("This is a comment using a stax writer")
20     CALL writer.startElementNS("eltA", "http://www.mycompany.com/d")
21     CALL writer.CData("<this is a CData section>")
22     CALL writer.endElement()
23     CALL writer.startElementNS("eltB", "http://www.mycompany.com/c")
24     CALL writer.characters("Hello world, I'm from the development team")
25     CALL writer.entityRef("one")
26     CALL writer.endElement()
27     CALL writer.processingInstruction("command1","do what you want")
28     CALL writer.endElement()
29     CALL writer.comment("This is my last comment using a stax writer")
30     CALL writer.endDocument()
31     CALL writer.close()
32     RETURN TRUE
33   CATCH
34     DISPLAY "StaxWriter ERROR :",STATUS, SQLCA.SQLERRM
35     RETURN FALSE
36   END TRY
37 END FUNCTION

Back to the top