|
|
# API General Considerations
|
|
|
|
|
|
## Wrap libxml2
|
|
|
|
|
|
libxml2 is a C based library, so no GObject interface is avairable for it. GXml wraps it providing an API to hide most details on its use.
|
|
|
|
|
|
For DOM4 API, all returned objects are created on the fly with internal references to libxml2's native nodes pointers in order to provide automatic memory management like unref an object, so **is highly recommended to use DOM4 API instead to mix with libxml2 structs**.
|
|
|
|
|
|
libxml2's tree `xmlDoc*` is used by GXml's objects so, any modification to that pointers should use libxml2's API. Fortunally, GXml's API provides a DOM4 one for most common use cases.
|
|
|
|
|
|
## General interface API
|
|
|
|
|
|
GXml provides an API to access XML tree, using objects like `Node`, `Document`, `Namespace`, but that API is not DOM4 compliant so will be deprecated shortly because is a convenient one for DOM1.
|
|
|
|
|
|
This DOM1 compatible general interfaces, have been implemented by libxml2's wraps and by a first try of pure `GObject` implementation prefixed with T character, like TNode and its descendants. TNode will be deprecated shortly.
|
|
|
|
|
|
## W3C DOM4
|
|
|
|
|
|
DOM4 provides a reach API, full of features, most of them not implemented yet in current 0.16 release.
|
|
|
|
|
|
DOM4 is implemented by libxml2 class wrappers and by a pure GObject implementation prefixed with Gom characters, like GomNode and its descendants.
|
|
|
|
|
|
GomNode and its descendants, fixes some limitations inherited by GNode from libxml2, like the ability to have more than one child DomText in a DomElement; there are more room for improvements in GomNode than in GNode in the future.
|
|
|
|
|
|
# Serialization
|
|
|
|
|
|
Serialization is the process to represent to/back GObject in XML. Can be many different ways to archive that.
|
|
|
|
|
|
In GXml you can simple derive a class from `GElement` or `GomElement`to be able to set properties or add new nodes it them, but only if they are the GNode or GomElement descendants, respectively.
|
|
|
|
|
|
## TNode for fast serialization
|
|
|
|
|
|
TNode currently use libxml2 to create a `xmlDoc*` native tree and then re-parse it to its native GObject tree, this is slow. One advantage of TNode, is that it uses `xmlTextWritter` to write back to XML, which it's faster than `xmlDoc*`.
|
|
|
|
|
|
## GomNode for fast de/serialization
|
|
|
|
|
|
GomNode currently use `xmlTextReader` to parse an XML document, reducing parsing time compared to TNode while reduce footprint too.
|
|
|
|
|
|
GomNode, like TNode, uses `xmlTextWritter` with an improved parser, so write down XML documents is fast.
|
|
|
|
|
|
### GObject to XML and back
|
|
|
|
|
|
GomNode's descendant GomElement, provides an easy way to use GObject's properties to XML Node's attributes, mapping a one to one XML element node to a GObject.
|
|
|
|
|
|
#### XML structure changes tolerant
|
|
|
|
|
|
Like a DomElement, GomElement descendants can have any DOM node and attributes; it is not limited to GObject's properties defined at class declaration, so is very easy to add new nodes and attributes to source XML and GomElement, just map the ones defined at class declaration, but allows you to use DOM4 API to access them.** XML changes tolerant**.
|
|
|
|
|
|
In the same way, when you write down an GomElement, with pre-parsed childs, any modification to GObject's properties and/or DOM nodes will be preserved. **No XML data lost**.
|
|
|
|