Namespace Dom

This namespace declares the collection of abstract classes, designed to express two object-based XML document models. The first model is the Document Object Model (DOM) as specified by DOM Level 1. The second, proprietary model is called XPath Document Model (XDM); it was originally designed to support document processing specified by XPath and XSLT.

These two document models use different approach to the namespace handling. In DOM, namespaces are represented as ordinary attribute nodes. In XDM, namespaces are represented as nodes of the special namespace node type; furhtermore, every element node has the individual list of namespace nodes which represent all namespaces declared on this element node, together with the default namespace (if any) and the implicit "xml:" namespace.

XDM implements the read-only access to documents. XDM documents can be created using several toolkit components (for example, using DOM writers). Once created, XDM documents cannot be modified, and content modification methods will fail being applied to nodes of these documents.

XDM was initially introduced due to the fundamental incompatibility between DOM and document model required by XPath and XSLT. It was recognized, however, that XDM provides a useful representation of XML documents in various XML processing scenarios, even in those having no direct relation to XPath or XSLT. In general, XDM provides more compact document representation than DOM, and the toolkit implements faster procedure for building XDM trees from various sources. Furthermore, unlike DOM, XDM is fully namespace-aware, which makes this document model useful for implementing the recent XML specifications, which strongly rely on the XML namespace concept.

Both DOM and XDM models are implemented using the same set of interfaces, and most of the toolkit functions are capable for working with nodes represented using both models; exceptions from this rule are explicitly outlined in the documentation of the respective functions. It is important to note, however, that not all classes and methods described below are supported by each particular model. For example, DOM does not support the INamespace class and related methods, while XDM does not support methods which modify the document content. Exact model-specific restrictions can be found in the documentation for each DOM/XDM method.

Note that there few are methods and even classes, which at present are not implemented neither for DOM nor for XDM. Although these classes are mentioned in the toolkit declarations an in this documentation, they must be considered reserved for future toolkit releases. However, since these particular classes and methods are almost insignificant for implementing modern XML technologies, their support in the future toolkit releases is not guaranteed.

DOM/XDM objects are represented as pointers to C++ objects. The toolkit provides two representation formats.

The first format is implemented using the ordinary C++ pointers, for example, generic nodes of class INode will be represented using the data type INode * . This representation can be safely used, when there is guarantee that the pointer to the object is owned in some place of the program code. For example, C++ pointers to DOM objects can be safely passed as function arguments.

The second format is implemented using specially introduced data types. For each DOM/XDM class an individual data type is defined. These data types specify "safe" pointers to objects of the respective classes. Each safe pointer "owns" a reference to the object. The C++ pointer to a DOM/XDM object is valid if there exists at least one safe pointer, which owns a reference to this object. Pointers fo DOM/XDM objects returned by C++ functions or stored in C++ variables are usually implemented as safe pointers.

The toolkit is using common naming conventions for classes and respective safe pointers. DOM/XDM class names are started with letter 'I' ; names for corresponding safe pointers are formed via replacing this starting letter with 'X' . For example, type XNode describes safe pointers to generic DOM/XDM nodes represented using class INode .

In most cases, the DOMString interface defined by DOM is represented using pointers to null-terminated arrays of 16-bit characters (that is, using WCHAR * data type). If such pointers are returned by DOM/XDM methods, the storage used to keep the string data is owned by the respective DOM/XDM objects, and pointers to the string values are valid while the pointers to their owner objects are valid.

Null string values are represented as empty strings (that is, arrays of WCHAR consiting of a single null character).

There are very few exceptions, where DOM strings are represented using the toolkit CString class. These exceptions apply in cases, where the DOM/XDM methods return syntetic string values, which are not stored directly by respective objects.

The Document Object Model (Level 1) is described in Document Object Model (DOM) Level 1 Specification .

Since:

1.00.00

Version:

1.50.00

Author:

Alexey Gokhberg