You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by tn...@apache.org on 2002/05/21 20:23:26 UTC
cvs commit: xml-xerces/c/doc program-deprecateddom.xml
tng 02/05/21 11:23:26
Added: c/doc program-deprecateddom.xml
Log:
Documentation Update: Old DOM Interface programming guide is moved to program-deprecateddom.xml
Revision Changes Path
1.1 xml-xerces/c/doc/program-deprecateddom.xml
Index: program-deprecateddom.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="Deprecated - Java-like DOM">
<s2 title="Deprecated - Java-like DOM">
<p>Earlier, &XercesCName; has provided a set of C++ DOM interfaces that is
very similar in design and use, to the Java DOM API bindings.
It uses smart pointer interface and uses reference counting in memory management.
</p>
<p>
Currently, such interface has been deprecated and is provided just as a viable
alternative for those users who like the idea of Java-like smart pointer design.
Please note that such interface may not be kept up to date to the latest
W3C DOM specification.
</p>
<p>
Users are recommended to migrate to the
<jump href="ApacheDOMC++Binding.html">Apache Recommended DOM C++ binding</jump>.
</p>
</s2>
<s2 title="Constructing a DOMParser">
<p>In order to use &XercesCName; to parse XML files using the deprecated DOM, you
will need to create an instance of the DOMParser class. The example
below shows the code you need in order to create an instance of the
DOMParser.</p>
<source>
#include <xercesc/dom/deprecated/DOMParser.hpp>
#include <xercesc/dom/deprecated/DOM.hpp>
#include <xercesc/sax/HandlerBase.hpp>
#include <xercesc/util/XMLString.hpp>
int main (int argc, char* args[]) {
try {
XMLPlatformUtils::Initialize();
}
catch (const XMLException& toCatch) {
char* message = XMLString::transcode(toCatch.getMessage());
cout << "Error during initialization! :\n"
<< message << "\n";
delete [] message;
return 1;
}
char* xmlFile = "x1.xml";
DOMParser* parser = new DOMParser();
parser->setValidationScheme(DOMParser::Val_Always); // optional.
parser->setDoNamespaces(true); // optional
ErrorHandler* errHandler = (ErrorHandler*) new HandlerBase();
parser->setErrorHandler(errHandler);
try {
parser->parse(xmlFile);
}
catch (const XMLException& toCatch) {
char* message = XMLString::transcode(toCatch.getMessage());
cout << "Exception message is: \n"
<< message << "\n";
delete [] message;
return -1;
}
catch (const DOM_DOMException& toCatch) {
cout << "Exception message is: \n"
<< toCatch.code << "\n";
return -1;
}
catch (...) {
cout << "Unexpected Exception \n" ;
return -1;
}
delete parser;
delete errHandler;
return 0;
}
</source>
</s2>
<s2 title="Accessing this set of deprecated API">
<source>
// C++
#include <xercesc/dom/deprecated/DOM.hpp></source>
<source>// Compared to Java
import org.w3c.dom.*</source>
<p>The header file <dom/deprecated/DOM.hpp> includes all the
individual headers for this set of deprecated DOM API classes. </p>
</s2>
<s2 title="Class Names">
<p>The C++ class names are prefixed with "DOM_". The intent is
to prevent conflicts between DOM class names and other names
that may already be in use by an application or other
libraries that a DOM based application must link with.</p>
<p>The use of C++ namespaces would also have solved this
conflict problem, but for the fact that many compilers do not
yet support them.</p>
<source>DOM_Document myDocument; // C++
DOM_Node aNode;
DOM_Text someText;</source>
<source>Document myDocument; // Compared to Java
Node aNode;
Text someText;</source>
<p>If you wish to use the Java class names in C++, then you need
to typedef them in C++. This is not advisable for the general
case - conflicts really do occur - but can be very useful when
converting a body of existing Java code to C++.</p>
<source>typedef DOM_Document Document;
typedef DOM_Node Node;
Document myDocument; // Now C++ usage is
// indistinguishable from Java
Node aNode;</source>
</s2>
<s2 title="Objects and Memory Management">
<p>This deprecated C++ DOM implementation uses automatic memory management,
implemented using reference counting. As a result, the C++
code for most DOM operations is very similar to the equivalent
Java code, right down to the use of factory methods in the DOM
document class for nearly all object creation, and the lack of
any explicit object deletion.</p>
<p>Consider the following code snippets </p>
<source>// This is C++
DOM_Node aNode;
aNode = someDocument.createElement("ElementName");
DOM_Node docRootNode = someDoc.getDocumentElement();
docRootNode.AppendChild(aNode);</source>
<source>// This is Java
Node aNode;
aNode = someDocument.createElement("ElementName");
Node docRootNode = someDoc.getDocumentElement();
docRootNode.AppendChild(aNode);</source>
<p>The Java and the C++ are identical on the surface, except for
the class names, and this similarity remains true for most DOM
code. </p>
<p>However, Java and C++ handle objects in somewhat different
ways, making it important to understand a little bit of what
is going on beneath the surface.</p>
<p>In Java, the variable <code>aNode</code> is an object reference ,
essentially a pointer. It is initially == null, and references
an object only after the assignment statement in the second
line of the code.</p>
<p>In C++ the variable <code>aNode</code> is, from the C++ language's
perspective, an actual live object. It is constructed when the
first line of the code executes, and DOM_Node::operator = ()
executes at the second line. The C++ class DOM_Node
essentially a form of a smart-pointer; it implements much of
the behavior of a Java Object Reference variable, and
delegates the DOM behaviors to an implementation class that
lives behind the scenes. </p>
<p>Key points to remember when using the C++ DOM classes:</p>
<ul>
<li>Create them as local variables, or as member variables of
some other class. Never "new" a DOM object into the heap or
make an ordinary C pointer variable to one, as this will
greatly confuse the automatic memory management. </li>
<li>The "real" DOM objects - nodes, attributes, CData
sections, whatever, do live on the heap, are created with the
create... methods on class DOM_Document. DOM_Node and the
other DOM classes serve as reference variables to the
underlying heap objects.</li>
<li>The visible DOM classes may be freely copied (assigned),
passed as parameters to functions, or returned by value from
functions.</li>
<li>Memory management of the underlying DOM heap objects is
automatic, implemented by means of reference counting. So long
as some part of a document can be reached, directly or
indirectly, via reference variables that are still alive in
the application program, the corresponding document data will
stay alive in the heap. When all possible paths of access have
been closed off (all of the application's DOM objects have
gone out of scope) the heap data itself will be automatically
deleted. </li>
<li>There are restrictions on the ability to subclass the DOM
classes. </li>
</ul>
</s2>
<s2 title="DOMString">
<p>Class DOMString provides the mechanism for passing string
data to and from the DOM API. DOMString is not intended to be
a completely general string class, but rather to meet the
specific needs of the DOM API.</p>
<p>The design derives from two primary sources: from the DOM's
CharacterData interface and from class <code>java.lang.string</code>.</p>
<p>Main features are:</p>
<ul>
<li>It stores Unicode text.</li>
<li>Automatic memory management, using reference counting.</li>
<li>DOMStrings are mutable - characters can be inserted,
deleted or appended.</li>
</ul>
<p></p>
<p>When a string is passed into a method of the DOM, when
setting the value of a Node, for example, the string is cloned
so that any subsequent alteration or reuse of the string by
the application will not alter the document contents.
Similarly, when strings from the document are returned to an
application via the DOM API, the string is cloned so that the
document can not be inadvertently altered by subsequent edits
to the string.</p>
<note>The ICU classes are a more general solution to UNICODE
character handling for C++ applications. ICU is an Open
Source Unicode library, available at the <jump
href="http://oss.software.ibm.com/icu/">IBM
DeveloperWorks website</jump>.</note>
</s2>
<s2 title="Equality Testing">
<p>The DOMString equality operators (and all of the rest of the
DOM class conventions) are modeled after the Java
equivalents. The equals() method compares the content of the
string, while the == operator checks whether the string
reference variables (the application program variables) refer
to the same underlying string in memory. This is also true of
DOM_Node, DOM_Element, etc., in that operator == tells whether
the variables in the application are referring to the same
actual node or not. It's all very Java-like </p>
<ul>
<li>bool operator == () is true if the DOMString variables
refer to the same underlying storage. </li>
<li>bool equals() is true if the strings contain the same
characters. </li>
</ul>
<p>Here is an example of how the equality operators work: </p>
<source>DOMString a = "Hello";
DOMString b = a;
DOMString c = a.clone();
if (b == a) // This is true
if (a == c) // This is false
if (a.equals(c)) // This is true
b = b + " World";
if (b == a) // Still true, and the string's
// value is "Hello World"
if (a.equals(c)) // false. a is "Hello World";
// c is still "Hello".</source>
</s2>
<s2 title="Downcasting">
<p>Application code sometimes must cast an object reference from
DOM_Node to one of the classes deriving from DOM_Node,
DOM_Element, for example. The syntax for doing this in C++ is
different from that in Java.</p>
<source>// This is C++
DOM_Node aNode = someFunctionReturningNode();
DOM_Element el = (DOM_Element &) aNode;</source>
<source>// This is Java
Node aNode = someFunctionReturningNode();
Element el = (Element) aNode;</source>
<p>The C++ cast is not type-safe; the Java cast is checked for
compatible types at runtime. If necessary, a type-check can
be made in C++ using the node type information: </p>
<source>// This is C++
DOM_Node aNode = someFunctionReturningNode();
DOM_Element el; // by default, el will == null.
if (anode.getNodeType() == DOM_Node::ELEMENT_NODE)
el = (DOM_Element &) aNode;
else
// aNode does not refer to an element.
// Do something to recover here.</source>
</s2>
<s2 title="Subclassing">
<p>The C++ DOM classes, DOM_Node, DOM_Attr, DOM_Document, etc.,
are not designed to be subclassed by an application
program. </p>
<p>As an alternative, the DOM_Node class provides a User Data
field for use by applications as a hook for extending nodes by
referencing additional data or objects. See the API
description for DOM_Node for details.</p>
</s2>
</s1>
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org