XML APIs

Since the 3.2 version of Gambas, the gb.xml component offers different APIs to manipulate XML data. This page is intended to describe how each works internally, so that you can choose the good one for your use.

XmlReader

XmlReader is a XML stream reader : it can read the beginning of a XML stream (not necessarily a full XML document) on the fly. The input stream can be any Gambas stream containing XML data, like File, Process or Socket.
In a few words, when you call the Read() method, XmlReader reads the stream character per character, and stops when it finds something interesting (Element, Attribute, Text ...). Thereby, the XML document is read from the first node to the last, and from the shallower to the deepest one.

Because of this, XmlReader is slower than the DOM API. This makes it only useful for reading network streams, but should also be used for huge XML files (when its size is measured in MBytes), because the document is never wholly loaded, so it can avoid eating all the memory when parsing it.

XmlWriter

XmlWriter works like XmlReader, except that it writes into the stream instead of reading from it. That's it.

XmlDocument

The XmlDocument class, and all the related ones (like XmlNode, XmlElement ...), make the DOM API.

When you open an XML Document (using a file or a string that is already in memory), the whole content is parsed and then loaded in memory as a XmlNode tree.
This API can be used to read as well as write an XML document : you can browse the whole tree, you can add nodes when and where you want, you can look for specific nodes ... anything is possible.

Because the whole document is loaded, using this API could eat all your memory if you read or write a huge document. If this is the case, you should use the XmlReader or XmlWriter APIs instead.

XmlExplorer

The XmlExplorer class is rather special, as it is a compromise between XmlReader and XmlDocument : the interface is the same as XmlReader, but it internally works like the DOM API : when you open a document, it is parsed and loaded the same way as XmlDocument does. Then, when you call the Read() method, an internal pointer is moved to the next node, and you can access to the current node using the Node property, like XmlReader.

If you use the XmlReader API in your project, and you suddenly realize that for performance reasons, you should use the DOM API, but if you don't want to rewrite all your code, you can use XmlExplorer, this will be as fast. You just have to replace all the XmlReader occurences by XmlExplorer, and this should will work.

Likewise, if for some reason you want to explore your documents in a linear way (from the first node to the last ...), and if you can load the whole document in memory, using this class could be a good solution for you.

Problems ?

If you encounter problems, please send an accurate bug report. See Reporting a problem, a bug or a crash for further information.