XML Engine DOM API: API Description

XML Engine DOM API is provided as an API library. The wrapper provides classes and methods that might be used by the client to store and modify XML data. All parser context, DOM tree data and XML data are in client thread memory. All classes provide functionality of different nodes type in the DOM tree. These nodes represent XML data such as elements, attributes, etc. To process data that are held in classes a user calls methods provided by it. Those methods allow reading, changing or deleting data. Additionally, the API allows for holding binary data in the DOM tree. Such data are stored in data container nodes. This is a special part of this functionality, not described in the DOM specification. The XML Engine DOM API provides functionality to process XML data so it might be used in the application type. It might be used by other libraries or end user applications. This parser functionality might also be used by all applications that need to store some non text data (so no XML data) in the DOM tree.

Use cases

XML Engine DOM API should be used for processing XML data in the way described in the DOM specification. Main actions here are:

1. Initializing the subsystem - to provide functionality of DOM parser the subsystem needs to be initialized.
2. Parsing XML data - parser builds a DOM tree
3. Modifying DOM tree - processing nodes in DOM tree:
   • Creating new document - building new DOM tree
   • Adding new nodes to tree
   • Removing nodes from tree
   • Editing existing nodes
4. Saving document - serializing DOM tree to XML data

API class structure

Classes provided in the API might be subdivided into:

1. Parsing classes
   • RXmlEngDOMParser - provides methods for parsing XML documents and building a DOM tree. May be configured as chunk parser or used to parse all data at once.
2. DOM tree structure classes
   1. Nodes types from DOM specification:
      • TXmlEngNode - base class for nodes. Store node properties. Describes DOM action for nodes.
      • RXmlEngDocument – a class holding whole DOM tree. Stores document properties. Contains all nodes, allows creating a new one. The class also frees all memory used to hold XML data. The RXmlEngDocument class provides a functionality that allows saving the tree.
      • TXmlEngElement - stores element properties. Describes the DOM action for the element.
      • TXmlEngAttr – a class holding attributes properties. Provides functionality for processing this type of nodes.
      • TXmlEngCharacterData - it is a base class for all text nodes. Describes the DOM action for the nodes that contain text data.
      • TXmlEngComment - one of text node class. Stores comment properties.
      • TXmlEngTextNode - next text type node class. Stores text properties.
      • TXmlEngCDATASection - stores CDATA properties.
      • TXmlEngProcessingInstruction - stores processing instruction properties.
      • TXmlEngEntityReference - a class storing entity reference properties.
      • TXmlEngNamespace - stores namespaces node. Provides methods specific for such type of node.
   2. Non text data nodes support:
      • TXmlEngineDataContainer – a base class for all binary data containers. Implements all methods specific for non XML nodes.
      • TXmlEngBinaryContainer - represents binary data in a DOM tree. A client can decide how it will be serialized using the MXmlEngDataSerializer interface.
      • TXmlEngChunkContainer - represents binary data that is stored in an external (not owned by the document) memory chunk. Upon creating a chunk container, chunk handle reference, size, and offset are stored in the container. A client can decide how it will be serialized using the MXmlEngDataSerializer interface.
      • TXmlEngFileContainer - represents binary data that is stored in a file (not owned by the document). Upon creating a file container, file handle reference is stored in the container. A client can decide how it will be serialized using the MXmlEngDataSerializer interface.
3. M-interfaces
   • MXmlEngDataSerializer – an interface used by XML Engine DOM to serialize binary data. This interface may be implemented by a client application and provided to the wrapper while saving the document. If no document is serialized in a default way - data containers will be skip.
   • MXmlEngNodeFilter - is used to decide if a node should be serialized. A user implements it and provides while saving the document.
   • MXmlEngOutputStream - is used while saving the document. Client implements the interface. During serialization wrapper calls Write and Close methods from that class.
   • MXmlEngUserData - interface that allows users to store some additional data in a node, not as a part of the tree (node), but as a container connected to the node.
4. Helper classes - classes that provide additional functionality used during work with component.
   • TXmlEngSerializationOptions - describes options used during document saving.
   • RXmlEngDOMImplementation - provides methods for performing operations that are independent of any particular instance of the DOM. It allows initializing and closing a component.
   • RXmlEngNodeList< T > - a container for storage nodes. It allows a user to decide what type of node it will hold.
   • RXmlEngNodeListImpl - class implements all actions for RXmlEngNodeList.

Some classes like TXmlNode has protected members. It is protected not private to allow changes of those fields in client classes that inherits DOM API classes. Client should change it only if he knows the structure of the tree and know how to use it. Any incorrect changes might lead to panics during client application processing.