| |
The experimental IDOM API is a new design of the C++ DOM API.
Please note that this experimental IDOM API is only a prototype
and is subject to change.
|
| |
The C++ IDOM implementation no longer uses reference counting for
automatic memory management. The C++ IDOM uses an independent storage
allocator per document. The storage for a DOM document is
associated with the document node object.
The advantage here is that allocation would require no synchronization
in most cases (based on the same threading model that we
have now - one thread active per document, but any number of
documents running in parallel with separate threads).
The allocator does not support a delete operation at all - all
allocated memory would persist for the life of the document, and
then the larger blocks would be returned to the system without separately
deleting all of the individual nodes and strings within the document.
The C++ DOM and IDOM are similar in the use of factory methods in the
document class for all object creation. They differ in the object deletion
mechanism.
In C++ DOM, there is no explicit object deletion. The deallocation of
memory is automatically taken care of by the reference counting.
In C++ IDOM, there is an implicit and explicit object deletion.
|
| |
If user is manually building a DOM tree in memory using the document factory methods,
then the user needs to explicitly delete the document object to free all the allocated memory.
It normally falls under the following 3 scenarios:
- If a user is manually creating a DOM document using the document implementation
factory methods, IDOM_DOMImplementation::getImplementation()->createDocument,
then the user needs to explicitly delete the document object to free all
allocated memory.
- If a user is creating a DocumentType object using the document implementation factory
method, IDOM_DOMImplementation::getImplementation()->createDocumentType, then
the user also needs to explicitly delete the DocumentType object to free the
allocated memory.
- Special case: If a user is creating a DocumentType using the document
implementation factory method, and clone the node WITHOUT assigning a document
owner to that DocumentType object, then the cloned node also needs to be explicitly
deleted.
Consider the following code snippets:
 |  |  |  |
// C++ IDOM - explicit deletion
// use the document implementation factory method to create a DocumentType and a document
IDOM_DocumentType* myDocType;
IDOM_Document* myDocument;
IDOM_Node* root;
IDOM_Node* aNode;
myDocType = IDOM_DOMImplementation::getImplementation()->createDocumentType(name, 0, 0);
myDocument = IDOM_DOMImplementation::getImplementation()->createDocument(0, name, myDocType);
root = myDocument->getDocumentElement();
aNode = myDocument->createElement(anElementname);
root->appendChild(aNode);
// need to delete both myDocType and myDocument which are created through DOM Implementation
delete myDocType;
delete myDocument;
|  |  |  |  |
 |  |  |  |
// C++ IDOM - explicit deletion
// use the document implementation factory method to create a document
IDOM_DocumentType* myDocType;
IDOM_Document* myDocument;
IDOM_Node* root;
IDOM_Node* aNode;
myDocument = IDOM_DOMImplementation::getImplementation()->createDocument();
myDocType = myDocument->createDocumentType(name);
root = myDocument->createElement(name);
aNode = myDocument->createElement(anElementname);
myDocument->appendChild(myDocType);
myDocument->appendChild(root);
root->appendChild(aNode);
// the myDocType is created through myDocument, not through Document Implementation
// thus no need to delete myDocType
delete myDocument;
|  |  |  |  |
 |  |  |  |
// C++ IDOM - explicit deletion
// manually build a DOM document
// clone the DocumentType object which does not have an owner yet
IDOM_DocumentType* myDocType1;
IDOM_DocumentType* myDocType;
IDOM_Document* myDocument;
IDOM_Node* root;
IDOM_Node* aNode;
myDocType = IDOM_DOMImplementation::getImplementation()->createDocumentType(name, 0, 0);
myDocType1 = (IDOM_DocumentType*) myDocType->cloneNode(false);
myDocument = IDOM_DOMImplementation::getImplementation()->createDocument(0, name, myDocType);
root = myDocument->getDocumentElement();
aNode = myDocument->createElement(anElementname);
root->appendChild(aNode);
// myDocType does not have an owner yet when myDocType1 was cloned.
// thus need to explicitly delete myDocType1
delete myDocType1;
delete myDocType;
delete myDocument;
|  |  |  |  |
 |  |  |  |
// C++ IDOM - explicit deletion
// manually build a DOM document
// clone the DocumentType object that has an owner already
// thus no need to delete the cloned object
IDOM_DocumentType* myDocType1;
IDOM_DocumentType* myDocType;
IDOM_Document* myDocument;
IDOM_Node* root;
IDOM_Node* aNode;
myDocType = IDOM_DOMImplementation::getImplementation()->createDocumentType(name, 0, 0);
myDocument = IDOM_DOMImplementation::getImplementation()->createDocument(0, name, myDocType);
myDocType1 = (IDOM_DocumentType*) myDocType->cloneNode(false);
root = myDocument->getDocumentElement();
aNode = myDocument->createElement(anElementname);
root->appendChild(aNode);
// myDocType already has myDocument as the owner when myDocType1 was cloned
// thus NO need to explicitly delete myDocType1
delete myDocType;
delete myDocument;
|  |  |  |  |
|
Key points to remember when using the C++ IDOM classes:
- The DOM objects are accessed via C++ pointers.
- The DOM objects - nodes, attributes, CData
sections, etc., are created with the factory methods
(create...) in the document class.
- If you are manually building a DOM tree in memory, you
need to explicitly delete the document object.
Memory management will be automatically taken care of by
the IDOM parser when parsing an instance document.
|