DOMParser Class Reference

This class provides basic methods to parse or synthesize XML documents using the Document Object Model (DOM). More...

Public Member Functions
	DOMParser ()
	The constructor actually takes no arguments. More...
DOMDocument	getDocument ()
	This returns the root of the DOM tree after a successful call of parse(), otherwise null.
String	getLastError ()
	This returns the text of the last occurred error.
Integer	parse (String xml, boolean fromFile)
	Parse an XML document, either from a String or from a local file. More...
Var	write (DOMNode node, String path, String encoding, boolean prettyPrint)
	Build an XML document from a DOM tree. More...

Public Attributes
Error Constants
In contrast to many other methods of the DOM API, the parse() method does not forward exceptions of the native parser to the calling script. It rather stores the error text in a buffer, which the script can read with getLastError(). The return value signals the type of the exception, which equals one of these constants. The constants are also properties of the constructor, so it is possible to read them in the style DOMParser.ErrCatDOM .
Integer	ErrCatNone
	This constant with the value zero indicates "no error".
Integer	ErrCatEnv
	This constant represents errors detected by interface code outside the native parser.
Integer	ErrCatXML
	This constant represents a caught exception of the type "XMLException".
Integer	ErrCatSAX
	This constant represents a caught exception of the type "SAXException".
Integer	ErrCatDOM
	This constant represents a caught exception of the type "DOMException".

Detailed Description

This class provides basic methods to parse or synthesize XML documents using the Document Object Model (DOM).

See also

XML-DOM Example

Since

DOCUMENTS 4.0c

Constructor & Destructor Documentation

DOMParser()

DOMParser::DOMParser

(

)

The constructor actually takes no arguments.

Member Function Documentation

parse()

Integer DOMParser::parse	(	String	xml,
		boolean	fromFile
	)

Parse an XML document, either from a String or from a local file.

Parameters

xml	Either the XML itself or the path and file name of a local file
fromFile	true to parse a local file, otherwise false.

Returns

An integer, which describes an error category. See ErrCatNone and further constants.

Remarks

On success, call getDocument() to access the DOM tree. On error use getLastError() to obtain an error text.
The encapsulated native DOM library supports the following character encodings: ASCII, UTF-8, UTF-16, UCS4, EBCDIC code pages IBM037, IBM1047 and IBM1140, ISO-8859-1 (aka Latin1) and Windows-1252. (no guarantee)

Since

DOCUMENTS 4.0c

write()

Var DOMParser::write	(	DOMNode	node,
		String	path,
		String	encoding,
		boolean	prettyPrint
	)

Build an XML document from a DOM tree.

Parameters

node	The root node to build the document from. Though the interface accepts any DOMNode, only a DOMDocument should be passed. Otherwise the output may be a fragment which is not a valid XML.
path	Optional path and filename to save the XML in the local file system.
encoding	Optional encoding specification for the file. Only used when path is also specified.
prettyPrint	Optional boolean value.

Returns

The return type depends on the parameters. After saving to a local file, the method returns a boolean value, which indicates the success of the operation. Otherwise the return value is a String with the XML itself, or an empty string after an error.

Note

Saving to a local file is not supported on all platforms. If a script tries it while the version of the native DOM library is too old, the method just throws a JavaScript error.

Remarks

To obtain an error message use getLastError(). When the message is just "NULL pointer", the native DOM library may have failed to open the output file for writing. When the method writes to a string, the encoding is always the server application's internal encoding.
The encapsulated native DOM library supports the following character encodings: ASCII, UTF-8, UTF-16, UCS4, EBCDIC code pages IBM037, IBM1047 and IBM1140, ISO-8859-1 (aka Latin1) and Windows-1252. (no guarantee)

Since

DOCUMENTS 4.0c

Parameter prettyPrint since DOCUMENTS 5.0b HF3