diff --git a/src/xercesc/dom/DOM.hpp b/src/xercesc/dom/DOM.hpp
index 0a5763423745f04fd940b0a6538c2890639ea5d4..6c8ffbd84d37a0809f11a05315590abbba4278fe 100644
--- a/src/xercesc/dom/DOM.hpp
+++ b/src/xercesc/dom/DOM.hpp
@@ -76,9 +76,6 @@
#include <xercesc/dom/DOMElement.hpp>
#include <xercesc/dom/DOMEntity.hpp>
#include <xercesc/dom/DOMEntityReference.hpp>
-#include <xercesc/dom/DOMEntityResolver.hpp>
-#include <xercesc/dom/DOMError.hpp>
-#include <xercesc/dom/DOMErrorHandler.hpp>
#include <xercesc/dom/DOMException.hpp>
#include <xercesc/dom/DOMImplementation.hpp>
#include <xercesc/dom/DOMNamedNodeMap.hpp>
@@ -100,6 +97,9 @@
// Introduced in DOM Level 3
// Experimental - subject to change
#include <xercesc/dom/DOMBuilder.hpp>
+#include <xercesc/dom/DOMEntityResolver.hpp>
+#include <xercesc/dom/DOMError.hpp>
+#include <xercesc/dom/DOMErrorHandler.hpp>
#include <xercesc/dom/DOMImplementationLS.hpp>
#include <xercesc/dom/DOMImplementationRegistry.hpp>
#include <xercesc/dom/DOMImplementationSource.hpp>
diff --git a/src/xercesc/dom/DOMAttr.hpp b/src/xercesc/dom/DOMAttr.hpp
index 7ecdb388e91dc41a90e6997a1410e46ee6eef5e6..634decb711bb6cad9575543df5093af5dae16810 100644
--- a/src/xercesc/dom/DOMAttr.hpp
+++ b/src/xercesc/dom/DOMAttr.hpp
@@ -69,90 +69,107 @@ class DOMElement;
/**
-* The <code>DOMAttr</code> class refers to an attribute of an XML element.
-*
-* Typically the allowable values for the
-* attribute are defined in a documenttype definition.
-* <p><code>DOMAttr</code> objects inherit the <code>DOM_Node</code> interface, but
-* since attributes are not actually child nodes of the elements they are associated with, the
-* DOM does not consider them part of the document tree. Thus, the
-* <code>DOM_Node</code> attributes <code>parentNode</code>,
-* <code>previousSibling</code>, and <code>nextSibling</code> have a null
-* value for <code>DOMAttr</code> objects. The DOM takes the view that
-* attributes are properties of elements rather than having a separate
-* identity from the elements they are associated with; this should make it
-* more efficient to implement such features as default attributes associated
-* with all elements of a given type. Furthermore, attribute nodes
-* may not be immediate children of a <code>DocumentFragment</code>. However,
-* they can be associated with <code>Element</code> nodes contained within a
-* <code>DocumentFragment</code>. In short, users of the DOM
-* need to be aware that <code>Attr</code> nodes have some things in common
-* with other objects inheriting the <code>Node</code> interface, but they
-* also are quite distinct.
-*
-*/
+ * The <code>DOMAttr</code> class refers to an attribute of an XML element.
+ *
+ * Typically the allowable values for the
+ * attribute are defined in a documenttype definition.
+ * <p><code>DOMAttr</code> objects inherit the <code>DOMNode</code> interface, but
+ * since attributes are not actually child nodes of the elements they are associated with, the
+ * DOM does not consider them part of the document tree. Thus, the
+ * <code>DOMNode</code> attributes <code>parentNode</code>,
+ * <code>previousSibling</code>, and <code>nextSibling</code> have a null
+ * value for <code>DOMAttr</code> objects. The DOM takes the view that
+ * attributes are properties of elements rather than having a separate
+ * identity from the elements they are associated with; this should make it
+ * more efficient to implement such features as default attributes associated
+ * with all elements of a given type. Furthermore, attribute nodes
+ * may not be immediate children of a <code>DOMDocumentFragment</code>. However,
+ * they can be associated with <code>DOMElement</code> nodes contained within a
+ * <code>DOMDocumentFragment</code>. In short, users of the DOM
+ * need to be aware that <code>DOMAttr</code> nodes have some things in common
+ * with other objects inheriting the <code>DOMNode</code> interface, but they
+ * also are quite distinct.
+ *
+ * @since DOM Level 1
+ */
class CDOM_EXPORT DOMAttr: public DOMNode {
-
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMAttr() {};
DOMAttr(const DOMAttr &other) {};
DOMAttr & operator = (const DOMAttr &other) {return *this;};
-
+ //@}
public:
- /** @name Destructor */
- //@{
-
- /**
- * Destructor. The object being destroyed is a reference to the Attribute
- * "node", not the underlying attribute itself.
- *
- */
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMAttr() {};
- //@}
+ //@}
- /** @name Getter functions */
- //@{
+ // -----------------------------------------------------------------------
+ // Virtual DOMAttr interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
+ //@{
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
/**
- * Returns the name of this attribute.
- */
+ * Returns the name of this attribute.
+ * @since DOM Level 1
+ */
virtual const XMLCh * getName() const = 0;
/**
- *
- * Returns true if the attribute received its value explicitly in the
- * XML document, or if a value was assigned programatically with
- * the setValue function. Returns false if the attribute value
- * came from the default value declared in the document's DTD.
- */
+ *
+ * Returns true if the attribute received its value explicitly in the
+ * XML document, or if a value was assigned programatically with
+ * the setValue function. Returns false if the attribute value
+ * came from the default value declared in the document's DTD.
+ * @since DOM Level 1
+ */
virtual bool getSpecified() const = 0;
/**
- * Returns the value of the attribute.
- *
- * The value of the attribute is returned as a string.
- * Character and general entity references are replaced with their values.
- */
+ * Returns the value of the attribute.
+ *
+ * The value of the attribute is returned as a string.
+ * Character and general entity references are replaced with their values.
+ * @since DOM Level 1
+ */
virtual const XMLCh * getValue() const = 0;
- //@}
- /** @name Setter functions */
- //@{
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
/**
- * Sets the value of the attribute. A text node with the unparsed contents
- * of the string will be created.
- *
- * @param value The value of the DOM attribute to be set
- */
+ * Sets the value of the attribute. A text node with the unparsed contents
+ * of the string will be created.
+ *
+ * @param value The value of the DOM attribute to be set
+ * @since DOM Level 1
+ */
virtual void setValue(const XMLCh *value) = 0;
- //@}
+ //@}
/** @name Functions introduced in DOM Level 2. */
//@{
/**
- * The <code>DOM_Element</code> node this attribute is attached to or
+ * The <code>DOMElement</code> node this attribute is attached to or
* <code>null</code> if this attribute is not in use.
*
+ * @since DOM Level 2
*/
virtual DOMElement *getOwnerElement() const = 0;
//@}
diff --git a/src/xercesc/dom/DOMBuilder.hpp b/src/xercesc/dom/DOMBuilder.hpp
index af5276952228d59a47824a92a62a9d44b9c15dd0..aaadcfc8886e11ec78330dcdbf404ed1138d3f2d 100644
--- a/src/xercesc/dom/DOMBuilder.hpp
+++ b/src/xercesc/dom/DOMBuilder.hpp
@@ -1,3 +1,6 @@
+#ifndef DOMBuilder_HEADER_GUARD_
+#define DOMBuilder_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
*
@@ -59,9 +62,6 @@
*
*/
-#ifndef DOMBUILDER_HPP
-#define DOMBUILDER_HPP
-
#include <xercesc/util/XercesDefs.hpp>
@@ -72,34 +72,74 @@ class DOMBuilderFilter;
class DOMNode;
class DOMDocument;
- /**
- * Introduced in DOM Level 3
- *
- * DOMBuilder provides an API for parsing XML documents and building the
- * corresponding DOM document tree. A DOMBuilder instance is obtained from
- * the DOMImplementationLS interface by invoking its createDOMBuilder method.
- * This implementation also allows the applications to install an error and
- * an entity handler (useful extensions to the DOM specification).
- *
- */
+/**
+ * DOMBuilder provides an API for parsing XML documents and building the
+ * corresponding DOM document tree. A DOMBuilder instance is obtained from
+ * the DOMImplementationLS interface by invoking its createDOMBuilder method.
+ * This implementation also allows the applications to install an error and
+ * an entity handler (useful extensions to the DOM specification).
+ *
+ * @since DOM Level 3
+ *
+ */
class CDOM_EXPORT DOMBuilder
{
protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
- /** @name Constructors */
+ /** @name Hidden constructors */
//@{
-
- /** Default constructor */
DOMBuilder() {};
+ DOMBuilder(const DOMBuilder &other) {};
+ DOMBuilder & operator = (const DOMBuilder &other) {return *this;};
+ //@}
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMBuilder() {};
//@}
-public :
// -----------------------------------------------------------------------
// Class types
// -----------------------------------------------------------------------
+ /** @name Public Constants */
+ //@{
+ /**
+ * Action types for use in parseWithContext.
+ *
+ * <p> <code>ACTION_REPLACE</code>:
+ * Replace the context node with the result of parsing the input source.
+ * For this action to work the context node must be an
+ * <code>DOMElement</code>, <code>DOMText</code>, <code>DOMCDATASection</code>,
+ * <code>DOMComment</code>, <code>DOMProcessingInstruction</code>, or
+ * <code>DOMEntityReference</code> node.</p>
+ *
+ * <p> <code>ACTION_APPEND</code>:
+ * Append the result of parsing the input source to the context node. For
+ * this action to work, the context node must be an <code>DOMElement</code>.</p>
+ *
+ * <p> <code>ACTION_INSERT_AFTER</code>:
+ * Insert the result of parsing the input source after the context node.
+ * For this action to work the context nodes parent must be an
+ * <code>DOMElement</code>.</p>
+ *
+ * <p> <code>ACTION_INSERT_BEFORE</code>:
+ * Insert the result of parsing the input source before the context node.
+ * For this action to work the context nodes parent must be an
+ * <code>DOMElement</code>.</p>
+ *
+ * @see parseWithContext(...)
+ * @since DOM Level 3
+ */
enum ActionType
{
ACTION_REPLACE = 1,
@@ -107,112 +147,100 @@ public :
ACTION_INSERT_AFTER = 3,
ACTION_INSERT_BEFORE = 4
};
+ //@}
// -----------------------------------------------------------------------
- // All constructors are hidden, just the destructor is available
+ // Virtual DOMBuilder interface
// -----------------------------------------------------------------------
- /** @name Destructor */
+ /** @name Functions introduced in DOM Level 3 */
//@{
- /**
- * Destructor
- *
- */
- virtual ~DOMBuilder() {};
- //@}
-
// -----------------------------------------------------------------------
// Getter methods
// -----------------------------------------------------------------------
- /** @name Getter methods */
- //@{
-
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Get a pointer to the error handler
*
* This method returns the installed error handler. If no handler
* has been installed, then it will be a zero pointer.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @return The pointer to the installed error handler object.
+ * @since DOM Level 3
*/
virtual DOMErrorHandler* getErrorHandler() = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Get a const pointer to the error handler
*
* This method returns the installed error handler. If no handler
* has been installed, then it will be a zero pointer.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @return A const pointer to the installed error handler object.
+ * @since DOM Level 3
*/
virtual const DOMErrorHandler* getErrorHandler() const = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Get a pointer to the entity resolver
*
* This method returns the installed entity resolver. If no resolver
* has been installed, then it will be a zero pointer.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @return The pointer to the installed entity resolver object.
+ * @since DOM Level 3
*/
virtual DOMEntityResolver* getEntityResolver() = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Get a const pointer to the entity resolver
*
* This method returns the installed entity resolver. If no resolver
* has been installed, then it will be a zero pointer.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @return A const pointer to the installed entity resolver object.
+ * @since DOM Level 3
*/
virtual const DOMEntityResolver* getEntityResolver() const = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Get a pointer to the application filter
*
* This method returns the installed application filter. If no filter
* has been installed, then it will be a zero pointer.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @return The pointer to the installed application filter.
+ * @since DOM Level 3
*/
virtual DOMBuilderFilter* getFilter() = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Get a const pointer to the application filter
*
* This method returns the installed application filter. If no filter
* has been installed, then it will be a zero pointer.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @return A const pointer to the installed application filter
+ * @since DOM Level 3
*/
virtual const DOMBuilderFilter* getFilter() const = 0;
- //@}
-
-
// -----------------------------------------------------------------------
// Setter methods
// -----------------------------------------------------------------------
-
- /** @name Setter methods */
- //@{
-
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Set the error handler
*
* This method allows applications to install their own error handler
@@ -221,16 +249,17 @@ public :
* <i>Any previously set handler is merely dropped, since the parser
* does not own them.</i>
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param handler A const pointer to the user supplied error
* handler.
*
* @see #getErrorHandler
+ * @since DOM Level 3
*/
virtual void setErrorHandler(DOMErrorHandler* const handler) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Set the entity resolver
*
* This method allows applications to install their own entity
@@ -241,16 +270,17 @@ public :
* <i>Any previously set resolver is merely dropped, since the parser
* does not own them.</i>
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param handler A const pointer to the user supplied entity
* resolver.
*
* @see #getEntityResolver
+ * @since DOM Level 3
*/
virtual void setEntityResolver(DOMEntityResolver* const handler) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Set the application filter
*
* When the application provides a filter, the parser will call out to
@@ -263,30 +293,27 @@ public :
* <i>Any previously set filter is merely dropped, since the parser
* does not own them.</i>
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param filter A const pointer to the user supplied application
* filter.
*
* @see #getFilter
+ * @since DOM Level 3
*/
virtual void setFilter(DOMBuilderFilter* const filter) = 0;
- //@}
-
-
// -----------------------------------------------------------------------
// Feature methods
// -----------------------------------------------------------------------
- /** @name Feature methods */
- //@{
-
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Set the state of a feature
*
* It is possible for a DOMBuilder to recognize a feature name but to be
* unable to set its value.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param name The feature name.
* @param state The requested state of the feature (true or false).
* @exception DOMException
@@ -297,30 +324,32 @@ public :
*
* @see #setFeature
* @see #canSetFeature
+ * @since DOM Level 3
*/
virtual void setFeature(const XMLCh* const name, const bool state) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Look up the value of a feature.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param name The feature name.
* @return The current state of the feature (true or false)
* @exception DOMException
* NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
- * the feature name.
+ * the feature name.
*
* @see #getFeature
* @see #canSetFeature
+ * @since DOM Level 3
*/
virtual bool getFeature(const XMLCh* const name) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Query whether setting a feature to a specific value is supported.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param name The feature name.
* @param state The requested state of the feature (true or false).
* @return <code>true</code> if the feature could be successfully set
@@ -330,33 +359,29 @@ public :
*
* @see #getFeature
* @see #setFeature
+ * @since DOM Level 3
*/
virtual bool canSetFeature(const XMLCh* const name, const bool state) = 0;
- //@}
-
// -----------------------------------------------------------------------
// Parsing methods
// -----------------------------------------------------------------------
- /** @name Parsing methods */
- //@{
-
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Parse via an input source object
*
* This method invokes the parsing process on the XML file specified
* by the DOMInputSource parameter. This API is borrowed from the
* SAX Parser interface.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param source A const reference to the DOMInputSource object which
* points to the XML file to be parsed.
* @param reuseGrammar The flag indicating whether the existing Grammar
* should be reused or not for this parsing run.
* If true, there cannot be any internal subset.
* @return If the DOMBuilder is a synchronous DOMBuilder the newly created
- * and populated Document is returned. If the DOMBuilder is
+ * and populated DOMDocument is returned. If the DOMBuilder is
* asynchronous then <code>null</code> is returned since the
* document object is not yet parsed when this method returns.
* @exception SAXException Any SAX exception, possibly
@@ -368,24 +393,25 @@ public :
* @see DOMInputSource#DOMInputSource
* @see #setEntityResolver
* @see #setErrorHandler
+ * @since DOM Level 3
*/
virtual DOMDocument* parse(const DOMInputSource& source, const bool reuseGrammar = false) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Parse via a file path or URL
*
* This method invokes the parsing process on the XML file specified by
* the Unicode string parameter 'systemId'.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param systemId A const XMLCh pointer to the Unicode string which
* contains the path to the XML file to be parsed.
* @param reuseGrammar The flag indicating whether the existing Grammar
* should be reused or not for this parsing run.
* If true, there cannot be any internal subset.
* @return If the DOMBuilder is a synchronous DOMBuilder the newly created
- * and populated Document is returned. If the DOMBuilder is
+ * and populated DOMDocument is returned. If the DOMBuilder is
* asynchronous then <code>null</code> is returned since the
* document object is not yet parsed when this method returns.
* @exception SAXException Any SAX exception, possibly
@@ -395,24 +421,25 @@ public :
* @exception DOMException A DOM exception as per DOM spec.
*
* @see #parse(DOMInputSource,...)
+ * @since DOM Level 3
*/
virtual DOMDocument* parseURI(const XMLCh* const systemId, const bool reuseGrammar = false) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Parse via a file path or URL (in the local code page)
*
* This method invokes the parsing process on the XML file specified by
* the native char* string parameter 'systemId'.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param systemId A const char pointer to a native string which
* contains the path to the XML file to be parsed.
* @param reuseGrammar The flag indicating whether the existing Grammar
* should be reused or not for this parsing run.
* If true, there cannot be any internal subset.
* @return If the DOMBuilder is a synchronous DOMBuilder the newly created
- * and populated Document is returned. If the DOMBuilder is
+ * and populated DOMDocument is returned. If the DOMBuilder is
* asynchronous then <code>null</code> is returned since the
* document object is not yet parsed when this method returns.
* @exception SAXException Any SAX exception, possibly
@@ -426,8 +453,6 @@ public :
virtual DOMDocument* parseURI(const char* const systemId, const bool reuseGrammar = false) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Parse via an input source object
*
* This method invokes the parsing process on the XML file specified
@@ -436,6 +461,8 @@ public :
* and action arguments. When parsing the input stream the context node
* is used for resolving unbound namespace prefixes.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param source A const reference to the DOMInputSource object which
* points to the XML file to be parsed.
* @param contextNode The node that is used as the context for the data
@@ -451,6 +478,7 @@ public :
* this method.
* <br>NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is
* readonly.
+ * @since DOM Level 3
*/
virtual void parseWithContext
(
@@ -458,13 +486,8 @@ public :
, DOMNode* const contextNode
, const short action
) = 0;
+ //@}
-private :
- // -----------------------------------------------------------------------
- // Unimplemented constructors and operators
- // -----------------------------------------------------------------------
- DOMBuilder(const DOMBuilder&);
- void operator=(const DOMBuilder&);
};
diff --git a/src/xercesc/dom/DOMCDATASection.hpp b/src/xercesc/dom/DOMCDATASection.hpp
index 0a2d53a962970908db849f02ecbae0d2df85f2fa..02e43c1efada428949dba6fd7ca375c83d203615 100644
--- a/src/xercesc/dom/DOMCDATASection.hpp
+++ b/src/xercesc/dom/DOMCDATASection.hpp
@@ -67,28 +67,63 @@
/**
- * <code>DOM_CDataSection</code> objects refer to the data from an
- * XML CDATA section. These are used to escape blocks of text containing characters
- * that would otherwise be regarded as markup.
+ * CDATA sections are used to escape blocks of text containing characters that
+ * would otherwise be regarded as markup. The only delimiter that is
+ * recognized in a CDATA section is the "]]>" string that ends the CDATA
+ * section. CDATA sections cannot be nested. Their primary purpose is for
+ * including material such as XML fragments, without needing to escape all
+ * the delimiters.
+ * <p>The <code>data</code> attribute of the <code>DOMText</code> node holds
+ * the text that is contained by the CDATA section. Note that this may
+ * contain characters that need to be escaped outside of CDATA sections and
+ * that, depending on the character encoding ("charset") chosen for
+ * serialization, it may be impossible to write out some characters as part
+ * of a CDATA section.
+ * <p>The <code>DOMCDATASection</code> interface inherits from the
+ * <code>DOMCharacterData</code> interface through the <code>DOMText</code>
+ * interface. Adjacent <code>DOMCDATASection</code> nodes are not merged by use
+ * of the <code>normalize</code> method of the <code>DOMNode</code> interface.
+ * Because no markup is recognized within a <code>DOMCDATASection</code>,
+ * character numeric references cannot be used as an escape mechanism when
+ * serializing. Therefore, action needs to be taken when serializing a
+ * <code>DOMCDATASection</code> with a character encoding where some of the
+ * contained characters cannot be represented. Failure to do so would not
+ * produce well-formed XML.One potential solution in the serialization
+ * process is to end the CDATA section before the character, output the
+ * character using a character reference or entity reference, and open a new
+ * CDATA section for any further characters in the text node. Note, however,
+ * that some code conversion libraries at the time of writing do not return
+ * an error or exception when a character is missing from the encoding,
+ * making the task of ensuring that data is not corrupted on serialization
+ * more difficult.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
*
- * <p>Note that the string data associated with the CDATA section may
- * contain characters that need to be escaped when appearing in an
- * XML document outside of a CDATA section.
- * <p> The <code>DOMCDATASection</code> class inherits from the
- * <code>DOM_CharacterData</code> class through the <code>Text</code>
- * interface. Adjacent CDATASection nodes are not merged by use
- * of the Element.normalize() method.
+ * @since DOM Level 1
*/
class CDOM_EXPORT DOMCDATASection: public DOMText {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMCDATASection() {};
DOMCDATASection(const DOMCDATASection &other) {};
DOMCDATASection & operator = (const DOMCDATASection &other) {return *this;};
-
+ //@}
public:
-
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMCDATASection() {};
+ //@}
};
#endif
diff --git a/src/xercesc/dom/DOMCharacterData.hpp b/src/xercesc/dom/DOMCharacterData.hpp
index dc9a65080b0c6a6759ccfc57b2aea0d3e2031049..a220ed4c3d5ba1508002ff6aa969c3934f82ea98 100644
--- a/src/xercesc/dom/DOMCharacterData.hpp
+++ b/src/xercesc/dom/DOMCharacterData.hpp
@@ -1,3 +1,6 @@
+#ifndef DOMCharacterData_HEADER_GUARD_
+#define DOMCharacterData_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
*
@@ -58,152 +61,179 @@
* $Id$
*/
-#ifndef DOMCharacterData_HEADER_GUARD_
-#define DOMCharacterData_HEADER_GUARD_
-
#include <xercesc/util/XercesDefs.hpp>
#include <xercesc/dom/DOMNode.hpp>
/**
- * The <code>DOMCharacterData</code> interface extends Node with a set of
- * methods for accessing character data in the DOM.
- *
- * For clarity this set is defined here rather than on each class that uses
- * these methods. No DOM objects correspond directly to
- * <code>CharacterData</code>, though <code>Text</code> and others do inherit
- * the interface from it. All <code>offset</code>s in this interface start
- * from 0, and index in terms of Unicode 16 bit storage units.
+ * The <code>DOMCharacterData</code> interface extends DOMNode with a set of
+ * attributes and methods for accessing character data in the DOM. For
+ * clarity this set is defined here rather than on each object that uses
+ * these attributes and methods. No DOM objects correspond directly to
+ * <code>DOMCharacterData</code>, though <code>DOMText</code> and others do
+ * inherit the interface from it. All <code>offsets</code> in this interface
+ * start from <code>0</code>.
+ * <p>As explained in the DOM spec, text strings in
+ * the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In
+ * the following, the term 16-bit units is used whenever necessary to
+ * indicate that indexing on DOMCharacterData is done in 16-bit units.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
*/
class CDOM_EXPORT DOMCharacterData: public DOMNode {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMCharacterData() {};
DOMCharacterData(const DOMCharacterData &other) {};
DOMCharacterData & operator = (const DOMCharacterData &other) {return *this;};
+ //@}
public:
- /** @name Destructor. */
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
//@{
- /**
- * Destructor for DOMCharacterData. The object being destroyed
- * is the reference to the Character Data node, not the character
- * data itself.
- */
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMCharacterData() {};
-
-
//@}
- /** @name Getter functions. */
+ // -----------------------------------------------------------------------
+ // Virtual DOMCharacterData interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
//@{
- /**
- * Returns the character data of the node that implements this interface.
- *
- * The DOM implementation may not put arbitrary limits on the amount of data that
- * may be stored in a <code>CharacterData</code> node. However,
- * implementation limits may mean that the entirety of a node's data may
- * not fit into a single <code>XMLCh* String</code>. In such cases, the user
- * may call <code>substringData</code> to retrieve the data in
- * appropriately sized pieces.
- * @exception DOMException
- * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
- */
- virtual const XMLCh * getData() const = 0;
- /**
- * Returns the number of characters that are available through <code>data</code> and
- * the <code>substringData</code> method below.
- *
- * This may have the value
- * zero, i.e., <code>CharacterData</code> nodes may be empty.
- */
- virtual XMLSize_t getLength() const = 0;
- /**
- * Extracts a range of data from the node.
- *
- * @param offset Start offset of substring to extract.
- * @param count The number of characters to extract.
- * @return The specified substring. If the sum of <code>offset</code> and
- * <code>count</code> exceeds the <code>length</code>, then all
- * characters to the end of the data are returned.
- * @exception DOMException
- * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
- * than the number of characters in <code>data</code>, or if the
- * specified <code>count</code> is negative.
- */
- virtual const XMLCh * substringData(XMLSize_t offset,
- XMLSize_t count) const = 0;
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
+ /**
+ * Returns the character data of the node that implements this interface.
+ *
+ * The DOM implementation may not put arbitrary limits on the amount of data that
+ * may be stored in a <code>DOMCharacterData</code> node. However,
+ * implementation limits may mean that the entirety of a node's data may
+ * not fit into a single <code>XMLCh* String</code>. In such cases, the user
+ * may call <code>substringData</code> to retrieve the data in
+ * appropriately sized pieces.
+ * @exception DOMException
+ * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
+ * @since DOM Level 1
+ */
+ virtual const XMLCh * getData() const = 0;
+
+ /**
+ * Returns the number of characters that are available through <code>data</code> and
+ * the <code>substringData</code> method below.
+ *
+ * This may have the value
+ * zero, i.e., <code>CharacterData</code> nodes may be empty.
+ * @since DOM Level 1
+ */
+ virtual XMLSize_t getLength() const = 0;
+
+ /**
+ * Extracts a range of data from the node.
+ *
+ * @param offset Start offset of substring to extract.
+ * @param count The number of characters to extract.
+ * @return The specified substring. If the sum of <code>offset</code> and
+ * <code>count</code> exceeds the <code>length</code>, then all
+ * characters to the end of the data are returned.
+ * @exception DOMException
+ * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
+ * than the number of characters in <code>data</code>, or if the
+ * specified <code>count</code> is negative.
+ * @since DOM Level 1
+ */
+ virtual const XMLCh * substringData(XMLSize_t offset,
+ XMLSize_t count) const = 0;
+
+ // -----------------------------------------------------------------------
+ // String methods
+ // -----------------------------------------------------------------------
+ /**
+ * Append the string to the end of the character data of the node.
+ *
+ * Upon success, <code>data</code> provides access to the concatenation of
+ * <code>data</code> and the <code>XMLCh* String</code> specified.
+ * @param arg The <code>XMLCh* String</code> to append.
+ * @exception DOMException
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * @since DOM Level 1
+ */
+ virtual void appendData(const XMLCh *arg) = 0;
+
+ /**
+ * Insert a string at the specified character offset.
+ *
+ * @param offset The character offset at which to insert.
+ * @param arg The <code>XMLCh* String</code> to insert.
+ * @exception DOMException
+ * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
+ * than the number of characters in <code>data</code>.
+ * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * @since DOM Level 1
+ */
+ virtual void insertData(XMLSize_t offset, const XMLCh *arg) = 0;
+
+ /**
+ * Remove a range of characters from the node.
+ *
+ * Upon success,
+ * <code>data</code> and <code>length</code> reflect the change.
+ * @param offset The offset from which to remove characters.
+ * @param count The number of characters to delete. If the sum of
+ * <code>offset</code> and <code>count</code> exceeds <code>length</code>
+ * then all characters from <code>offset</code> to the end of the data
+ * are deleted.
+ * @exception DOMException
+ * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
+ * than the number of characters in <code>data</code>, or if the
+ * specified <code>count</code> is negative.
+ * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * @since DOM Level 1
+ */
+ virtual void deleteData(XMLSize_t offset,
+ XMLSize_t count) = 0;
+
+ /**
+ * Replace the characters starting at the specified character offset with
+ * the specified string.
+ *
+ * @param offset The offset from which to start replacing.
+ * @param count The number of characters to replace. If the sum of
+ * <code>offset</code> and <code>count</code> exceeds <code>length</code>
+ * , then all characters to the end of the data are replaced (i.e., the
+ * effect is the same as a <code>remove</code> method call with the same
+ * range, followed by an <code>append</code> method invocation).
+ * @param arg The <code>XMLCh* String</code> with which the range must be
+ * replaced.
+ * @exception DOMException
+ * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
+ * than the number of characters in <code>data</code>, or if the
+ * specified <code>count</code> is negative.
+ * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * @since DOM Level 1
+ */
+ virtual void replaceData(XMLSize_t offset,
+ XMLSize_t count,
+ const XMLCh *arg) = 0;
+
+ /**
+ * Sets the character data of the node that implements this interface.
+ *
+ * @param data The <code>XMLCh* String</code> to set.
+ * @since DOM Level 1
+ */
+ virtual void setData(const XMLCh *data) = 0;
//@}
- /** @name Functions that set or change data. */
- //@{
- /**
- * Append the string to the end of the character data of the node.
- *
- * Upon success, <code>data</code> provides access to the concatenation of
- * <code>data</code> and the <code>XMLCh* String</code> specified.
- * @param arg The <code>XMLCh* String</code> to append.
- * @exception DOMException
- * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- */
- virtual void appendData(const XMLCh *arg) = 0;
- /**
- * Insert a string at the specified character offset.
- *
- * @param offset The character offset at which to insert.
- * @param arg The <code>XMLCh* String</code> to insert.
- * @exception DOMException
- * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
- * than the number of characters in <code>data</code>.
- * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- */
- virtual void insertData(XMLSize_t offset, const XMLCh *arg) = 0;
- /**
- * Remove a range of characters from the node.
- *
- * Upon success,
- * <code>data</code> and <code>length</code> reflect the change.
- * @param offset The offset from which to remove characters.
- * @param count The number of characters to delete. If the sum of
- * <code>offset</code> and <code>count</code> exceeds <code>length</code>
- * then all characters from <code>offset</code> to the end of the data
- * are deleted.
- * @exception DOMException
- * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
- * than the number of characters in <code>data</code>, or if the
- * specified <code>count</code> is negative.
- * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- */
- virtual void deleteData(XMLSize_t offset,
- XMLSize_t count) = 0;
- /**
- * Replace the characters starting at the specified character offset with
- * the specified string.
- *
- * @param offset The offset from which to start replacing.
- * @param count The number of characters to replace. If the sum of
- * <code>offset</code> and <code>count</code> exceeds <code>length</code>
- * , then all characters to the end of the data are replaced (i.e., the
- * effect is the same as a <code>remove</code> method call with the same
- * range, followed by an <code>append</code> method invocation).
- * @param arg The <code>XMLCh* String</code> with which the range must be
- * replaced.
- * @exception DOMException
- * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
- * than the number of characters in <code>data</code>, or if the
- * specified <code>count</code> is negative.
- * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- */
- virtual void replaceData(XMLSize_t offset,
- XMLSize_t count,
- const XMLCh *arg) = 0;
-
- /**
- * Sets the character data of the node that implements this interface.
- *
- * @param data The <code>XMLCh* String</code> to set.
- */
- virtual void setData(const XMLCh *data) = 0;
- //@}
};
diff --git a/src/xercesc/dom/DOMComment.hpp b/src/xercesc/dom/DOMComment.hpp
index f6b16ace69b9ecf6328ed050f30c2cbb47bce77c..0cdce6b36606d8fdc08ed69eeb184e26864c0c50 100644
--- a/src/xercesc/dom/DOMComment.hpp
+++ b/src/xercesc/dom/DOMComment.hpp
@@ -65,23 +65,39 @@
#include <xercesc/util/XercesDefs.hpp>
#include "DOMCharacterData.hpp"
-
/**
- * Class to refer to XML comment nodes in the DOM.
+ * This interface inherits from <code>CharacterData</code> and represents the
+ * content of a comment, i.e., all the characters between the starting '
+ * <code><!--</code>' and ending '<code>--></code>'.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
*
- * <P>The string value contains all of the characters between
- * the starting '<code><!--</code>' and ending '<code>--></code>'.
+ * @since DOM Level 1
*/
class CDOM_EXPORT DOMComment: public DOMCharacterData {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMComment() {};
DOMComment(const DOMComment &other) {};
DOMComment & operator = (const DOMComment &other) {return *this;};
+ //@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMComment() {};
-
+ //@}
};
#endif
diff --git a/src/xercesc/dom/DOMDocument.hpp b/src/xercesc/dom/DOMDocument.hpp
index 7a612fadec2803e3b75f2da89060455b1620dcad..0cd999dfd95a85b6157bfa4a0c8aa0302dd09844 100644
--- a/src/xercesc/dom/DOMDocument.hpp
+++ b/src/xercesc/dom/DOMDocument.hpp
@@ -67,8 +67,6 @@
#include "DOMDocumentTraversal.hpp"
-class DOMNodeIteratorImpl;
-
class DOMDocumentType;
class DOMElement;
class DOMDocumentFragment;
@@ -87,233 +85,198 @@ class DOMNode;
/**
-* Class to refer to XML Document nodes in the DOM.
-*
-* Conceptually, a DOM document node is the root of the document tree, and provides
-* the primary access to the document's data.
-* <p>Since elements, text nodes, comments, processing instructions, etc.
-* cannot exist outside the context of a <code>Document</code>, the
-* <code>Document</code> interface also contains the factory methods needed
-* to create these objects. The <code>Node</code> objects created have a
-* <code>ownerDocument</code> attribute which associates them with the
-* <code>Document</code> within whose context they were created.
-*/
+ * The <code>DOMDocument</code> interface represents the entire XML
+ * document. Conceptually, it is the root of the document tree, and provides
+ * the primary access to the document's data.
+ * <p>Since elements, text nodes, comments, processing instructions, etc.
+ * cannot exist outside the context of a <code>DOMDocument</code>, the
+ * <code>DOMDocument</code> interface also contains the factory methods needed
+ * to create these objects. The <code>DOMNode</code> objects created have a
+ * <code>ownerDocument</code> attribute which associates them with the
+ * <code>DOMDocument</code> within whose context they were created.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
+ */
+
class CDOM_EXPORT DOMDocument: public DOMDocumentRange,
public DOMDocumentTraversal,
public DOMNode {
protected:
- /** @name Constructors and assignment operators */
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
//@{
- /**
- * The default constructor for DOMDocument creates a null
- * DOMDocument object that refers to no document. It may subsequently be
- * assigned to refer to an actual Document node.
- *
- * To create a new document, use the DOMImplementation
- * <code> DOMImplementation::createDocument(). </code>
- *
- */
DOMDocument() {};
-
- /**
- * Copy constructor. Creates a new <code>DOMDocument</code> that refers to the
- * same underlying actual document as the original.
- *
- * @param other The object to be copied
- */
DOMDocument(const DOMDocument &other) {};
- /**
- * Assignment operator
- *
- * @param other The object to be copied
- */
DOMDocument & operator = (const DOMDocument &other) {return *this;};
-
-
- //@}
+ //@}
public:
- /** @name Destructor */
- //@{
-
- virtual ~DOMDocument() {};
-
- //@}
- /** @name Factory methods to create new nodes for the Document */
- //@{
-
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
/**
- * Create a new entity.
- *
- * Non-standard extension.
- * @param name The name of the entity to instantiate
- *
- */
- virtual DOMEntity *createEntity(const XMLCh *name) = 0;
+ * Destructor
+ *
+ */
+ virtual ~DOMDocument() {};
+ //@}
+ // -----------------------------------------------------------------------
+ // Virtual DOMDocument interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
+ //@{
/**
- * Creates an element of the type specified.
- *
- * Note that the instance returned
- * implements the Element interface, so attributes can be specified
- * directly on the returned object.
- * @param tagName The name of the element type to instantiate.
- * @return A <code>DOMElement</code> that reference the new element.
- * @exception DOMException
- * INVALID_CHARACTER_ERR: Raised if the specified name contains an
- * illegal character.
- */
+ * Creates an element of the type specified. Note that the instance
+ * returned implements the <code>DOMElement</code> interface, so attributes
+ * can be specified directly on the returned object.
+ * <br>In addition, if there are known attributes with default values,
+ * <code>DOMAttr</code> nodes representing them are automatically created
+ * and attached to the element.
+ * <br>To create an element with a qualified name and namespace URI, use
+ * the <code>createElementNS</code> method.
+ * @param tagName The name of the element type to instantiate. For XML,
+ * this is case-sensitive.
+ * @return A new <code>DOMElement</code> object with the
+ * <code>nodeName</code> attribute set to <code>tagName</code>, and
+ * <code>localName</code>, <code>prefix</code>, and
+ * <code>namespaceURI</code> set to <code>null</code>.
+ * @exception DOMException
+ * INVALID_CHARACTER_ERR: Raised if the specified name contains an
+ * illegal character.
+ * @since DOM Level 1
+ */
virtual DOMElement *createElement(const XMLCh *tagName) = 0;
-
-
/**
- * Creates an empty DocumentFragment object.
- *
- * @return A <code>DOMDocumentFragment</code> that references the newly
- * created document fragment.
- */
+ * Creates an empty <code>DOMDocumentFragment</code> object.
+ * @return A new <code>DOMDocumentFragment</code>.
+ * @since DOM Level 1
+ */
virtual DOMDocumentFragment *createDocumentFragment() = 0;
/**
- * Creates a Text node given the specified string.
- *
- * @param data The data for the node.
- * @return A <code>DOMText</code> object that references the newly
- * created text node.
- */
+ * Creates a <code>DOMText</code> node given the specified string.
+ * @param data The data for the node.
+ * @return The new <code>DOMText</code> object.
+ * @since DOM Level 1
+ */
virtual DOMText *createTextNode(const XMLCh *data) = 0;
/**
- * Creates a Comment node given the specified string.
- *
- * @param data The data for the comment.
- * @return A <code>DOMComment</code> that references the newly
- * created comment node.
- */
+ * Creates a <code>DOMComment</code> node given the specified string.
+ * @param data The data for the node.
+ * @return The new <code>DOMComment</code> object.
+ * @since DOM Level 1
+ */
virtual DOMComment *createComment(const XMLCh *data) = 0;
/**
- * Creates a CDATASection node whose value is the specified
- * string.
- *
- * @param data The data for the <code>DOMCDATASection</code> contents.
- * @return A <code>DOMCDATASection</code> object.
- * @exception DOMException
- * NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
- */
+ * Creates a <code>DOMCDATASection</code> node whose value is the specified
+ * string.
+ * @param data The data for the <code>DOMCDATASection</code> contents.
+ * @return The new <code>DOMCDATASection</code> object.
+ * @since DOM Level 1
+ */
virtual DOMCDATASection *createCDATASection(const XMLCh *data) = 0;
/**
- * Create a DocumentType node. Non-standard extension.
- *
- * @return A <code>DOMDocumentType</code> that references the newly
- * created DocumentType node.
- *
- */
- virtual DOMDocumentType *createDocumentType(const XMLCh *name) = 0;
-
-
- /**
- * Create a Notation.
- *
- * Non-standard extension.
- *
- * @param name The name of the notation to instantiate
- * @return A <code>DOMNotation</code> that references the newly
- * created Notation node.
- */
- virtual DOMNotation *createNotation(const XMLCh *name) = 0;
-
-
- /**
- * Creates a ProcessingInstruction node given the specified
- * name and data strings.
- *
- * @param target The target part of the processing instruction.
- * @param data The data for the node.
- * @return A <code>DOMProcessingInstruction</code> that references the newly
- * created PI node.
- * @exception DOMException
- * INVALID_CHARACTER_ERR: Raised if an illegal character is specified.
- */
+ * Creates a <code>DOMProcessingInstruction</code> node given the specified
+ * name and data strings.
+ * @param target The target part of the processing instruction.
+ * @param data The data for the node.
+ * @return The new <code>DOMProcessingInstruction</code> object.
+ * @exception DOMException
+ * INVALID_CHARACTER_ERR: Raised if the specified target contains an
+ * illegal character.
+ * @since DOM Level 1
+ */
virtual DOMProcessingInstruction *createProcessingInstruction(const XMLCh *target,
const XMLCh *data) = 0;
/**
- * Creates an Attr of the given name.
- *
- * Note that the
- * <code>Attr</code> instance can then be attached to an Element
- * using the <code>DOMElement::setAttribute()</code> method.
+ * Creates an <code>DOMAttr</code> of the given name. Note that the
+ * <code>DOMAttr</code> instance can then be set on an <code>DOMElement</code>
+ * using the <code>setAttributeNode</code> method.
+ * <br>To create an attribute with a qualified name and namespace URI, use
+ * the <code>createAttributeNS</code> method.
* @param name The name of the attribute.
- * @return A new <CODE>DOMAttr</CODE>
- * object with the <CODE>nodeName</CODE> attribute set to
- * <CODE>name</CODE>, and <CODE>localName</CODE>, <CODE>prefix</CODE>,
- * and <CODE>namespaceURI</CODE> set to
- * <CODE>null</CODE>.
+ * @return A new <code>DOMAttr</code> object with the <code>nodeName</code>
+ * attribute set to <code>name</code>, and <code>localName</code>,
+ * <code>prefix</code>, and <code>namespaceURI</code> set to
+ * <code>null</code>. The value of the attribute is the empty string.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified name contains an
* illegal character.
+ * @since DOM Level 1
*/
virtual DOMAttr *createAttribute(const XMLCh *name) = 0;
/**
- * Creates an EntityReference object.
- *
+ * Creates an <code>DOMEntityReference</code> object. In addition, if the
+ * referenced entity is known, the child list of the
+ * <code>DOMEntityReference</code> node is made the same as that of the
+ * corresponding <code>DOMEntity</code> node.If any descendant of the
+ * <code>DOMEntity</code> node has an unbound namespace prefix, the
+ * corresponding descendant of the created <code>DOMEntityReference</code>
+ * node is also unbound; (its <code>namespaceURI</code> is
+ * <code>null</code>). The DOM Level 2 does not support any mechanism to
+ * resolve namespace prefixes.
* @param name The name of the entity to reference.
- * @return A <code>DOMEntityReference</code> that references the newly
- * created EntityReference node.
+ * @return The new <code>DOMEntityReference</code> object.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified name contains an
* illegal character.
+ * @since DOM Level 1
*/
virtual DOMEntityReference *createEntityReference(const XMLCh *name) = 0;
-
- //@}
- /** @name Getter functions */
- //@{
/**
- * Get Document Type Declaration (see <code>DOMDocumentType</code>) associated
- * with this document.
- *
- * For documents without
- * a document type declaration this returns <code>null</code> reference object. The DOM Level
- * 1 does not support editing the Document Type Declaration, therefore
- * <code>docType</code> cannot be altered in any way.
+ * The Document Type Declaration (see <code>DOMDocumentType</code>)
+ * associated with this document. For XML
+ * documents without a document type declaration this returns
+ * <code>null</code>. The DOM Level 2 does not support editing the
+ * Document Type Declaration. <code>docType</code> cannot be altered in
+ * any way, including through the use of methods inherited from the
+ * <code>DOMNode</code> interface, such as <code>insertNode</code> or
+ * <code>removeNode</code>.
+ * @since DOM Level 1
*/
virtual DOMDocumentType *getDoctype() const = 0;
-
-
/**
- * Return the <code>DOMImplementation</code> object that handles this document.
+ * The <code>DOMImplementation</code> object that handles this document. A
+ * DOM application may use objects from multiple implementations.
+ * @since DOM Level 1
*/
virtual DOMImplementation *getImplementation() const = 0;
-
/**
- * Return a reference to the root element of the document.
+ * This is a convenience attribute that allows direct access to the child
+ * node that is the root element of the document.
+ * @since DOM Level 1
*/
virtual DOMElement *getDocumentElement() const = 0;
/**
- * Returns a <code>DOMNodeList</code> of all the elements with a
- * given tag name. The returned node list is "live", in that changes
+ * Returns a <code>DOMNodeList</code> of all the <code>DOMElement(s)</code> with a
+ * given tag name in the order in which they are encountered in a
+ * preorder traversal of the <code>DOMDocument</code> tree.
+ *
+ * The returned node list is "live", in that changes
* to the document tree made after a nodelist was initially
* returned will be immediately reflected in the node list.
- *
- * The elements in the node list are ordered in the same order in which they
- * would be encountered in a
- * preorder traversal of the <code>Document</code> tree.
* @param tagname The name of the tag to match on. The special value "*"
* matches all tags.
- * @return A reference to a NodeList containing all the matched
- * <code>Element</code>s.
+ * @return A new <code>DOMNodeList</code> object containing all the matched
+ * <code>DOMElement(s)</code>.
+ * @since DOM Level 1
*/
virtual DOMNodeList *getElementsByTagName(const XMLCh *tagname) const = 0;
@@ -322,145 +285,312 @@ public:
//@{
/**
- * Imports a node from another document to this document.
- * The returned node has no parent (<CODE>parentNode</CODE> is
- * <CODE>null</CODE>). The source node is not altered or removed from the
- * original document; this method creates a new copy of the source
- * node.<BR>For all nodes, importing a node creates a node object owned by
- * the importing document, with attribute values identical to the source
- * node's <CODE>nodeName</CODE> and <CODE>nodeType</CODE>, plus the
- * attributes related to namespaces (prefix and namespaces URI).
- *
+ * Imports a node from another document to this document. The returned
+ * node has no parent; (<code>parentNode</code> is <code>null</code>).
+ * The source node is not altered or removed from the original document;
+ * this method creates a new copy of the source node.
+ * <br>For all nodes, importing a node creates a node object owned by the
+ * importing document, with attribute values identical to the source
+ * node's <code>nodeName</code> and <code>nodeType</code>, plus the
+ * attributes related to namespaces (<code>prefix</code>,
+ * <code>localName</code>, and <code>namespaceURI</code>). As in the
+ * <code>cloneNode</code> operation on a <code>DOMNode</code>, the source
+ * node is not altered.
+ * <br>Additional information is copied as appropriate to the
+ * <code>nodeType</code>, attempting to mirror the behavior expected if
+ * a fragment of XML source was copied from one document to
+ * another, recognizing that the two documents may have different DTDs
+ * in the XML case. The following list describes the specifics for each
+ * type of node.
+ * <dl>
+ * <dt>ATTRIBUTE_NODE</dt>
+ * <dd>The <code>ownerElement</code> attribute
+ * is set to <code>null</code> and the <code>specified</code> flag is
+ * set to <code>true</code> on the generated <code>DOMAttr</code>. The
+ * descendants of the source <code>DOMAttr</code> are recursively imported
+ * and the resulting nodes reassembled to form the corresponding subtree.
+ * Note that the <code>deep</code> parameter has no effect on
+ * <code>DOMAttr</code> nodes; they always carry their children with them
+ * when imported.</dd>
+ * <dt>DOCUMENT_FRAGMENT_NODE</dt>
+ * <dd>If the <code>deep</code> option
+ * was set to <code>true</code>, the descendants of the source element
+ * are recursively imported and the resulting nodes reassembled to form
+ * the corresponding subtree. Otherwise, this simply generates an empty
+ * <code>DOMDocumentFragment</code>.</dd>
+ * <dt>DOCUMENT_NODE</dt>
+ * <dd><code>DOMDocument</code>
+ * nodes cannot be imported.</dd>
+ * <dt>DOCUMENT_TYPE_NODE</dt>
+ * <dd><code>DOMDocumentType</code>
+ * nodes cannot be imported.</dd>
+ * <dt>ELEMENT_NODE</dt>
+ * <dd>Specified attribute nodes of the
+ * source element are imported, and the generated <code>DOMAttr</code>
+ * nodes are attached to the generated <code>DOMElement</code>. Default
+ * attributes are not copied, though if the document being imported into
+ * defines default attributes for this element name, those are assigned.
+ * If the <code>importNode</code> <code>deep</code> parameter was set to
+ * <code>true</code>, the descendants of the source element are
+ * recursively imported and the resulting nodes reassembled to form the
+ * corresponding subtree.</dd>
+ * <dt>ENTITY_NODE</dt>
+ * <dd><code>DOMEntity</code> nodes can be
+ * imported, however in the current release of the DOM the
+ * <code>DOMDocumentType</code> is readonly. Ability to add these imported
+ * nodes to a <code>DOMDocumentType</code> will be considered for addition
+ * to a future release of the DOM.On import, the <code>publicId</code>,
+ * <code>systemId</code>, and <code>notationName</code> attributes are
+ * copied. If a <code>deep</code> import is requested, the descendants
+ * of the the source <code>DOMEntity</code> are recursively imported and
+ * the resulting nodes reassembled to form the corresponding subtree.</dd>
+ * <dt>
+ * ENTITY_REFERENCE_NODE</dt>
+ * <dd>Only the <code>DOMEntityReference</code> itself is
+ * copied, even if a <code>deep</code> import is requested, since the
+ * source and destination documents might have defined the entity
+ * differently. If the document being imported into provides a
+ * definition for this entity name, its value is assigned.</dd>
+ * <dt>NOTATION_NODE</dt>
+ * <dd>
+ * <code>DOMNotation</code> nodes can be imported, however in the current
+ * release of the DOM the <code>DOMDocumentType</code> is readonly. Ability
+ * to add these imported nodes to a <code>DOMDocumentType</code> will be
+ * considered for addition to a future release of the DOM.On import, the
+ * <code>publicId</code> and <code>systemId</code> attributes are copied.
+ * Note that the <code>deep</code> parameter has no effect on
+ * <code>DOMNotation</code> nodes since they never have any children.</dd>
+ * <dt>
+ * PROCESSING_INSTRUCTION_NODE</dt>
+ * <dd>The imported node copies its
+ * <code>target</code> and <code>data</code> values from those of the
+ * source node.</dd>
+ * <dt>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE</dt>
+ * <dd>These three
+ * types of nodes inheriting from <code>DOMCharacterData</code> copy their
+ * <code>data</code> and <code>length</code> attributes from those of
+ * the source node.</dd>
+ * </dl>
* @param importedNode The node to import.
- * @param deep If <CODE>true</CODE>, recursively import the subtree under the
- * specified node; if <CODE>false</CODE>, import only the node itself,
- * as explained above. This does not apply to <CODE>DOMAttr</CODE>,
- * <CODE>DOMEntityReference</CODE>, and <CODE>DOMNotation</CODE> nodes.
- * @return The imported node that belongs to this <CODE>DOMDocument</CODE>.
+ * @param deep If <code>true</code>, recursively import the subtree under
+ * the specified node; if <code>false</code>, import only the node
+ * itself, as explained above. This has no effect on <code>DOMAttr</code>
+ * , <code>DOMEntityReference</code>, and <code>DOMNotation</code> nodes.
+ * @return The imported node that belongs to this <code>DOMDocument</code>.
* @exception DOMException
- * NOT_SUPPORTED_ERR: Raised if the type of node being imported is
- * not supported.
+ * NOT_SUPPORTED_ERR: Raised if the type of node being imported is not
+ * supported.
+ * @since DOM Level 2
*/
virtual DOMNode *importNode(DOMNode *importedNode, bool deep) = 0;
/**
- * Creates an element of the given qualified name and
- * namespace URI.
- *
- * @param namespaceURI The <em>namespace URI</em> of
- * the element to create.
- * @param qualifiedName The <em>qualified name</em>
- * of the element type to instantiate.
- * @return A new <code>DOMElement</code> object.
+ * Creates an element of the given qualified name and namespace URI.
+ * @param namespaceURI The namespace URI of the element to create.
+ * @param qualifiedName The qualified name of the element type to
+ * instantiate.
+ * @return A new <code>DOMElement</code> object with the following
+ * attributes:
+ * <table border='1'>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>Attribute</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>Value</code></td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.nodeName</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>qualifiedName</code></td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.namespaceURI</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>namespaceURI</code></td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.prefix</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>prefix, extracted
+ * from <code>qualifiedName</code>, or <code>null</code> if there is
+ * no prefix</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.localName</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>local name, extracted from
+ * <code>qualifiedName</code></td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>DOMElement.tagName</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>qualifiedName</code></td>
+ * </tr>
+ * </table>
* @exception DOMException
- * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains
- * an illegal character.
- * <br>
- * NAMESPACE_ERR: Raised if the <CODE>qualifiedName</CODE> is
- * malformed, if the <CODE>qualifiedName</CODE> has a prefix and the
- * <CODE>namespaceURI</CODE> is <CODE>null</CODE> or an empty string,
- * or if the <CODE>qualifiedName</CODE> has a prefix that is "xml" and
- * the <CODE>namespaceURI</CODE> is different from
- * "http://www.w3.org/XML/1998/namespace".
+ * INVALID_CHARACTER_ERR: Raised if the specified qualified name
+ * contains an illegal character, per the XML 1.0 specification .
+ * <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
+ * malformed per the Namespaces in XML specification, if the
+ * <code>qualifiedName</code> has a prefix and the
+ * <code>namespaceURI</code> is <code>null</code>, or if the
+ * <code>qualifiedName</code> has a prefix that is "xml" and the
+ * <code>namespaceURI</code> is different from "
+ * http://www.w3.org/XML/1998/namespace" .
+ * <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
+ * support the <code>"XML"</code> feature, since namespaces were
+ * defined by XML.
+ * @since DOM Level 2
*/
virtual DOMElement *createElementNS(const XMLCh *namespaceURI,
const XMLCh *qualifiedName) = 0;
/**
- * Creates an element of the given qualified name and
- * namespace URI, and also stores line/column number info.
- * Non standard. Used by XSDXercesDOMParser during schema traversal.
- *
- * @param namespaceURI The <em>namespace URI</em> of
- * the element to create.
- * @param qualifiedName The <em>qualified name</em>
- * of the element type to instantiate.
- * @param lineNum The <em>line number</em> of the element to create.
- * @param columnNum The <em>column number</em> of the element to create.
- * @return A new <code>DOMElement</code> object.
+ * Creates an attribute of the given qualified name and namespace URI.
+ * @param namespaceURI The namespace URI of the attribute to create.
+ * @param qualifiedName The qualified name of the attribute to
+ * instantiate.
+ * @return A new <code>DOMAttr</code> object with the following attributes:
+ * <table border='1'>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>Attribute</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>Value</code></td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.nodeName</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>qualifiedName</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>DOMNode.namespaceURI</code></td>
+ * <td valign='top' rowspan='1' colspan='1'><code>namespaceURI</code></td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>DOMNode.prefix</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>prefix, extracted from
+ * <code>qualifiedName</code>, or <code>null</code> if there is no
+ * prefix</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.localName</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>local name, extracted from
+ * <code>qualifiedName</code></td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>DOMAttr.name</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>qualifiedName</code></td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.nodeValue</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>the empty
+ * string</td>
+ * </tr>
+ * </table>
* @exception DOMException
- * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains
- * an illegal character.
- * <br>
- * NAMESPACE_ERR: Raised if the <CODE>qualifiedName</CODE> is
- * malformed, if the <CODE>qualifiedName</CODE> has a prefix and the
- * <CODE>namespaceURI</CODE> is <CODE>null</CODE> or an empty string,
- * or if the <CODE>qualifiedName</CODE> has a prefix that is "xml" and
- * the <CODE>namespaceURI</CODE> is different from
- * "http://www.w3.org/XML/1998/namespace".
- */
- virtual DOMElement *createElementNS(const XMLCh *namespaceURI,
- const XMLCh *qualifiedName,
- const XMLSSize_t lineNum,
- const XMLSSize_t columnNum) = 0;
-
- /**
- * Creates an attribute of the given qualified name and namespace
- * URI.
- *
- * @param namespaceURI The <em>namespace URI</em> of
- * the attribute to create.
- * @param qualifiedName The <em>qualified name</em>
- * of the attribute to instantiate.
- * @return A new <code>DOMAttr</code> object.
- * @exception DOMException
- * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains
- * an illegal character.
- * <br>
- * NAMESPACE_ERR: Raised if the <CODE>qualifiedName</CODE> is
- * malformed, if the <CODE>qualifiedName</CODE> has a prefix and the
- * <CODE>namespaceURI</CODE> is <CODE>null</CODE> or an empty string,
- * if the <CODE>qualifiedName</CODE> has a prefix that is "xml" and the
- * <CODE>namespaceURI</CODE> is different from
- * "http://www.w3.org/XML/1998/namespace", if the
- * <CODE>qualifiedName</CODE> has a prefix that is "xmlns" and the
- * <CODE>namespaceURI</CODE> is different from
- * "http://www.w3.org/2000/xmlns/", or if the
- * <CODE>qualifiedName</CODE> is "xmlns" and the
- * <CODE>namespaceURI</CODE> is different from
- * "http://www.w3.org/2000/xmlns/".
+ * INVALID_CHARACTER_ERR: Raised if the specified qualified name
+ * contains an illegal character, per the XML 1.0 specification .
+ * <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
+ * malformed per the Namespaces in XML specification, if the
+ * <code>qualifiedName</code> has a prefix and the
+ * <code>namespaceURI</code> is <code>null</code>, if the
+ * <code>qualifiedName</code> has a prefix that is "xml" and the
+ * <code>namespaceURI</code> is different from "
+ * http://www.w3.org/XML/1998/namespace", or if the
+ * <code>qualifiedName</code>, or its prefix, is "xmlns" and the
+ * <code>namespaceURI</code> is different from "
+ * http://www.w3.org/2000/xmlns/".
+ * <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
+ * support the <code>"XML"</code> feature, since namespaces were
+ * defined by XML.
+ * @since DOM Level 2
*/
virtual DOMAttr *createAttributeNS(const XMLCh *namespaceURI,
const XMLCh *qualifiedName) = 0;
/**
- * Returns a <code>DOMNodeList</code> of all the <code>DOMElement</code>s
- * with a given <em>local name</em> and
- * namespace URI in the order in which they would be encountered in a
- * preorder traversal of the <code>DOMDocument</code> tree.
- *
- * @param namespaceURI The <em>namespace URI</em> of
- * the elements to match on. The special value "*" matches all
- * namespaces.
- * @param localName The <em>local name</em> of the
- * elements to match on. The special value "*" matches all local names.
+ * Returns a <code>DOMNodeList</code> of all the <code>DOMElement(s)</code> with a
+ * given local name and namespace URI in the order in which they are
+ * encountered in a preorder traversal of the <code>DOMDocument</code> tree.
+ * @param namespaceURI The namespace URI of the elements to match on. The
+ * special value "*" matches all namespaces.
+ * @param localName The local name of the elements to match on. The
+ * special value "*" matches all local names.
* @return A new <code>DOMNodeList</code> object containing all the matched
- * <code>DOMElement</code>s.
+ * <code>DOMElement(s)</code>.
+ * @since DOM Level 2
*/
virtual DOMNodeList *getElementsByTagNameNS(const XMLCh *namespaceURI,
const XMLCh *localName) const = 0;
/**
- * Returns the <code>DOMElement</code> whose ID is given by <code>elementId</code>.
- * If no such element exists, returns <code>null</code>.
- * Behavior is not defined if more than one element has this <code>ID</code>.
- * <P><B>Note:</B> The DOM implementation must have information that says
- * which attributes are of type ID. Attributes with the name "ID" are not of
- * type ID unless so defined. Implementations that do not know whether
- * attributes are of type ID or not are expected to return
- * <CODE>null</CODE>.</P>
- *
+ * Returns the <code>DOMElement</code> whose <code>ID</code> is given by
+ * <code>elementId</code>. If no such element exists, returns
+ * <code>null</code>. Behavior is not defined if more than one element
+ * has this <code>ID</code>. The DOM implementation must have
+ * information that says which attributes are of type ID. Attributes
+ * with the name "ID" are not of type ID unless so defined.
+ * Implementations that do not know whether attributes are of type ID or
+ * not are expected to return <code>null</code>.
* @param elementId The unique <code>id</code> value for an element.
* @return The matching element.
+ * @since DOM Level 2
*/
virtual DOMElement * getElementById(const XMLCh *elementId) const = 0;
//@}
+ // -----------------------------------------------------------------------
+ // Non-standard extension
+ // -----------------------------------------------------------------------
+ /** @name Non-standard extension */
+ //@{
+ /**
+ * Non-standard extension
+ *
+ * Create a new entity.
+ * @param name The name of the entity to instantiate
+ *
+ */
+ virtual DOMEntity *createEntity(const XMLCh *name) = 0;
+
+ /**
+ * Non-standard extension
+ *
+ * Create a DOMDocumentType node.
+ * @return A <code>DOMDocumentType</code> that references the newly
+ * created DOMDocumentType node.
+ *
+ */
+ virtual DOMDocumentType *createDocumentType(const XMLCh *name) = 0;
+
+
+ /**
+ * Non-standard extension.
+ *
+ * Create a Notation.
+ * @param name The name of the notation to instantiate
+ * @return A <code>DOMNotation</code> that references the newly
+ * created DOMNotation node.
+ */
+ virtual DOMNotation *createNotation(const XMLCh *name) = 0;
+
+ /**
+ * Non-standard extension.
+ *
+ * Creates an element of the given qualified name and
+ * namespace URI, and also stores line/column number info.
+ * Used by internally XSDXercesDOMParser during schema traversal.
+ *
+ * @see createElementNS(const XMLCh *namespaceURI, const XMLCh *qualifiedName)
+ */
+ virtual DOMElement *createElementNS(const XMLCh *namespaceURI,
+ const XMLCh *qualifiedName,
+ const XMLSSize_t lineNum,
+ const XMLSSize_t columnNum) = 0;
+ //@}
+
protected:
friend class DOMNode;
- friend class DocumentImpl;
- friend class NodeIteratorImpl;
friend class DOMImplementation;
};
diff --git a/src/xercesc/dom/DOMDocumentFragment.hpp b/src/xercesc/dom/DOMDocumentFragment.hpp
index 934a97809506d1ddbb88438117c79c66b2ce48e2..bc2122c76f9f012140408c809576d6a2c3a217af 100644
--- a/src/xercesc/dom/DOMDocumentFragment.hpp
+++ b/src/xercesc/dom/DOMDocumentFragment.hpp
@@ -67,55 +67,68 @@
/**
- * <code>DocumentFragment</code> is a "lightweight" or "minimal"
- * <code>Document</code> object.
+ * OMDocumentFragment is a "lightweight" or "minimal"
+ * DOMDocument object.
*
* It is very common to want to be able to
* extract a portion of a document's tree or to create a new fragment of a
* document. Imagine implementing a user command like cut or rearranging a
* document by moving fragments around. It is desirable to have an object
- * which can hold such fragments and it is quite natural to use a Node for
- * this purpose. While it is true that a <code>Document</code> object could
- * fulfil this role, a <code>Document</code> object can potentially be a
+ * which can hold such fragments and it is quite natural to use a DOMNode for
+ * this purpose. While it is true that a <code>DOMDocument</code> object could
+ * fulfil this role, a <code>DOMDocument</code> object can potentially be a
* heavyweight object, depending on the underlying implementation. What is
* really needed for this is a very lightweight object.
- * <code>DocumentFragment</code> is such an object.
+ * <code>DOMDocumentFragment</code> is such an object.
* <p>Furthermore, various operations -- such as inserting nodes as children
- * of another <code>Node</code> -- may take <code>DocumentFragment</code>
+ * of another <code>DOMNode</code> -- may take <code>DOMDocumentFragment</code>
* objects as arguments; this results in all the child nodes of the
- * <code>DocumentFragment</code> being moved to the child list of this node.
- * <p>The children of a <code>DocumentFragment</code> node are zero or more
+ * <code>DOMDocumentFragment</code> being moved to the child list of this node.
+ * <p>The children of a <code>DOMDocumentFragment</code> node are zero or more
* nodes representing the tops of any sub-trees defining the structure of the
- * document. <code>DocumentFragment</code> nodes do not need to be
+ * document. <code>DOMDocumentFragment</code> nodes do not need to be
* well-formed XML documents (although they do need to follow the rules
* imposed upon well-formed XML parsed entities, which can have multiple top
- * nodes). For example, a <code>DocumentFragment</code> might have only one
- * child and that child node could be a <code>Text</code> node. Such a
+ * nodes). For example, a <code>DOMDocumentFragment</code> might have only one
+ * child and that child node could be a <code>DOMText</code> node. Such a
* structure model represents neither an HTML document nor a well-formed XML
* document.
- * <p>When a <code>DocumentFragment</code> is inserted into a
- * <code>Document</code> (or indeed any other <code>Node</code> that may take
- * children) the children of the <code>DocumentFragment</code> and not the
- * <code>DocumentFragment</code> itself are inserted into the
- * <code>Node</code>. This makes the <code>DocumentFragment</code> very
+ * <p>When a <code>DOMDocumentFragment</code> is inserted into a
+ * <code>DOMDocument</code> (or indeed any other <code>DOMNode</code> that may take
+ * children) the children of the <code>DOMDocumentFragment</code> and not the
+ * <code>DOMDocumentFragment</code> itself are inserted into the
+ * <code>DOMNode</code>. This makes the <code>DOMDocumentFragment</code> very
* useful when the user wishes to create nodes that are siblings; the
- * <code>DocumentFragment</code> acts as the parent of these nodes so that the
- * user can use the standard methods from the <code>Node</code> interface,
+ * <code>DOMDocumentFragment</code> acts as the parent of these nodes so that the
+ * user can use the standard methods from the <code>DOMNode</code> interface,
* such as <code>insertBefore()</code> and <code>appendChild()</code>.
+ *
+ * @since DOM Level 1
*/
class CDOM_EXPORT DOMDocumentFragment: public DOMNode {
-
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMDocumentFragment() {};
DOMDocumentFragment(const DOMDocumentFragment &other) {};
DOMDocumentFragment & operator = (const DOMDocumentFragment &other) {return *this;};
+ //@}
+
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
/** @name Destructor */
//@{
-
-public:
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMDocumentFragment() {};
-
//@}
};
diff --git a/src/xercesc/dom/DOMDocumentRange.hpp b/src/xercesc/dom/DOMDocumentRange.hpp
index 1672748d10bec39b7d5e289b4b645b001fdb82dc..f4ca41d24460b4a15f7f9b19fc3466d58a6ee6a6 100644
--- a/src/xercesc/dom/DOMDocumentRange.hpp
+++ b/src/xercesc/dom/DOMDocumentRange.hpp
@@ -73,25 +73,44 @@ class DOMRange;
class CDOM_EXPORT DOMDocumentRange {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMDocumentRange() {};
DOMDocumentRange(const DOMDocumentRange &other) {};
DOMDocumentRange & operator = (const DOMDocumentRange &other) {return *this;};
+ //@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMDocumentRange() {};
+ //@}
- /** @name Factory methods to create new nodes for the Document */
- //@{
-
+ // -----------------------------------------------------------------------
+ // Virtual DOMDocumentRange interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 2 */
+ //@{
/**
* To create the range consisting of boundary-points and offset of the
- * selected contents
- *
- * @return The initial state of the Range such that both the boundary-points
- * are positioned at the beginning of the corresponding DOMDOcument, before
- * any content. The range returned can only be used to select content
- * associated with this document, or with documentFragments and Attrs for
- * which this document is the ownerdocument
+ * selected contents
+ *
+ * @return The initial state of the Range such that both the boundary-points
+ * are positioned at the beginning of the corresponding DOMDOcument, before
+ * any content. The range returned can only be used to select content
+ * associated with this document, or with documentFragments and Attrs for
+ * which this document is the ownerdocument
+ * @since DOM Level 2
*/
virtual DOMRange *createRange() = 0;
diff --git a/src/xercesc/dom/DOMDocumentTraversal.hpp b/src/xercesc/dom/DOMDocumentTraversal.hpp
index 7c4439ef6ec5f9e9451d3e45a389cf0c6212e7cc..5f592401cbfaa8886aaf4dd08bbd5f6e6cf17142 100644
--- a/src/xercesc/dom/DOMDocumentTraversal.hpp
+++ b/src/xercesc/dom/DOMDocumentTraversal.hpp
@@ -70,29 +70,47 @@ class DOMTreeWalker;
/**
- * <code>DocumentTraversal</code> contains methods that create
- * <code>NodeIterators</code> and <code>TreeWalkers</code> to traverse a
+ * <code>DOMDocumentTraversal</code> contains methods that create
+ * <code>DOMNodeIterators</code> and <code>DOMTreeWalkers</code> to traverse a
* node and its children in document order (depth first, pre-order
* traversal, which is equivalent to the order in which the start tags occur
* in the text representation of the document). In DOMs which support the
- * Traversal feature, <code>DocumentTraversal</code> will be implemented by
- * the same objects that implement the Document interface.
+ * Traversal feature, <code>DOMDocumentTraversal</code> will be implemented by
+ * the same objects that implement the DOMDocument interface.
* <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.
* @since DOM Level 2
*/
class CDOM_EXPORT DOMDocumentTraversal {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMDocumentTraversal() {};
DOMDocumentTraversal(const DOMDocumentTraversal &other) {};
DOMDocumentTraversal & operator = (const DOMDocumentTraversal &other) {return *this;};
+ //@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMDocumentTraversal() {};
+ //@}
- /** @name Factory methods to create new nodes for the Document */
- //@{
-
+ // -----------------------------------------------------------------------
+ // Virtual DOMDocumentRange interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 2 */
+ //@{
/**
* Creates a NodeIterator object. (DOM2)
*
@@ -100,7 +118,7 @@ public:
* document subtree governed by a particular node, the results of a query, or any other set of nodes.
* The set of nodes to be iterated is determined by the implementation of the NodeIterator. DOM Level 2
* specifies a single NodeIterator implementation for document-order traversal of a document subtree.
- * Instances of these iterators are created by calling <code>DocumentTraversal.createNodeIterator()</code>.
+ * Instances of these iterators are created by calling <code>DOMDocumentTraversal.createNodeIterator()</code>.
*
* To produce a view of the document that has entity references expanded and does not
* expose the entity reference node itself, use the <code>whatToShow</code> flags to hide the entity
@@ -114,13 +132,14 @@ public:
* @param filter The filter used to screen nodes
* @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are
* visible to the iterator. If false, they will be skipped over.
+ * @since DOM Level 2
*/
virtual DOMNodeIterator *createNodeIterator(DOMNode *root,
unsigned long whatToShow,
DOMNodeFilter* filter,
bool entityReferenceExpansion) = 0;
- /**
+ /**
* Creates a TreeWalker object. (DOM2)
*
* TreeWalker objects are used to navigate a document tree or subtree using the view of the document defined
@@ -130,7 +149,7 @@ public:
* Omitting nodes from the logical view of a subtree can result in a structure that is substantially different from
* the same subtree in the complete, unfiltered document. Nodes that are siblings in the TreeWalker view may
* be children of different, widely separated nodes in the original view. For instance, consider a Filter that skips
- * all nodes except for Text nodes and the root node of a document. In the logical view that results, all text
+ * all nodes except for DOMText nodes and the root node of a document. In the logical view that results, all text
* nodes will be siblings and appear as direct children of the root node, no matter how deeply nested the
* structure of the original document.
*
@@ -147,6 +166,7 @@ public:
* @param filter The filter used to screen nodes
* @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are
* visible to the tree-walker. If false, they will be skipped over.
+ * @since DOM Level 2
*/
virtual DOMTreeWalker *createTreeWalker(DOMNode *root,
diff --git a/src/xercesc/dom/DOMDocumentType.hpp b/src/xercesc/dom/DOMDocumentType.hpp
index 220804d5a127bcad24fe03c3c345018071ce1373..eb638fb652d171b29b4512688a2a2140f67fc939 100644
--- a/src/xercesc/dom/DOMDocumentType.hpp
+++ b/src/xercesc/dom/DOMDocumentType.hpp
@@ -68,54 +68,86 @@
class DOMNamedNodeMap;
/**
- * Each <code>Document</code> has a <code>doctype</code> whose value
- * is either <code>null</code> or a <code>DocumentType</code> object.
+ * Each <code>DOMDocument</code> has a <code>doctype</code> attribute whose value
+ * is either <code>null</code> or a <code>DOMDocumentType</code> object. The
+ * <code>DOMDocumentType</code> interface in the DOM Core provides an interface
+ * to the list of entities that are defined for the document, and little
+ * else because the effect of namespaces and the various XML schema efforts
+ * on DTD representation are not clearly understood as of this writing.
+ * <p>The DOM Level 2 doesn't support editing <code>DOMDocumentType</code> nodes.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
*
- * The <code>DOMDocumentType</code> class provides access
- * to the list of entities and notations that are defined for the document.
- * <p>The DOM Level 1 doesn't support editing <code>DocumentType</code> nodes.
+ * @since DOM Level 1
*/
class CDOM_EXPORT DOMDocumentType: public DOMNode {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMDocumentType() {};
DOMDocumentType(const DOMDocumentType &other) {};
DOMDocumentType & operator = (const DOMDocumentType &other) {return *this;};
+ //@}
public:
-
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMDocumentType() {};
+ //@}
+ // -----------------------------------------------------------------------
+ // Virtual DOMDocumentType interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
+ //@{
+ /**
+ * The name of DTD; i.e., the name immediately following the
+ * <code>DOCTYPE</code> keyword.
+ *
+ * @since DOM Level 1
+ */
+ virtual const XMLCh * getName() const = 0;
+ /**
+ * A <code>DOMNamedNodeMap</code> containing the general entities, both
+ * external and internal, declared in the DTD. Parameter entities are
+ * not contained. Duplicates are discarded. For example in:
+ * <pre><!DOCTYPE
+ * ex SYSTEM "ex.dtd" [ <!ENTITY foo "foo"> <!ENTITY bar
+ * "bar"> <!ENTITY bar "bar2"> <!ENTITY % baz "baz">
+ * ]> <ex/></pre>
+ * the interface provides access to <code>foo</code>
+ * and the first declaration of <code>bar</code> but not the second
+ * declaration of <code>bar</code> or <code>baz</code>. Every node in
+ * this map also implements the <code>DOMEntity</code> interface.
+ * <br>The DOM Level 2 does not support editing entities, therefore
+ * <code>entities</code> cannot be altered in any way.
+ *
+ * @since DOM Level 1
+ */
+ virtual DOMNamedNodeMap *getEntities() const = 0;
- /** @name Getter functions. */
- //@{
- /**
- * The name of DTD; i.e., the name immediately following the
- * <code>DOCTYPE</code> keyword in an XML source document.
- */
- virtual const XMLCh * getName() const = 0;
-
- /**
- * This function returns a <code>NamedNodeMap</code> containing the general entities, both
- * external and internal, declared in the DTD. Parameter entities are not contained.
- * Duplicates are discarded.
- * <p>
- * Note: this functionality is not implemented in the initial release
- * of the parser, and the returned NamedNodeMap will be empty.
- */
- virtual DOMNamedNodeMap *getEntities() const = 0;
-
-
- /**
- * This function returns a named node map containing an entry for
- * each notation declared in a document's DTD. Duplicates are discarded.
- *
- * <p>
- * Note: this functionality is not implemented in the initial release
- * of the parser, and the returned NamedNodeMap will be empty.
- */
- virtual DOMNamedNodeMap *getNotations() const = 0;
- //@}
+
+ /**
+ * A <code>DOMNamedNodeMap</code> containing the notations declared in the
+ * DTD. Duplicates are discarded. Every node in this map also implements
+ * the <code>DOMNotation</code> interface.
+ * <br>The DOM Level 2 does not support editing notations, therefore
+ * <code>notations</code> cannot be altered in any way.
+ *
+ * @since DOM Level 1
+ */
+ virtual DOMNamedNodeMap *getNotations() const = 0;
+ //@}
/** @name Functions introduced in DOM Level 2. */
//@{
@@ -123,6 +155,7 @@ public:
* Get the public identifier of the external subset.
*
* @return The public identifier of the external subset.
+ * @since DOM Level 2
*/
virtual const XMLCh * getPublicId() const = 0;
@@ -130,13 +163,19 @@ public:
* Get the system identifier of the external subset.
*
* @return The system identifier of the external subset.
+ * @since DOM Level 2
*/
virtual const XMLCh * getSystemId() const = 0;
/**
- * Get the internal subset as a string.
+ * The internal subset as a string, or <code>null</code> if there is none.
+ * This is does not contain the delimiting square brackets.The actual
+ * content returned depends on how much information is available to the
+ * implementation. This may vary depending on various parameters,
+ * including the XML processor used to build the document.
*
* @return The internal subset as a string.
+ * @since DOM Level 2
*/
virtual const XMLCh * getInternalSubset() const = 0;
//@}
diff --git a/src/xercesc/dom/DOMElement.hpp b/src/xercesc/dom/DOMElement.hpp
index 6860abe1b418aeac7ca318794ad301126c6f1d46..c4bbb652b1c91264405d8f62d4d4a3349e3ae64a 100644
--- a/src/xercesc/dom/DOMElement.hpp
+++ b/src/xercesc/dom/DOMElement.hpp
@@ -91,279 +91,298 @@ class DOMNodeList;
* attribute value. On the other hand, in HTML, where all attributes have
* simple string values, methods to directly access an attribute value can
* safely be used as a convenience.
+ *
+ * @since DOM Level 1
*/
class CDOM_EXPORT DOMElement: public DOMNode {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMElement() {};
DOMElement(const DOMElement &other) {};
DOMElement & operator = (const DOMElement &other) {return *this;};
+ //@}
public:
- /** @name Constructors and assignment operator */
- //@{
-
-
-
- //@}
- /** @name Destructor. */
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
//@{
- /**
- * Destructor. The object being destroyed is the reference
- * object, not the underlying Element itself.
- *
- */
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMElement() {};
//@}
- /** @name Getter functions. */
- //@{
- /**
- * The name of the element.
- *
- * For example, in: <elementExample
- * id="demo"> ... </elementExample> , <code>tagName</code> has
- * the value <code>"elementExample"</code>. Note that this is
- * case-preserving in XML, as are all of the operations of the DOM.
- */
- virtual const XMLCh * getTagName() const = 0;
-
- /**
- * Retrieves an attribute value by name.
- *
- * @param name The name of the attribute to retrieve.
- * @return The <code>DOMAttr</code> value as a string, or the empty string if
- * that attribute does not have a specified or default value.
- */
- virtual const XMLCh * getAttribute(const XMLCh *name) const = 0;
-
- /**
- * Retrieves an <code>DOMAttr</code> node by name.
- *
- * @param name The name (<CODE>nodeName</CODE>) of the attribute to retrieve.
- * @return The <code>DOMAttr</code> node with the specified name (<CODE>nodeName</CODE>) or
- * <code>null</code> if there is no such attribute.
- */
- virtual DOMAttr * getAttributeNode(const XMLCh *name) const = 0;
+ // -----------------------------------------------------------------------
+ // Virtual DOMElement interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
+ //@{
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
+ /**
+ * The name of the element.
+ *
+ * For example, in: <elementExample
+ * id="demo"> ... </elementExample> , <code>tagName</code> has
+ * the value <code>"elementExample"</code>. Note that this is
+ * case-preserving in XML, as are all of the operations of the DOM.
+ * @since DOM Level 1
+ */
+ virtual const XMLCh * getTagName() const = 0;
- /**
- * Returns a <code>NodeList</code> of all descendant elements with a given
- * tag name, in the order in which they would be encountered in a preorder
- * traversal of the <code>DOMElement</code> tree.
- *
- * @param name The name of the tag to match on. The special value "*"
- * matches all tags.
- * @return A list of matching <code>DOMElement</code> nodes.
- */
- virtual DOMNodeList * getElementsByTagName(const XMLCh *name) const = 0;
+ /**
+ * Retrieves an attribute value by name.
+ *
+ * @param name The name of the attribute to retrieve.
+ * @return The <code>DOMAttr</code> value as a string, or the empty string if
+ * that attribute does not have a specified or default value.
+ * @since DOM Level 1
+ */
+ virtual const XMLCh * getAttribute(const XMLCh *name) const = 0;
- //@}
- /** @name Set functions. */
- //@{
+ /**
+ * Retrieves an <code>DOMAttr</code> node by name.
+ *
+ * @param name The name (<CODE>nodeName</CODE>) of the attribute to retrieve.
+ * @return The <code>DOMAttr</code> node with the specified name (<CODE>nodeName</CODE>) or
+ * <code>null</code> if there is no such attribute.
+ * @since DOM Level 1
+ */
+ virtual DOMAttr * getAttributeNode(const XMLCh *name) const = 0;
- /**
- * Adds a new attribute.
- *
- * If an attribute with that name is already present
- * in the element, its value is changed to be that of the value parameter.
- * This value is a simple string, it is not parsed as it is being set. So
- * any markup (such as syntax to be recognized as an entity reference) is
- * treated as literal text, and needs to be appropriately escaped by the
- * implementation when it is written out. In order to assign an attribute
- * value that contains entity references, the user must create an
- * <code>DOMAttr</code> node plus any <code>Text</code> and
- * <code>EntityReference</code> nodes, build the appropriate subtree, and
- * use <code>setAttributeNode</code> to assign it as the value of an
- * attribute.
- * @param name The name of the attribute to create or alter.
- * @param value Value to set in string form.
- * @exception DOMException
- * INVALID_CHARACTER_ERR: Raised if the specified name contains an
- * illegal character.
- * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- */
- virtual void setAttribute(const XMLCh *name,
- const XMLCh *value) = 0;
- /**
- * Adds a new attribute.
- *
- * If an attribute with that name (<CODE>nodeName</CODE>) is already present
- * in the element, it is replaced by the new one.
- * @param newAttr The <code>DOMAttr</code> node to add to the attribute list.
- * @return If the <code>newAttr</code> attribute replaces an existing
- * attribute, the replaced
- * <code>DOMAttr</code> node is returned, otherwise <code>null</code> is
- * returned.
- * @exception DOMException
- * WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a
- * different document than the one that created the element.
- * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
- * attribute of another <code>DOMElement</code> object. The DOM user must
- * explicitly clone <code>DOMAttr</code> nodes to re-use them in other
- * elements.
- */
- virtual DOMAttr * setAttributeNode(DOMAttr *newAttr) = 0;
+ /**
+ * Returns a <code>DOMNodeList</code> of all descendant elements with a given
+ * tag name, in the order in which they would be encountered in a preorder
+ * traversal of the <code>DOMElement</code> tree.
+ *
+ * @param name The name of the tag to match on. The special value "*"
+ * matches all tags.
+ * @return A list of matching <code>DOMElement</code> nodes.
+ * @since DOM Level 1
+ */
+ virtual DOMNodeList * getElementsByTagName(const XMLCh *name) const = 0;
- //@}
- /** @name Functions which modify the Element. */
- //@{
- /**
- * Removes the specified attribute node.
- * If the removed <CODE>DOMAttr</CODE>
- * has a default value it is immediately replaced. The replacing attribute
- * has the same namespace URI and local name, as well as the original prefix,
- * when applicable.
- *
- * @param oldAttr The <code>DOMAttr</code> node to remove from the attribute
- * list.
- * @return The <code>DOMAttr</code> node that was removed.
- * @exception DOMException
- * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- * <br>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute
- * of the element.
- */
- virtual DOMAttr * removeAttributeNode(DOMAttr *oldAttr) = 0;
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
+ /**
+ * Adds a new attribute.
+ *
+ * If an attribute with that name is already present
+ * in the element, its value is changed to be that of the value parameter.
+ * This value is a simple string, it is not parsed as it is being set. So
+ * any markup (such as syntax to be recognized as an entity reference) is
+ * treated as literal text, and needs to be appropriately escaped by the
+ * implementation when it is written out. In order to assign an attribute
+ * value that contains entity references, the user must create an
+ * <code>DOMAttr</code> node plus any <code>DOMText</code> and
+ * <code>DOMEntityReference</code> nodes, build the appropriate subtree, and
+ * use <code>setAttributeNode</code> to assign it as the value of an
+ * attribute.
+ * @param name The name of the attribute to create or alter.
+ * @param value Value to set in string form.
+ * @exception DOMException
+ * INVALID_CHARACTER_ERR: Raised if the specified name contains an
+ * illegal character.
+ * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * @since DOM Level 1
+ */
+ virtual void setAttribute(const XMLCh *name,
+ const XMLCh *value) = 0;
+ /**
+ * Adds a new attribute.
+ *
+ * If an attribute with that name (<CODE>nodeName</CODE>) is already present
+ * in the element, it is replaced by the new one.
+ * @param newAttr The <code>DOMAttr</code> node to add to the attribute list.
+ * @return If the <code>newAttr</code> attribute replaces an existing
+ * attribute, the replaced
+ * <code>DOMAttr</code> node is returned, otherwise <code>null</code> is
+ * returned.
+ * @exception DOMException
+ * WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a
+ * different document than the one that created the element.
+ * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
+ * attribute of another <code>DOMElement</code> object. The DOM user must
+ * explicitly clone <code>DOMAttr</code> nodes to re-use them in other
+ * elements.
+ * @since DOM Level 1
+ */
+ virtual DOMAttr * setAttributeNode(DOMAttr *newAttr) = 0;
- /**
- * Removes an attribute by name.
- *
- * If the removed attribute
- * is known to have a default value, an attribute immediately appears
- * containing the default value as well as the corresponding namespace URI,
- * local name, and prefix when applicable.<BR>To remove an attribute by local
- * name and namespace URI, use the <CODE>removeAttributeNS</CODE> method.
- * @param name The name of the attribute to remove.
- * @exception DOMException
- * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- */
- virtual void removeAttribute(const XMLCh *name) = 0;
+ /**
+ * Removes the specified attribute node.
+ * If the removed <CODE>DOMAttr</CODE>
+ * has a default value it is immediately replaced. The replacing attribute
+ * has the same namespace URI and local name, as well as the original prefix,
+ * when applicable.
+ *
+ * @param oldAttr The <code>DOMAttr</code> node to remove from the attribute
+ * list.
+ * @return The <code>DOMAttr</code> node that was removed.
+ * @exception DOMException
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * <br>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute
+ * of the element.
+ * @since DOM Level 1
+ */
+ virtual DOMAttr * removeAttributeNode(DOMAttr *oldAttr) = 0;
- //@}
- /** @name Functions introduced in DOM Level 2. */
- //@{
+ /**
+ * Removes an attribute by name.
+ *
+ * If the removed attribute
+ * is known to have a default value, an attribute immediately appears
+ * containing the default value as well as the corresponding namespace URI,
+ * local name, and prefix when applicable.<BR>To remove an attribute by local
+ * name and namespace URI, use the <CODE>removeAttributeNS</CODE> method.
+ * @param name The name of the attribute to remove.
+ * @exception DOMException
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * @since DOM Level 1
+ */
+ virtual void removeAttribute(const XMLCh *name) = 0;
+ //@}
- /**
- * Retrieves an attribute value by local name and namespace URI.
- *
- * @param namespaceURI The <em>namespace URI</em> of
- * the attribute to retrieve.
- * @param localName The <em>local name</em> of the
- * attribute to retrieve.
- * @return The <code>DOMAttr</code> value as a string, or an <CODE>null</CODE> if
- * that attribute does not have a specified or default value.
- */
- virtual const XMLCh * getAttributeNS(const XMLCh *namespaceURI,
- const XMLCh *localName) const = 0;
+ /** @name Functions introduced in DOM Level 2. */
+ //@{
+ /**
+ * Retrieves an attribute value by local name and namespace URI.
+ *
+ * @param namespaceURI The <em>namespace URI</em> of
+ * the attribute to retrieve.
+ * @param localName The <em>local name</em> of the
+ * attribute to retrieve.
+ * @return The <code>DOMAttr</code> value as a string, or an <CODE>null</CODE> if
+ * that attribute does not have a specified or default value.
+ * @since DOM Level 2
+ */
+ virtual const XMLCh * getAttributeNS(const XMLCh *namespaceURI,
+ const XMLCh *localName) const = 0;
- /**
- * Adds a new attribute. If an attribute with the same
- * local name and namespace URI is already present on the element, its prefix
- * is changed to be the prefix part of the <CODE>qualifiedName</CODE>, and
- * its value is changed to be the <CODE>value</CODE> parameter. This value is
- * a simple string, it is not parsed as it is being set. So any markup (such
- * as syntax to be recognized as an entity reference) is treated as literal
- * text, and needs to be appropriately escaped by the implementation when it
- * is written out. In order to assign an attribute value that contains entity
- * references, the user must create an <CODE>DOMAttr</CODE>
- * node plus any <CODE>DOMText</CODE> and <CODE>DOMEntityReference</CODE>
- * nodes, build the appropriate subtree, and use
- * <CODE>setAttributeNodeNS</CODE> or <CODE>setAttributeNode</CODE> to assign
- * it as the value of an attribute.
- *
- * @param namespaceURI The <em>namespace URI</em> of
- * the attribute to create or alter.
- * @param qualifiedName The <em>qualified name</em> of the
- * attribute to create or alter.
- * @param value The value to set in string form.
- * @exception DOMException
- * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an
- * illegal character.
- * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- * <br>
- * NAMESPACE_ERR: Raised if the <CODE>qualifiedName</CODE> is
- * malformed, if the <CODE>qualifiedName</CODE> has a prefix and the
- * <CODE>namespaceURI</CODE> is <CODE>null</CODE> or an empty string,
- * if the <CODE>qualifiedName</CODE> has a prefix that is "xml" and the
- * <CODE>namespaceURI</CODE> is different from
- * "http://www.w3.org/XML/1998/namespace", if the
- * <CODE>qualifiedName</CODE> has a prefix that is "xmlns" and the
- * <CODE>namespaceURI</CODE> is different from
- * "http://www.w3.org/2000/xmlns/", or if the
- * <CODE>qualifiedName</CODE> is "xmlns" and the
- * <CODE>namespaceURI</CODE> is different from
- * "http://www.w3.org/2000/xmlns/".
- */
- virtual void setAttributeNS(const XMLCh *namespaceURI,
- const XMLCh *qualifiedName, const XMLCh *value) = 0;
+ /**
+ * Adds a new attribute. If an attribute with the same
+ * local name and namespace URI is already present on the element, its prefix
+ * is changed to be the prefix part of the <CODE>qualifiedName</CODE>, and
+ * its value is changed to be the <CODE>value</CODE> parameter. This value is
+ * a simple string, it is not parsed as it is being set. So any markup (such
+ * as syntax to be recognized as an entity reference) is treated as literal
+ * text, and needs to be appropriately escaped by the implementation when it
+ * is written out. In order to assign an attribute value that contains entity
+ * references, the user must create an <CODE>DOMAttr</CODE>
+ * node plus any <CODE>DOMText</CODE> and <CODE>DOMEntityReference</CODE>
+ * nodes, build the appropriate subtree, and use
+ * <CODE>setAttributeNodeNS</CODE> or <CODE>setAttributeNode</CODE> to assign
+ * it as the value of an attribute.
+ *
+ * @param namespaceURI The <em>namespace URI</em> of
+ * the attribute to create or alter.
+ * @param qualifiedName The <em>qualified name</em> of the
+ * attribute to create or alter.
+ * @param value The value to set in string form.
+ * @exception DOMException
+ * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an
+ * illegal character.
+ * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * <br>
+ * NAMESPACE_ERR: Raised if the <CODE>qualifiedName</CODE> is
+ * malformed, if the <CODE>qualifiedName</CODE> has a prefix and the
+ * <CODE>namespaceURI</CODE> is <CODE>null</CODE> or an empty string,
+ * if the <CODE>qualifiedName</CODE> has a prefix that is "xml" and the
+ * <CODE>namespaceURI</CODE> is different from
+ * "http://www.w3.org/XML/1998/namespace", if the
+ * <CODE>qualifiedName</CODE> has a prefix that is "xmlns" and the
+ * <CODE>namespaceURI</CODE> is different from
+ * "http://www.w3.org/2000/xmlns/", or if the
+ * <CODE>qualifiedName</CODE> is "xmlns" and the
+ * <CODE>namespaceURI</CODE> is different from
+ * "http://www.w3.org/2000/xmlns/".
+ * @since DOM Level 2
+ */
+ virtual void setAttributeNS(const XMLCh *namespaceURI,
+ const XMLCh *qualifiedName, const XMLCh *value) = 0;
- /**
- * Removes an attribute by local name and namespace URI. If the
- * removed attribute has a default value it is immediately replaced.
- * The replacing attribute has the same namespace URI and local name, as well as
- * the original prefix.
- *
- * @param namespaceURI The <em>namespace URI</em> of
- * the attribute to remove.
- * @param localName The <em>local name</em> of the
- * attribute to remove.
- * @exception DOMException
- * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- */
- virtual void removeAttributeNS(const XMLCh *namespaceURI,
- const XMLCh *localName) = 0;
+ /**
+ * Removes an attribute by local name and namespace URI. If the
+ * removed attribute has a default value it is immediately replaced.
+ * The replacing attribute has the same namespace URI and local name, as well as
+ * the original prefix.
+ *
+ * @param namespaceURI The <em>namespace URI</em> of
+ * the attribute to remove.
+ * @param localName The <em>local name</em> of the
+ * attribute to remove.
+ * @exception DOMException
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * @since DOM Level 2
+ */
+ virtual void removeAttributeNS(const XMLCh *namespaceURI,
+ const XMLCh *localName) = 0;
- /**
- * Retrieves an <code>DOMAttr</code> node by local name and namespace URI.
- *
- * @param namespaceURI The <em>namespace URI</em> of
- * the attribute to retrieve.
- * @param localName The <em>local name</em> of the
- * attribute to retrieve.
- * @return The <code>DOMAttr</code> node with the specified attribute local
- * name and namespace URI or <code>null</code> if there is no such attribute.
- */
- virtual DOMAttr * getAttributeNodeNS(const XMLCh *namespaceURI,
- const XMLCh *localName) const = 0;
+ /**
+ * Retrieves an <code>DOMAttr</code> node by local name and namespace URI.
+ *
+ * @param namespaceURI The <em>namespace URI</em> of
+ * the attribute to retrieve.
+ * @param localName The <em>local name</em> of the
+ * attribute to retrieve.
+ * @return The <code>DOMAttr</code> node with the specified attribute local
+ * name and namespace URI or <code>null</code> if there is no such attribute.
+ * @since DOM Level 2
+ */
+ virtual DOMAttr * getAttributeNodeNS(const XMLCh *namespaceURI,
+ const XMLCh *localName) const = 0;
- /**
- * Adds a new attribute.
- *
- * If an attribute with that local name and namespace URI is already present
- * in the element, it is replaced by the new one.
- *
- * @param newAttr The <code>DOMAttr</code> node to add to the attribute list.
- * @return If the <code>newAttr</code> attribute replaces an existing
- * attribute with the same <em>local name</em> and <em>namespace URI</em>,
- * the replaced <code>DOMAttr</code> node is
- * returned, otherwise <code>null</code> is returned.
- * @exception DOMException
- * WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a
- * different document than the one that created the element.
- * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
- * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
- * attribute of another <code>DOMElement</code> object. The DOM user must
- * explicitly clone <code>DOMAttr</code> nodes to re-use them in other
- * elements.
- */
- virtual DOMAttr * setAttributeNodeNS(DOMAttr *newAttr) = 0;
+ /**
+ * Adds a new attribute.
+ *
+ * If an attribute with that local name and namespace URI is already present
+ * in the element, it is replaced by the new one.
+ *
+ * @param newAttr The <code>DOMAttr</code> node to add to the attribute list.
+ * @return If the <code>newAttr</code> attribute replaces an existing
+ * attribute with the same <em>local name</em> and <em>namespace URI</em>,
+ * the replaced <code>DOMAttr</code> node is
+ * returned, otherwise <code>null</code> is returned.
+ * @exception DOMException
+ * WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a
+ * different document than the one that created the element.
+ * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
+ * attribute of another <code>DOMElement</code> object. The DOM user must
+ * explicitly clone <code>DOMAttr</code> nodes to re-use them in other
+ * elements.
+ * @since DOM Level 2
+ */
+ virtual DOMAttr * setAttributeNodeNS(DOMAttr *newAttr) = 0;
- /**
- * Returns a <code>DOMNodeList</code> of all the <code>DOMElement</code>s
- * with a given local name and namespace URI in the order in which they
- * would be encountered in a preorder traversal of the
- * <code>DOMDocument</code> tree, starting from this node.
- *
- * @param namespaceURI The <em>namespace URI</em> of
- * the elements to match on. The special value "*" matches all
- * namespaces.
- * @param localName The <em>local name</em> of the
- * elements to match on. The special value "*" matches all local names.
- * @return A new <code>DOMNodeList</code> object containing all the matched
- * <code>DOMElement</code>s.
- */
- virtual DOMNodeList * getElementsByTagNameNS(const XMLCh *namespaceURI,
- const XMLCh *localName) const = 0;
+ /**
+ * Returns a <code>DOMNodeList</code> of all the <code>DOMElement</code>s
+ * with a given local name and namespace URI in the order in which they
+ * would be encountered in a preorder traversal of the
+ * <code>DOMDocument</code> tree, starting from this node.
+ *
+ * @param namespaceURI The <em>namespace URI</em> of
+ * the elements to match on. The special value "*" matches all
+ * namespaces.
+ * @param localName The <em>local name</em> of the
+ * elements to match on. The special value "*" matches all local names.
+ * @return A new <code>DOMNodeList</code> object containing all the matched
+ * <code>DOMElement</code>s.
+ * @since DOM Level 2
+ */
+ virtual DOMNodeList * getElementsByTagNameNS(const XMLCh *namespaceURI,
+ const XMLCh *localName) const = 0;
/**
* Returns <code>true</code> when an attribute with a given name is
@@ -373,6 +392,7 @@ public:
* @return <code>true</code> if an attribute with the given name is
* specified on this element or has a default value, <code>false</code>
* otherwise.
+ * @since DOM Level 2
*/
virtual bool hasAttribute(const XMLCh *name) const = 0;
@@ -390,8 +410,7 @@ public:
*/
virtual bool hasAttributeNS(const XMLCh *namespaceURI,
const XMLCh *localName) const = 0;
-
- //@}
+ //@}
};
diff --git a/src/xercesc/dom/DOMEntity.hpp b/src/xercesc/dom/DOMEntity.hpp
index 6e16e5969d8123b8c4ff7efc798029783484fb4e..08ae70fd66aadca38907f5ae9964368b414eb73b 100644
--- a/src/xercesc/dom/DOMEntity.hpp
+++ b/src/xercesc/dom/DOMEntity.hpp
@@ -68,54 +68,100 @@
/**
* This interface represents an entity, either parsed or unparsed, in an XML
- * document.
- *
- * Note that this models the entity itself not the entity
- * declaration. <code>Entity</code> declaration modeling has been left for a
+ * document. Note that this models the entity itself not the entity
+ * declaration. <code>DOMEntity</code> declaration modeling has been left for a
* later Level of the DOM specification.
* <p>The <code>nodeName</code> attribute that is inherited from
- * <code>Node</code> contains the name of the entity.
- * <p>An XML processor may choose to completely expand entities before the
+ * <code>DOMNode</code> contains the name of the entity.
+ * <p>An XML processor may choose to completely expand entities before the
* structure model is passed to the DOM; in this case there will be no
- * <code>EntityReference</code> nodes in the document tree.
+ * <code>DOMEntityReference</code> nodes in the document tree.
+ * <p>XML does not mandate that a non-validating XML processor read and
+ * process entity declarations made in the external subset or declared in
+ * external parameter entities. This means that parsed entities declared in
+ * the external subset need not be expanded by some classes of applications,
+ * and that the replacement value of the entity may not be available. When
+ * the replacement value is available, the corresponding <code>DOMEntity</code>
+ * node's child list represents the structure of that replacement text.
+ * Otherwise, the child list is empty.
+ * <p>The DOM Level 2 does not support editing <code>DOMEntity</code> nodes; if a
+ * user wants to make changes to the contents of an <code>DOMEntity</code>,
+ * every related <code>DOMEntityReference</code> node has to be replaced in the
+ * structure model by a clone of the <code>DOMEntity</code>'s contents, and
+ * then the desired changes must be made to each of those clones instead.
+ * <code>DOMEntity</code> nodes and all their descendants are readonly.
+ * <p>An <code>DOMEntity</code> node does not have any parent.If the entity
+ * contains an unbound namespace prefix, the <code>namespaceURI</code> of
+ * the corresponding node in the <code>DOMEntity</code> node subtree is
+ * <code>null</code>. The same is true for <code>DOMEntityReference</code>
+ * nodes that refer to this entity, when they are created using the
+ * <code>createEntityReference</code> method of the <code>DOMDocument</code>
+ * interface. The DOM Level 2 does not support any mechanism to resolve
+ * namespace prefixes.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
*
- * <p>Note: the first release of this parser does not create entity
- * nodes when reading an XML document. Entities may be
- * programatically created using DOM_Document::createEntity().
+ * @since DOM Level 1
*/
class CDOM_EXPORT DOMEntity: public DOMNode {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMEntity() {};
DOMEntity(const DOMEntity &other) {};
DOMEntity & operator = (const DOMEntity &other) {return *this;};
+ //@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMEntity() {};
+ //@}
- /** @name Get functions. */
+ // -----------------------------------------------------------------------
+ // Virtual DOMEntity interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
//@{
- /**
- * The public identifier associated with the entity, if specified.
- *
- * If the public identifier was not specified, this is <code>null</code>.
- */
- virtual const XMLCh * getPublicId() const = 0;
-
- /**
- * The system identifier associated with the entity, if specified.
- *
- * If the system identifier was not specified, this is <code>null</code>.
- */
- virtual const XMLCh * getSystemId() const = 0;
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
+ /**
+ * The public identifier associated with the entity, if specified.
+ *
+ * If the public identifier was not specified, this is <code>null</code>.
+ *
+ * @since DOM Level 1
+ */
+ virtual const XMLCh * getPublicId() const = 0;
- /**
- * For unparsed entities, the name of the notation for the entity.
- *
- * For parsed entities, this is <code>null</code>.
- */
- virtual const XMLCh * getNotationName() const = 0;
+ /**
+ * The system identifier associated with the entity, if specified.
+ *
+ * If the system identifier was not specified, this is <code>null</code>.
+ *
+ * @since DOM Level 1
+ */
+ virtual const XMLCh * getSystemId() const = 0;
- //@}
+ /**
+ * For unparsed entities, the name of the notation for the entity.
+ *
+ * For parsed entities, this is <code>null</code>.
+ *
+ * @since DOM Level 1
+ */
+ virtual const XMLCh * getNotationName() const = 0;
+ //@}
};
diff --git a/src/xercesc/dom/DOMEntityReference.hpp b/src/xercesc/dom/DOMEntityReference.hpp
index 666198d049ab7c23b0deb890a2b1c2cd77356e65..141f8f101fbc7ae4ed3faa16b3dfd5fca51eba87 100644
--- a/src/xercesc/dom/DOMEntityReference.hpp
+++ b/src/xercesc/dom/DOMEntityReference.hpp
@@ -67,27 +67,53 @@
/**
- * <code>EntityReference</code> nodes will appear in the structure
- * model when an entity reference is in the source document, or when the user
- * wishes to insert an entity reference.
+ * <code>DOMEntityReference</code> objects may be inserted into the structure
+ * model when an entity reference is in the source document, or when the
+ * user wishes to insert an entity reference. Note that character references
+ * and references to predefined entities are considered to be expanded by
+ * the HTML or XML processor so that characters are represented by their
+ * Unicode equivalent rather than by an entity reference. Moreover, the XML
+ * processor may completely expand references to entities while building the
+ * structure model, instead of providing <code>DOMEntityReference</code>
+ * objects. If it does provide such objects, then for a given
+ * <code>DOMEntityReference</code> node, it may be that there is no
+ * <code>DOMEntity</code> node representing the referenced entity. If such an
+ * <code>DOMEntity</code> exists, then the subtree of the
+ * <code>DOMEntityReference</code> node is in general a copy of the
+ * <code>DOMEntity</code> node subtree. However, this may not be true when an
+ * entity contains an unbound namespace prefix. In such a case, because the
+ * namespace prefix resolution depends on where the entity reference is, the
+ * descendants of the <code>DOMEntityReference</code> node may be bound to
+ * different namespace URIs.
+ * <p>As for <code>DOMEntity</code> nodes, <code>DOMEntityReference</code> nodes and
+ * all their descendants are readonly.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
*
- * The expansion of the entity will appear as child nodes of the entity
- * reference node. The expansion may be just simple text, or it may
- * be more complex, containing additional entity refs.
- *
-*/
+ * @since DOM Level 1
+ */
class CDOM_EXPORT DOMEntityReference: public DOMNode {
protected:
- /** @name Constructors and assignment operator */
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
//@{
DOMEntityReference() {};
-
DOMEntityReference(const DOMEntityReference &other) {};
-
DOMEntityReference & operator = (const DOMEntityReference &other) {return *this;};
+ //@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMEntityReference() {};
//@}
diff --git a/src/xercesc/dom/DOMEntityResolver.hpp b/src/xercesc/dom/DOMEntityResolver.hpp
index 1eb45054b5bdb40838f95015e9a9d11361ff6255..8d4a76ed1bdee1edd006fabddad464aa10aab3ab 100644
--- a/src/xercesc/dom/DOMEntityResolver.hpp
+++ b/src/xercesc/dom/DOMEntityResolver.hpp
@@ -1,37 +1,40 @@
+#ifndef DOMEntityResolver_HEADER_GUARD_
+#define DOMEntityResolver_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
- *
+ *
* Copyright (c) 2002 The Apache Software Foundation. All rights
* reserved.
- *
+ *
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- *
+ *
* 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
+ * notice, this list of conditions and the following disclaimer.
+ *
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
- *
+ *
* 3. The end-user documentation included with the redistribution,
- * if any, must include the following acknowledgment:
+ * if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
- *
+ *
* 4. The names "Xerces" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
- * software without prior written permission. For written
+ * software without prior written permission. For written
* permission, please contact apache\@apache.org.
- *
+ *
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
- *
+ *
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
@@ -45,7 +48,7 @@
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
- *
+ *
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation, and was
* originally based on software copyright (c) 1999, International
@@ -56,6 +59,9 @@
/*
* $Log$
+ * Revision 1.3 2002/06/06 20:53:06 tng
+ * Documentation Fix: Update the API Documentation for DOM headers
+ *
* Revision 1.2 2002/05/30 19:24:48 knoaman
* documentation update
*
@@ -65,16 +71,11 @@
*/
-#ifndef DOMENTITYRESOLVER_HPP
-#define DOMENTITYRESOLVER_HPP
-
#include <xercesc/util/XercesDefs.hpp>
class DOMInputSource;
/**
- * Introduced in DOM Level 3
- *
* DOMEntityResolver provides a way for applications to redirect references
* to external entities.
*
@@ -93,65 +94,80 @@ class DOMInputSource;
*
* @see DOMBuilder#setEntityResolver
* @see DOMInputSource#DOMInputSource
+ * @since DOM Level 3
*/
class CDOM_EXPORT DOMEntityResolver
{
protected:
- /** @name Constructors */
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
//@{
-
- /** Default Constructor */
DOMEntityResolver() {};
-
+ DOMEntityResolver(const DOMEntityResolver &other) {};
+ DOMEntityResolver & operator = (const DOMEntityResolver &other) {return *this;};
//@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
/** @name Destructor */
//@{
-
- /** Destructor */
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMEntityResolver() {};
-
//@}
- /** @name The DOMEntityResolver interface */
+ // -----------------------------------------------------------------------
+ // Virtual DOMEntityResolver interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 2 */
//@{
-
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Allow the application to resolve external entities.
- *
- * <p>The DOMBuilder will call this method before opening any external
- * entity except the top-level document entity (including the
- * external DTD subset, external entities referenced within the
- * DTD, and external entities referenced within the document
- * element): the application may request that the DOMBuilder resolve
- * the entity itself, that it use an alternative URI, or that it
- * use an entirely different input source.</p>
- *
- * <p>Application writers can use this method to redirect external
- * system identifiers to secure and/or local URIs, to look up
- * public identifiers in a catalogue, or to read an entity from a
- * database or other input source (including, for example, a dialog
- * box).</p>
- *
- * <p>If the system identifier is a URL, the DOMBuilder parser must
- * resolve it fully before reporting it to the application.</p>
- *
- * @param publicId The public identifier of the external entity
- * being referenced, or null if none was supplied.
- * @param systemId The system identifier of the external entity
- * being referenced.
- * @param baseURI The absolute base URI of the resource being parsed, or
- * <code>null</code> if there is no base URI.
- * @return A DOMInputSource object describing the new input source,
- * or <code>null</code> to request that the parser open a regular
- * URI connection to the system identifier.
- * @exception DOMSystemException Any DOMSystemException exception, possibly
- * wrapping another exception.
- * @see DOMInputSource#DOMInputSource
- */
+ /**
+ * Allow the application to resolve external entities.
+ *
+ * <p>The DOMBuilder will call this method before opening any external
+ * entity except the top-level document entity (including the
+ * external DTD subset, external entities referenced within the
+ * DTD, and external entities referenced within the document
+ * element): the application may request that the DOMBuilder resolve
+ * the entity itself, that it use an alternative URI, or that it
+ * use an entirely different input source.</p>
+ *
+ * <p>Application writers can use this method to redirect external
+ * system identifiers to secure and/or local URIs, to look up
+ * public identifiers in a catalogue, or to read an entity from a
+ * database or other input source (including, for example, a dialog
+ * box).</p>
+ *
+ * <p>If the system identifier is a URL, the DOMBuilder parser must
+ * resolve it fully before reporting it to the application.</p>
+ *
+ * <p> The returned DOMInputSource is owned by the DOMBuilder which is
+ * responsible to clean up the memory.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param publicId The public identifier of the external entity
+ * being referenced, or null if none was supplied.
+ * @param systemId The system identifier of the external entity
+ * being referenced.
+ * @param baseURI The absolute base URI of the resource being parsed, or
+ * <code>null</code> if there is no base URI.
+ * @return A DOMInputSource object describing the new input source,
+ * or <code>null</code> to request that the parser open a regular
+ * URI connection to the system identifier.
+ * The returned DOMInputSource is owned by the DOMBuilder which is
+ * responsible to clean up the memory.
+ * @exception DOMSystemException Any DOMSystemException exception, possibly
+ * wrapping another exception.
+ * @see DOMInputSource#DOMInputSource
+ * @since DOM Level 3
+ */
virtual DOMInputSource* resolveEntity
(
const XMLCh* const publicId
@@ -161,15 +177,6 @@ public:
//@}
-private :
- /* Unimplemented constructors and operators */
-
- /* Copy constructor */
- DOMEntityResolver(const DOMEntityResolver&);
-
- /* Assignment operator */
- void operator=(const DOMEntityResolver&);
-
};
#endif
diff --git a/src/xercesc/dom/DOMError.hpp b/src/xercesc/dom/DOMError.hpp
index d6ec9eeeca702a9f238f8e8ecab939a3c07e5122..7b9b994cdc6a95dd3954b169e48fec181113deb2 100644
--- a/src/xercesc/dom/DOMError.hpp
+++ b/src/xercesc/dom/DOMError.hpp
@@ -1,37 +1,40 @@
+#ifndef DOMError_HEADER_GUARD_
+#define DOMError_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
- *
+ *
* Copyright (c) 2002 The Apache Software Foundation. All rights
* reserved.
- *
+ *
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- *
+ *
* 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
+ * notice, this list of conditions and the following disclaimer.
+ *
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
- *
+ *
* 3. The end-user documentation included with the redistribution,
- * if any, must include the following acknowledgment:
+ * if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
- *
+ *
* 4. The names "Xerces" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
- * software without prior written permission. For written
+ * software without prior written permission. For written
* permission, please contact apache\@apache.org.
- *
+ *
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
- *
+ *
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
@@ -45,7 +48,7 @@
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
- *
+ *
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation, and was
* originally based on software copyright (c) 1999, International
@@ -56,6 +59,9 @@
/*
* $Log$
+ * Revision 1.3 2002/06/06 20:53:06 tng
+ * Documentation Fix: Update the API Documentation for DOM headers
+ *
* Revision 1.2 2002/05/30 19:24:48 knoaman
* documentation update
*
@@ -65,125 +71,139 @@
*/
-#ifndef DOMERROR_HPP
-#define DOMERROR_HPP
-
#include <xercesc/util/XercesDefs.hpp>
class DOMLocator;
/**
- * Introduced in DOM Level 3
- *
* DOMError is an interface that describes an error.
*
* @see DOMErrorHandler#handleError
+ * @since DOM Level 3
*/
class CDOM_EXPORT DOMError
{
protected:
- /** @name Constructors */
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
//@{
-
- /** Default constructor */
DOMError() {};
-
+ DOMError(const DOMError &other) {};
+ DOMError & operator = (const DOMError &other) {return *this;};
//@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMError() {};
+ //@}
// -----------------------------------------------------------------------
// Class types
// -----------------------------------------------------------------------
+ /** @name Public constants */
+ //@{
+ /**
+ * The severity of the error described by the <code>DOMError</code>.
+ *
+ * @since DOM Level 3
+ */
enum ErrorSeverity
{
SEVERITY_WARNING = 0,
SEVERITY_ERROR = 1,
SEVERITY_FATAL_ERROR = 2
};
-
-
- /** @name Destructor */
- //@{
-
- /** Desctructor */
- virtual ~DOMError()
- {
- }
-
//@}
- /** @name Get function */
- //@{
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the severity of the error
- */
+ // -----------------------------------------------------------------------
+ // Virtual DOMError interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 3 */
+ //@{
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
+ /**
+ * Get the severity of the error
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @see setSeverity
+ * @since DOM Level 3
+ */
virtual short getSeverity() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the message describing the error that occured.
- */
+ /**
+ * Get the message describing the error that occured.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @see setMessage
+ * @since DOM Level 3
+ */
virtual const XMLCh* getMessage() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the location of the error
- */
+ /**
+ * Get the location of the error
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @see setLocation
+ * @since DOM Level 3
+ */
virtual DOMLocator* getLocation() const = 0;
- //@}
-
-
- /** @name Set function */
- //@{
-
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the severity of the error
- *
- * @param severity the type of the error to set
- */
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
+ /**
+ * Set the severity of the error
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param severity the type of the error to set
+ * @see getLocation
+ * @since DOM Level 3
+ */
virtual void setSeverity(const short severity) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the error message
- *
- * @param message the error message to set.
- */
+ /**
+ * Set the error message
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param message the error message to set.
+ * @see getMessage
+ * @since DOM Level 3
+ */
virtual void setMessage(const XMLCh* const message) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the location of the error
- *
- * @param location the location of the error to set.
- */
+ /**
+ * Set the location of the error
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param location the location of the error to set.
+ * @see getLocation
+ * @since DOM Level 3
+ */
virtual void setLocation(DOMLocator* const location) = 0;
//@}
-
-private :
- /* Unimplemented constructors and operators */
-
- /* Copy constructor */
- DOMError(const DOMError&);
-
- /* Assignment operator */
- void operator=(const DOMError&);
-
};
#endif
diff --git a/src/xercesc/dom/DOMErrorHandler.hpp b/src/xercesc/dom/DOMErrorHandler.hpp
index b590b84f4fc3a1a575ae8d3c8ca7c9aa64994d72..6b0e9cd06b19e5be33c6b8ca2f73e83491e2a6b7 100644
--- a/src/xercesc/dom/DOMErrorHandler.hpp
+++ b/src/xercesc/dom/DOMErrorHandler.hpp
@@ -1,37 +1,40 @@
+#ifndef DOMErrorHandler_HEADER_GUARD_
+#define DOMErrorHandler_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
- *
+ *
* Copyright (c) 2002 The Apache Software Foundation. All rights
* reserved.
- *
+ *
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
- *
+ *
* 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
+ * notice, this list of conditions and the following disclaimer.
+ *
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
- *
+ *
* 3. The end-user documentation included with the redistribution,
- * if any, must include the following acknowledgment:
+ * if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
- *
+ *
* 4. The names "Xerces" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
- * software without prior written permission. For written
+ * software without prior written permission. For written
* permission, please contact apache\@apache.org.
- *
+ *
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
- *
+ *
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
@@ -45,7 +48,7 @@
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
- *
+ *
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation, and was
* originally based on software copyright (c) 1999, International
@@ -56,6 +59,9 @@
/*
* $Log$
+ * Revision 1.3 2002/06/06 20:53:06 tng
+ * Documentation Fix: Update the API Documentation for DOM headers
+ *
* Revision 1.2 2002/05/30 19:24:48 knoaman
* documentation update
*
@@ -65,17 +71,11 @@
*/
-#ifndef DOMERRORHANDLER_HPP
-#define DOMERRORHANDLER_HPP
-
#include <xercesc/util/XercesDefs.hpp>
class DOMError;
-
/**
- * Introduced in DOM Level 3
- *
* Basic interface for DOM error handlers.
*
* <p>DOMErrorHandler is a callback interface that the DOM implementation
@@ -86,68 +86,71 @@ class DOMError;
* implement this interface.</p>
*
* @see DOMBuilder#setErrorHandler
+ * @since DOM Level 3
*/
class CDOM_EXPORT DOMErrorHandler
{
protected:
- /** @name Constructors */
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
//@{
-
- /** Default constructor */
DOMErrorHandler() {};
-
+ DOMErrorHandler(const DOMErrorHandler &other) {};
+ DOMErrorHandler & operator = (const DOMErrorHandler &other) {return *this;};
//@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
/** @name Destructor */
//@{
-
- /** Desctructor */
- virtual ~DOMErrorHandler()
- {
- }
-
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMErrorHandler() {};
//@}
- /** @name The error handler interface */
+ // -----------------------------------------------------------------------
+ // Virtual DOMErrorHandler interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 3 */
//@{
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * This method is called on the error handler when an error occures.
- *
- * @param domError The error object that describes the error, this object
- * may be reused by the DOM implementation across multiple
- * calls to the handleEvent method.
- * @return If the handleError method returns <code>true</code> the DOM
- * implementation should continue as if the error didn't happen
- * when possible, if the method returns <code>false</code> then the
- * DOM implementation should stop the current processing when
- * possible.
- */
+ /**
+ * This method is called on the error handler when an error occures.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param domError The error object that describes the error, this object
+ * may be reused by the DOM implementation across multiple
+ * calls to the handleEvent method.
+ * @return If the handleError method returns <code>true</code> the DOM
+ * implementation should continue as if the error didn't happen
+ * when possible, if the method returns <code>false</code> then the
+ * DOM implementation should stop the current processing when
+ * possible.
+ *
+ * @since DOM Level 3
+ */
virtual bool handleError(const DOMError& domError) = 0;
- /**
- * Reset the Error handler object on its reuse
- *
- * <p>This method helps in reseting the Error handler object
- * implementational defaults each time the Error handler is begun.</p>
- *
- */
- virtual void resetErrors() = 0;
+ /**
+ * Reset the Error handler object on its reuse
+ *
+ * <p>This method helps in reseting the Error handler object
+ * implementational defaults each time the Error handler is begun.</p>
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @since DOM Level 3
+ */
+ virtual void resetErrors() = 0;
//@}
-
-private :
- /* Unimplemented constructors and operators */
-
- /* Copy constructor */
- DOMErrorHandler(const DOMErrorHandler&);
-
- /* Assignment operator */
- void operator=(const DOMErrorHandler&);
-
};
#endif
diff --git a/src/xercesc/dom/DOMException.hpp b/src/xercesc/dom/DOMException.hpp
index fb118138057b209efc3bd748c7378b69b6759086..b3fe5c93f653c25750f67a177489e8426fc01ded 100644
--- a/src/xercesc/dom/DOMException.hpp
+++ b/src/xercesc/dom/DOMException.hpp
@@ -64,47 +64,30 @@
#include <xercesc/util/XercesDefs.hpp>
/**
- * Encapsulate a general DOM error or warning.
- *
- * <p> The DOM will create and throw an instance of DOMException
- * when an error condition is detected. Exceptions can occur
- * when an application directly manipulates the DOM document
- * tree that is produced by the parser, or when a document tree
- * is created from scratch using the DOM API. DOM exceptions will
- * not be generated by the parser while constructing a document
- * tree from an XML source document.
- *
- * <p>Unlike the other classes in the C++ DOM API, DOM_DOMException
- * is NOT a reference to an underlying implementation class, and
- * does not provide automatic memory management. Code that catches
- * a DOM exception is responsible for deleting it, or otherwise
- * arranging for its disposal.
- *
- */
+ * DOM operations only raise exceptions in "exceptional" circumstances, i.e.,
+ * when an operation is impossible to perform (either for logical reasons,
+ * because data is lost, or because the implementation has become unstable).
+ * In general, DOM methods return specific error values in ordinary
+ * processing situations, such as out-of-bound errors when using
+ * <code>DOMNodeList</code>.
+ * <p>Implementations should raise other exceptions under other circumstances.
+ * For example, implementations should raise an implementation-dependent
+ * exception if a <code>null</code> argument is passed.
+ * <p>Some languages and object systems do not support the concept of
+ * exceptions. For such systems, error conditions may be indicated using
+ * native error reporting mechanisms. For some bindings, for example,
+ * methods may return error codes similar to those listed in the
+ * corresponding method descriptions.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
+ * @since DOM Level 1
+ */
+
class CDOM_EXPORT DOMException {
public:
- /** @name Enumerators for DOM Exceptions */
- //@{
- enum ExceptionCode {
- INDEX_SIZE_ERR = 1,
- DOMSTRING_SIZE_ERR = 2,
- HIERARCHY_REQUEST_ERR = 3,
- WRONG_DOCUMENT_ERR = 4,
- INVALID_CHARACTER_ERR = 5,
- NO_DATA_ALLOWED_ERR = 6,
- NO_MODIFICATION_ALLOWED_ERR = 7,
- NOT_FOUND_ERR = 8,
- NOT_SUPPORTED_ERR = 9,
- INUSE_ATTRIBUTE_ERR = 10,
- INVALID_STATE_ERR = 11,
- SYNTAX_ERR = 12,
- INVALID_MODIFICATION_ERR = 13,
- NAMESPACE_ERR = 14,
- INVALID_ACCESS_ERR = 15
- };
- //@}
-public:
- /** @name Constructors and assignment operator */
+ // -----------------------------------------------------------------------
+ // Constructors
+ // -----------------------------------------------------------------------
+ /** @name Constructors */
//@{
/**
* Default constructor for DOMException.
@@ -128,30 +111,125 @@ public:
DOMException(const DOMException &other);
//@}
+
+ // -----------------------------------------------------------------------
+ // Destructors
+ // -----------------------------------------------------------------------
/** @name Destructor. */
//@{
/**
- * Destructor for DOMException. Applications are responsible
- * for deleting DOM_Exception objects that they catch after they
- * have completed their exception processing.
+ * Destructor for DOMException.
*
*/
virtual ~DOMException();
//@}
- /** @name Public variables. */
- //@{
+public:
+ // -----------------------------------------------------------------------
+ // Class Types
+ // -----------------------------------------------------------------------
+ /** @name Public Contants */
+ //@{
+ /**
+ * ExceptionCode
+ *
+ * <p><code>INDEX_SIZE_ERR:</code>
+ * If index or size is negative, or greater than the allowed value.</p>
+ *
+ * <p><code>DOMSTRING_SIZE_ERR:</code>
+ * If the specified range of text does not fit into a DOMString.</p>
+ *
+ * <p><code>HIERARCHY_REQUEST_ERR:</code>
+ * If any node is inserted somewhere it doesn't belong.</p>
+ *
+ * <p><code>WRONG_DOCUMENT_ERR:</code>
+ * If a node is used in a different document than the one that created it
+ * (that doesn't support it).</p>
+ *
+ * <p><code>INVALID_CHARACTER_ERR:</code>
+ * If an invalid or illegal character is specified, such as in a name. See
+ * production 2 in the XML specification for the definition of a legal
+ * character, and production 5 for the definition of a legal name
+ * character.</p>
+ *
+ * <p><code>NO_DATA_ALLOWED_ERR:</code>
+ * If data is specified for a node which does not support data.</p>
+ *
+ * <p><code>NO_MODIFICATION_ALLOWED_ERR:</code>
+ * If an attempt is made to modify an object where modifications are not
+ * allowed.</p>
+ *
+ * <p><code>NOT_FOUND_ERR:</code>
+ * If an attempt is made to reference a node in a context where it does
+ * not exist.</p>
+ *
+ * <p><code>NOT_SUPPORTED_ERR:</code>
+ * If the implementation does not support the requested type of object or
+ * operation.</p>
+ *
+ * <p><code>INUSE_ATTRIBUTE_ERR:</code>
+ * If an attempt is made to add an attribute that is already in use
+ * elsewhere.</p>
+ *
+ * The above are since DOM Level 1
+ * @since DOM Level 1
+ *
+ * <p><code>INVALID_STATE_ERR:</code>
+ * If an attempt is made to use an object that is not, or is no longer,
+ * usable.</p>
+ *
+ * <p><code>SYNTAX_ERR:</code>
+ * If an invalid or illegal string is specified.</p>
+ *
+ * <p><code>INVALID_MODIFICATION_ERR:</code>
+ * If an attempt is made to modify the type of the underlying object.</p>
+ *
+ * <p><code>NAMESPACE_ERR:</code>
+ * If an attempt is made to create or change an object in a way which is
+ * incorrect with regard to namespaces.</p>
+ *
+ * <p><code>INVALID_ACCESS_ERR:</code>
+ * If a parameter or an operation is not supported by the underlying
+ * object.
+ *
+ * The above are since DOM Level 2
+ * @since DOM Level 2
+ */
+ enum ExceptionCode {
+ INDEX_SIZE_ERR = 1,
+ DOMSTRING_SIZE_ERR = 2,
+ HIERARCHY_REQUEST_ERR = 3,
+ WRONG_DOCUMENT_ERR = 4,
+ INVALID_CHARACTER_ERR = 5,
+ NO_DATA_ALLOWED_ERR = 6,
+ NO_MODIFICATION_ALLOWED_ERR = 7,
+ NOT_FOUND_ERR = 8,
+ NOT_SUPPORTED_ERR = 9,
+ INUSE_ATTRIBUTE_ERR = 10,
+ INVALID_STATE_ERR = 11,
+ SYNTAX_ERR = 12,
+ INVALID_MODIFICATION_ERR = 13,
+ NAMESPACE_ERR = 14,
+ INVALID_ACCESS_ERR = 15
+ };
+ //@}
+
+ // -----------------------------------------------------------------------
+ // Class Types
+ // -----------------------------------------------------------------------
+ /** @name Public variables */
+ //@{
/**
* A code value, from the set defined by the ExceptionCode enum,
- * indicating the type of error that occured.
- */
- ExceptionCode code;
+ * indicating the type of error that occured.
+ */
+ ExceptionCode code;
/**
* A string value. Applications may use this field to hold an error
- * message. The field value is not set by the DOM implementation,
- * meaning that the string will be empty when an exception is first
- * thrown.
+ * message. The field value is not set by the DOM implementation,
+ * meaning that the string will be empty when an exception is first
+ * thrown.
*/
const XMLCh *msg;
//@}
diff --git a/src/xercesc/dom/DOMImplementation.hpp b/src/xercesc/dom/DOMImplementation.hpp
index 5a842563492cd4828bb9f1d47ece55a1349ae138..8774ac285c80ab9e95187d540d148a3db117f173 100644
--- a/src/xercesc/dom/DOMImplementation.hpp
+++ b/src/xercesc/dom/DOMImplementation.hpp
@@ -79,7 +79,7 @@ protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
- /** @name Constructors */
+ /** @name Hidden constructors */
//@{
DOMImplementation() {}; // no plain constructor
@@ -102,9 +102,9 @@ public:
//@}
// -----------------------------------------------------------------------
- // DOMImplementation interface
+ // Virtual DOMImplementation interface
// -----------------------------------------------------------------------
- /** @name Virtual DOMImplementation interface */
+ /** @name Functions introduced in DOM Level 1 */
//@{
/**
* Test if the DOM implementation implements a specific feature.
@@ -120,24 +120,28 @@ public:
* method to return <code>true</code>.
* @return <code>true</code> if the feature is implemented in the
* specified version, <code>false</code> otherwise.
+ * @since DOM Level 1
*/
virtual bool hasFeature(const XMLCh *feature, const XMLCh *version) = 0;
+ //@}
-
+ // -----------------------------------------------------------------------
+ // Functions introduced in DOM Level 2
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 2 */
+ //@{
/**
- * Introduced in DOM Level 2
- *
- * Creates an empty <code>DocumentType</code> node. Entity declarations
+ * Creates an empty <code>DOMDocumentType</code> node. Entity declarations
* and notations are not made available. Entity reference expansions and
* default attribute additions do not occur. It is expected that a
* future version of the DOM will provide a way for populating a
- * <code>DocumentType</code>.
+ * <code>DOMDocumentType</code>.
* @param qualifiedName The qualified name of the document type to be
* created.
* @param publicId The external subset public identifier.
* @param systemId The external subset system identifier.
- * @return A new <code>DocumentType</code> node with
- * <code>Node.ownerDocument</code> set to <code>null</code>.
+ * @return A new <code>DOMDocumentType</code> node with
+ * <code>ownerDocument</code> set to <code>null</code>.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified qualified name
* contains an illegal character.
@@ -156,9 +160,7 @@ public:
const XMLCh *systemId) = 0;
/**
- * Introduced in DOM Level 2
- *
- * Creates a DOM Document object of the specified type with its document
+ * Creates a DOMDocument object of the specified type with its document
* element.
* @param namespaceURI The namespace URI of the document element to
* create.
@@ -166,9 +168,9 @@ public:
* created.
* @param doctype The type of document to be created or <code>null</code>.
* When <code>doctype</code> is not <code>null</code>, its
- * <code>Node.ownerDocument</code> attribute is set to the document
+ * <code>ownerDocument</code> attribute is set to the document
* being created.
- * @return A new <code>Document</code> object.
+ * @return A new <code>DOMDocument</code> object.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified qualified name
* contains an illegal character.
@@ -207,20 +209,23 @@ public:
/**
* Non-standard extension
*
- * Factory method for getting a DOMImplementation object.
- * The DOM implementation retains ownership of the returned object.
- * Application code should NOT delete it.
+ * Create a completely empty document that has neither a root element or a doctype node.
*/
- static DOMImplementation *getImplementation();
+ virtual DOMDocument *createDocument() = 0;
+ //@}
+ /** @name Non-standard extension */
+ //@{
/**
* Non-standard extension
*
- * Create a completely empty document that has neither a root element or a doctype node.
+ * Factory method for getting a DOMImplementation object.
+ * The DOM implementation retains ownership of the returned object.
+ * Application code should NOT delete it.
*/
- virtual DOMDocument *createDocument() = 0;
-
+ static DOMImplementation *getImplementation();
//@}
+
};
#endif
diff --git a/src/xercesc/dom/DOMImplementationLS.hpp b/src/xercesc/dom/DOMImplementationLS.hpp
index e80292a616b5c96d628b6dd6c854bf8a10baa7b1..d57160690c3f6cd604385c7b7d1da7c3d9d3735e 100644
--- a/src/xercesc/dom/DOMImplementationLS.hpp
+++ b/src/xercesc/dom/DOMImplementationLS.hpp
@@ -1,3 +1,6 @@
+#ifndef DOMImplementationLS_HEADER_GUARD_
+#define DOMImplementationLS_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
*
@@ -56,6 +59,9 @@
/*
* $Log$
+ * Revision 1.4 2002/06/06 20:53:06 tng
+ * Documentation Fix: Update the API Documentation for DOM headers
+ *
* Revision 1.3 2002/05/30 19:24:48 knoaman
* documentation update
*
@@ -68,9 +74,6 @@
*/
-#ifndef DOMIMPLEMENTATIONLS_HPP
-#define DOMIMPLEMENTATIONLS_HPP
-
#include <xercesc/util/XercesDefs.hpp>
class DOMBuilder;
@@ -79,8 +82,6 @@ class DOMInputSource;
/**
- * Introduced in DOM Level 3
- *
* <p><code>DOMImplementationLS</code> contains the factory methods for
* creating objects that implement the <code>DOMBuilder</code> (parser) and
* <code>DOMWriter</code> (serializer) interfaces.</p>
@@ -90,6 +91,8 @@ class DOMInputSource;
* Implementations supporting the Load and Save feature must implement the
* DOMImplementationLS interface on whatever object implements the
* DOMImplementation interface.</p>
+ *
+ * @since DOM Level 3
*/
class CDOM_EXPORT DOMImplementationLS
{
@@ -97,105 +100,112 @@ protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
- /** @name Constructors */
+ /** @name Hidden constructors */
//@{
-
- /** Default constructor */
DOMImplementationLS() {};
-
+ DOMImplementationLS(const DOMImplementationLS &other) {};
+ DOMImplementationLS & operator = (const DOMImplementationLS &other) {return *this;};
//@}
-
public:
// -----------------------------------------------------------------------
// All constructors are hidden, just the destructor is available
// -----------------------------------------------------------------------
/** @name Destructor */
//@{
- /**
- * Destructor
- *
- */
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMImplementationLS() {};
//@}
-
// -----------------------------------------------------------------------
// Public constants
// -----------------------------------------------------------------------
+ /** @name Public constants */
+ //@{
+ /**
+ * Create a synchronous or an asynchronous <code>DOMBuilder</code>.
+ * @see createDOMBuilder(const short mode, const XMLCh* const schemaType)
+ * @since DOM Level 3
+ *
+ */
enum
{
MODE_SYNCHRONOUS = 1,
MODE_ASYNCHRONOUS = 2
};
+ //@}
// -----------------------------------------------------------------------
- /** @name Virtual DOMImplementation LS interface */
+ // Virtual DOMImplementation LS interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 3 */
//@{
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * <p>Create a new DOMBuilder. The newly constructed parser may then be
- * configured by means of its setFeature method, and used to parse
- * documents by means of its parse method.</p>
- *
- * @param mode The mode argument is either <code>MODE_SYNCHRONOUS</code> or
- * <code>MODE_ASYNCHRONOUS</code>, if mode is <code>MODE_SYNCHRONOUS</code>
- * then the <code>DOMBuilder</code> that is created will operate in
- * synchronous mode, if it's <code>MODE_ASYNCHRONOUS</code> then the
- * <code>DOMBuilder</code> that is created will operate in asynchronous
- * mode.
- * @param schemaType An absolute URI representing the type of the schema
- * language used during the load of a Document using the newly created
- * <code>DOMBuilder</code>. Note that no lexical checking is done on the
- * absolute URI. In order to create a DOMBuilder for any kind of schema
- * types (i.e. the DOMBuilder will be free to use any schema found), use
- * the value <code>null</code>.
- * @return The newly created <code>DOMBuilder<code> object. This
- * <code>DOMBuilder</code> is either synchronous or asynchronous depending
- * on the value of the <code>mode<code> argument.
- * @exception DOMException NOT_SUPPORTED_ERR: Raised if the requested mode
- * or schema type is not supported.
- *
- * @see DOMBuilder
- */
+ // -----------------------------------------------------------------------
+ // Factory create methods
+ // -----------------------------------------------------------------------
+ /**
+ * Create a new DOMBuilder. The newly constructed parser may then be
+ * configured by means of its setFeature method, and used to parse
+ * documents by means of its parse method.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param mode The mode argument is either <code>MODE_SYNCHRONOUS</code> or
+ * <code>MODE_ASYNCHRONOUS</code>, if mode is <code>MODE_SYNCHRONOUS</code>
+ * then the <code>DOMBuilder</code> that is created will operate in
+ * synchronous mode, if it's <code>MODE_ASYNCHRONOUS</code> then the
+ * <code>DOMBuilder</code> that is created will operate in asynchronous
+ * mode.
+ * @param schemaType An absolute URI representing the type of the schema
+ * language used during the load of a DOMDocument using the newly created
+ * <code>DOMBuilder</code>. Note that no lexical checking is done on the
+ * absolute URI. In order to create a DOMBuilder for any kind of schema
+ * types (i.e. the DOMBuilder will be free to use any schema found), use
+ * the value <code>null</code>.
+ * @return The newly created <code>DOMBuilder<code> object. This
+ * <code>DOMBuilder</code> is either synchronous or asynchronous depending
+ * on the value of the <code>mode<code> argument.
+ * @exception DOMException NOT_SUPPORTED_ERR: Raised if the requested mode
+ * or schema type is not supported.
+ *
+ * @see DOMBuilder
+ * @since DOM Level 3
+ */
virtual DOMBuilder* createDOMBuilder(const short mode,
const XMLCh* const schemaType) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * <p>Create a new DOMWriter. DOMWriters are used to serialize a DOM tree
- * back into an XML document.</p>
- *
- * @return The newly created <code>DOMWriter<code> object.
- *
- * @see DOMWriter
- */
+ /**
+ * Create a new DOMWriter. DOMWriters are used to serialize a DOM tree
+ * back into an XML document.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return The newly created <code>DOMWriter<code> object.
+ *
+ * @see DOMWriter
+ * @since DOM Level 3
+ */
virtual DOMWriter* createDOMWriter() = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * <p>Create a new "empty" DOMInputSource.</p>
- *
- * @return The newly created <code>DOMInputSource<code> object.
- *
- * @see DOMInputSource
- */
+ /**
+ * Create a new "empty" DOMInputSource.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return The newly created <code>DOMInputSource<code> object.
+ * @exception DOMException NOT_SUPPORTED_ERR: Raised if this function is not
+ * supported by implementation
+ *
+ * @see DOMInputSource
+ * @since DOM Level 3
+ */
virtual DOMInputSource* createDOMInputSource() = 0;
//@}
-
-
-private:
- // -----------------------------------------------------------------------
- // Unimplemented constructors and operators
- // -----------------------------------------------------------------------
- DOMImplementationLS(const DOMImplementationLS&);
- DOMImplementationLS& operator=(const DOMImplementationLS&);
-
};
diff --git a/src/xercesc/dom/DOMImplementationRegistry.hpp b/src/xercesc/dom/DOMImplementationRegistry.hpp
index fd09361426aeccf7d6a7ef8687b7120b5e4700e6..b813ac804f2e344ef45db10f44c34986f123290c 100644
--- a/src/xercesc/dom/DOMImplementationRegistry.hpp
+++ b/src/xercesc/dom/DOMImplementationRegistry.hpp
@@ -62,8 +62,6 @@
*/
/**
- * Introduced in DOM Level 3
- *
* This class holds the list of registered DOMImplementations. Implementation
* or application can register DOMImplementationSource to the registry, and
* then can query DOMImplementation based on a list of requested features.
@@ -73,6 +71,7 @@
*
* @see DOMImplementation
* @see DOMImplementationSource
+ * @since DOM Level 3
*/
class DOMImplementation;
@@ -82,16 +81,16 @@ class CDOM_EXPORT DOMImplementationRegistry
{
public:
// -----------------------------------------------------------------------
- // Static DOMImplementationRegistry interface */
+ // Static DOMImplementationRegistry interface
// -----------------------------------------------------------------------
- /** @name Static DOMImplementationRegistry interface */
+ /** @name Functions introduced in DOM Level 3 */
//@{
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Return the first registered implementation that has the desired features,
* or null if none is found.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param features A string that specifies which features are required.
* This is a space separated list in which each feature is
* specified by its name optionally followed by a space
@@ -99,18 +98,21 @@ public:
* This is something like: "XML 1.0 Traversal Events 2.0"
* @return An implementation that has the desired features, or
* <code>null</code> if this source has none.
+ * @since DOM Level 3
*/
static DOMImplementation* getDOMImplementation(const XMLCh* features);
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Register an implementation.
*
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param source A DOMImplementation Source object to be added to the registry.
* The registry does NOT adopt the source object. Users still own it.
+ * @since DOM Level 3
*/
static void addSource(DOMImplementationSource* source);
+ //@}
};
#endif
diff --git a/src/xercesc/dom/DOMImplementationSource.hpp b/src/xercesc/dom/DOMImplementationSource.hpp
index ac12ed9cd0709ef6031ee9f7ac4979b95bf41bd8..fe6f4c50345152b6d00e669d7b20ec96b3dae4d8 100644
--- a/src/xercesc/dom/DOMImplementationSource.hpp
+++ b/src/xercesc/dom/DOMImplementationSource.hpp
@@ -62,14 +62,14 @@
*/
/**
- * Introduced in DOM Level 3
- *
* This interface permits a DOM implementer to supply one or more
* implementations, based upon requested features. Each implemented
* <code>DOMImplementationSource</code> object is listed in the
* binding-specific list of available sources so that its
* <code>DOMImplementation</code> objects are made available.
- * <p>See also the <a href='http://www.w3.org/2001/10/WD-DOM-Level-3-Core-20011017'>Document Object Model (DOM) Level 3 Core Specification</a>.
+ * <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409'>Document Object Model (DOM) Level 3 Core Specification</a>.
+ *
+ * @since DOM Level 3
*/
class DOMImplementation;
@@ -80,12 +80,11 @@ protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
- /** @name Constructors */
+ /** @name Hidden constructors */
//@{
-
- /** Default constructor */
DOMImplementationSource() {};
-
+ DOMImplementationSource(const DOMImplementationSource &other) {};
+ DOMImplementationSource & operator = (const DOMImplementationSource &other) {return *this;};
//@}
@@ -103,20 +102,22 @@ public:
//@}
// -----------------------------------------------------------------------
- // Virtual DOMImplementationSource interface */
+ // Virtual DOMImplementationSource interface
// -----------------------------------------------------------------------
- /** @name Virtual DOMImplementationSource interface */
+ /** @name Functions introduced in DOM Level 3 */
//@{
/**
+ * A method to request a DOM implementation.
+ *
* <p><b>"Experimental - subject to change"</b></p>
*
- * A method to request a DOM implementation.
* @param features A string that specifies which features are required.
* This is a space separated list in which each feature is specified
* by its name optionally followed by a space and a version number.
* This is something like: "XML 1.0 Traversal Events 2.0"
* @return An implementation that has the desired features, or
* <code>null</code> if this source has none.
+ * @since DOM Level 3
*/
virtual DOMImplementation* getDOMImplementation(const XMLCh* features) const = 0;
//@}
diff --git a/src/xercesc/dom/DOMInputSource.hpp b/src/xercesc/dom/DOMInputSource.hpp
index b006e417bf2415239fed1c4e9ece9ade4a109b84..5258b0880825aefdb1c23ccd464c9fa2d248da8a 100644
--- a/src/xercesc/dom/DOMInputSource.hpp
+++ b/src/xercesc/dom/DOMInputSource.hpp
@@ -1,3 +1,6 @@
+#ifndef DOMInputSource_HEADER_GUARD_
+#define DOMInputSource_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
*
@@ -56,6 +59,9 @@
/*
* $Log$
+ * Revision 1.3 2002/06/06 20:53:06 tng
+ * Documentation Fix: Update the API Documentation for DOM headers
+ *
* Revision 1.2 2002/05/30 19:24:48 knoaman
* documentation update
*
@@ -65,16 +71,12 @@
*/
-#ifndef DOMINPUTSOURCE_HPP
-#define DOMINPUTSOURCE_HPP
-
#include <xercesc/util/XercesDefs.hpp>
class BinInputStream;
/**
- * Introduced in DOM Level 3
* This interface represents a single input source for an XML entity.
*
* <p>This interface allows an application to encapsulate information about
@@ -98,6 +100,7 @@ class BinInputStream;
*
* @see DOMBuilder#parse
* @see DOMEntityResolver#resolveEntity
+ * @since DOM Level 3
*/
class CDOM_EXPORT DOMInputSource
{
@@ -105,202 +108,196 @@ protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
- /** @name Constructors */
+ /** @name Hidden constructors */
//@{
-
- /** Default constructor */
DOMInputSource() {};
-
+ DOMInputSource(const DOMInputSource &other) {};
+ DOMInputSource & operator = (const DOMInputSource &other) {return *this;};
//@}
-
public:
// -----------------------------------------------------------------------
// All constructors are hidden, just the destructor is available
// -----------------------------------------------------------------------
/** @name Destructor */
//@{
- /**
- * Destructor
- *
- */
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMInputSource() {};
//@}
-
// -----------------------------------------------------------------------
- /** @name Virtual input source interface */
+ // Virtual DOMInputSource interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 3 */
//@{
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Makes the byte stream for this input source.
- *
- * <p>The derived class must create and return a binary input stream of an
- * appropriate type for its kind of data source. The returned stream must
- * be dynamically allocated and becomes the parser's property.
- * </p>
- *
- * @see BinInputStream
- */
+ /**
+ * Makes the byte stream for this input source.
+ *
+ * <p>The derived class must create and return a binary input stream of an
+ * appropriate type for its kind of data source. The returned stream must
+ * be dynamically allocated and becomes the parser's property.
+ * </p>
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @see BinInputStream
+ * @since DOM Level 3
+ */
virtual BinInputStream* makeStream() const = 0;
- //@}
-
-
// -----------------------------------------------------------------------
- /** @name Getter methods */
- //@{
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * An input source can be set to force the parser to assume a particular
- * encoding for the data that input source reprsents, via the setEncoding()
- * method. This method returns name of the encoding that is to be forced.
- * If the encoding has never been forced, it returns a null pointer.
- *
- * @return The forced encoding, or null if none was supplied.
- * @see #setEncoding
- */
+ // Getter methods
+ // -----------------------------------------------------------------------
+ /**
+ * An input source can be set to force the parser to assume a particular
+ * encoding for the data that input source reprsents, via the setEncoding()
+ * method. This method returns name of the encoding that is to be forced.
+ * If the encoding has never been forced, it returns a null pointer.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return The forced encoding, or null if none was supplied.
+ * @see #setEncoding
+ * @since DOM Level 3
+ */
virtual const XMLCh* getEncoding() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the public identifier for this input source.
- *
- * @return The public identifier, or null if none was supplied.
- * @see #setPublicId
- */
+ /**
+ * Get the public identifier for this input source.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return The public identifier, or null if none was supplied.
+ * @see #setPublicId
+ * @since DOM Level 3
+ */
virtual const XMLCh* getPublicId() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the system identifier for this input source.
- *
- * <p>If the system ID is a URL, it will be fully resolved.</p>
- *
- * @return The system identifier.
- * @see #setSystemId
- */
+ /**
+ * Get the system identifier for this input source.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * <p>If the system ID is a URL, it will be fully resolved.</p>
+ *
+ * @return The system identifier.
+ * @see #setSystemId
+ * @since DOM Level 3
+ */
virtual const XMLCh* getSystemId() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the base URI to be used for resolving relative URIs to absolute
- * URIs. If the baseURI is itself a relative URI, the behavior is
- * implementation dependent.
- *
- * @return The base URI.
- * @see #setBaseURI
- */
+ /**
+ * Get the base URI to be used for resolving relative URIs to absolute
+ * URIs. If the baseURI is itself a relative URI, the behavior is
+ * implementation dependent.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return The base URI.
+ * @see #setBaseURI
+ * @since DOM Level 3
+ */
virtual const XMLCh* getBaseURI() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the flag that indicates if the parser should issue fatal error if this input source
- * is not found.
- *
- * @return True if the parser should issue fatal error if this input source is not found.
- * False if the parser issue warning message instead.
- * @see #setIssueFatalErrorIfNotFound
- */
+ /**
+ * Get the flag that indicates if the parser should issue fatal error if this input source
+ * is not found.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return True if the parser should issue fatal error if this input source is not found.
+ * False if the parser issue warning message instead.
+ * @see #setIssueFatalErrorIfNotFound
+ * @since DOM Level 3
+ */
virtual const bool getIssueFatalErrorIfNotFound() const = 0;
- //@}
-
-
// -----------------------------------------------------------------------
- /** @name Setter methods */
- //@{
-
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the encoding which will be required for use with the XML text read
- * via a stream opened by this input source.
- *
- * <p>This is usually not set, allowing the encoding to be sensed in the
- * usual XML way. However, in some cases, the encoding in the file is known
- * to be incorrect because of intermediate transcoding, for instance
- * encapsulation within a MIME document.
- *
- * @param encodingStr The name of the encoding to force.
- */
+ // Setter methods
+ // -----------------------------------------------------------------------
+ /**
+ * Set the encoding which will be required for use with the XML text read
+ * via a stream opened by this input source.
+ *
+ * <p>This is usually not set, allowing the encoding to be sensed in the
+ * usual XML way. However, in some cases, the encoding in the file is known
+ * to be incorrect because of intermediate transcoding, for instance
+ * encapsulation within a MIME document.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param encodingStr The name of the encoding to force.
+ * @since DOM Level 3
+ */
virtual void setEncoding(const XMLCh* const encodingStr) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the public identifier for this input source.
- *
- * <p>The public identifier is always optional: if the application writer
- * includes one, it will be provided as part of the location information.</p>
- *
- * @param publicId The public identifier as a string.
- * @see #getPublicId
- */
+ /**
+ * Set the public identifier for this input source.
+ *
+ * <p>The public identifier is always optional: if the application writer
+ * includes one, it will be provided as part of the location information.</p>
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param publicId The public identifier as a string.
+ * @see #getPublicId
+ * @since DOM Level 3
+ */
virtual void setPublicId(const XMLCh* const publicId) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the system identifier for this input source.
- *
- * <p>The system id is always required. The public id may be used to map
- * to another system id, but the system id must always be present as a fall
- * back.</p>
- *
- * <p>If the system ID is a URL, it must be fully resolved.</p>
- *
- * @param systemId The system identifier as a string.
- * @see #getSystemId
- */
+ /**
+ * Set the system identifier for this input source.
+ *
+ * <p>The system id is always required. The public id may be used to map
+ * to another system id, but the system id must always be present as a fall
+ * back.</p>
+ *
+ * <p>If the system ID is a URL, it must be fully resolved.</p>
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param systemId The system identifier as a string.
+ * @see #getSystemId
+ * @since DOM Level 3
+ */
virtual void setSystemId(const XMLCh* const systemId) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the base URI to be used for resolving relative URIs to absolute
- * URIs. If the baseURI is itself a relative URI, the behavior is
- * implementation dependent.
- *
- * @param baseURI The base URI.
- * @see #getBaseURI
- */
+ /**
+ * Set the base URI to be used for resolving relative URIs to absolute
+ * URIs. If the baseURI is itself a relative URI, the behavior is
+ * implementation dependent.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param baseURI The base URI.
+ * @see #getBaseURI
+ * @since DOM Level 3
+ */
virtual void setBaseURI(const XMLCh* const baseURI) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Indicates if the parser should issue fatal error if this input source
- * is not found. If set to false, the parser issue warning message instead.
- *
- * @param flag True if the parser should issue fatal error if this input source is not found.
- * If set to false, the parser issue warning message instead. (Default: true)
- *
- * @see #getIssueFatalErrorIfNotFound
- */
+ /**
+ * Indicates if the parser should issue fatal error if this input source
+ * is not found. If set to false, the parser issue warning message instead.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param flag True if the parser should issue fatal error if this input source is not found.
+ * If set to false, the parser issue warning message instead. (Default: true)
+ *
+ * @see #getIssueFatalErrorIfNotFound
+ * @since DOM Level 3
+ */
virtual void setIssueFatalErrorIfNotFound(const bool flag) = 0;
//@}
-
-
-private:
- // -----------------------------------------------------------------------
- // Unimplemented constructors and operators
- // -----------------------------------------------------------------------
- DOMInputSource(const DOMInputSource&);
- void operator=(const DOMInputSource&);
-
};
diff --git a/src/xercesc/dom/DOMLocator.hpp b/src/xercesc/dom/DOMLocator.hpp
index dc7a68a682015474219d91330ba55e6ae1c744a8..a6f7a46ae04776ee764f1efbfe3277399cae17fd 100644
--- a/src/xercesc/dom/DOMLocator.hpp
+++ b/src/xercesc/dom/DOMLocator.hpp
@@ -1,3 +1,6 @@
+#ifndef DOMLocator_HEADER_GUARD_
+#define DOMLocator_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
*
@@ -56,6 +59,9 @@
/*
* $Log$
+ * Revision 1.4 2002/06/06 20:53:06 tng
+ * Documentation Fix: Update the API Documentation for DOM headers
+ *
* Revision 1.3 2002/05/30 19:24:48 knoaman
* documentation update
*
@@ -67,173 +73,174 @@
*
*/
-
-#ifndef DOMLOCATOR_HPP
-#define DOMLOCATOR_HPP
-
#include <xercesc/util/XercesDefs.hpp>
class DOMNode;
/**
- * Introduced in DOM Level 3
- *
- * DOMLocator is an interface that describes a location (e.g. where an error
+ * DOMLocator is an interface that describes a location. (e.g. where an error
* occured).
*
* @see DOMError#DOMError
+ * @since DOM Level 3
*/
class CDOM_EXPORT DOMLocator
{
protected:
- /** @name Constructors */
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
//@{
-
- /** Default constructor */
DOMLocator() {};
-
+ DOMLocator(const DOMLocator &other) {};
+ DOMLocator & operator = (const DOMLocator &other) {return *this;};
//@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
/** @name Destructor */
//@{
-
- /** Desctructor */
- virtual ~DOMLocator()
- {
- }
-
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMLocator() {};
//@}
- /** @name Get function */
+ // -----------------------------------------------------------------------
+ // Virtual DOMLocator interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 3 */
//@{
-
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the line number where the error occured. The value is -1 if there is
- * no line number available.
- *
- * @see #setLineNumber
- */
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
+ /**
+ * Get the line number where the error occured. The value is -1 if there is
+ * no line number available.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @see #setLineNumber
+ * @since DOM Level 3
+ */
virtual XMLSSize_t getLineNumber() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the column number where the error occured. The value is -1 if there
- * is no column number available.
- *
- * @see #setColumnNumber
- */
+ /**
+ * Get the column number where the error occured. The value is -1 if there
+ * is no column number available.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @see #setColumnNumber
+ * @since DOM Level 3
+ */
virtual XMLSSize_t getColumnNumber() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the byte or character offset into the input source, if we're parsing
- * a file or a byte stream then this will be the byte offset into that
- * stream, but if a character media is parsed then the offset will be the
- * character offset. The value is -1 if there is no offset available.
- *
- * @see #setOffset
- */
+ /**
+ * Get the byte or character offset into the input source, if we're parsing
+ * a file or a byte stream then this will be the byte offset into that
+ * stream, but if a character media is parsed then the offset will be the
+ * character offset. The value is -1 if there is no offset available.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @see #setOffset
+ * @since DOM Level 3
+ */
virtual XMLSSize_t getOffset() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the DOM Node where the error occured, or <code>null</code> if there
- * is no node available.
- *
- * @see #setErrorNode
- */
+ /**
+ * Get the DOMNode where the error occured, or <code>null</code> if there
+ * is no node available.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @see #setErrorNode
+ * @since DOM Level 3
+ */
virtual DOMNode* getErrorNode() const = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Get the URI where the error occured, or <code>null</code> if there is no
- * URI available.
- *
- * @see #setURI
- */
+ /**
+ * Get the URI where the error occured, or <code>null</code> if there is no
+ * URI available.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @see #setURI
+ * @since DOM Level 3
+ */
virtual const XMLCh* getURI() const = 0;
- //@}
-
-
- /** @name Set function */
- //@{
-
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the line number of the error
- *
- * @param lineNumber the line number to set
- *
- * @see #getLinNumner
- */
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
+ /**
+ * Set the line number of the error
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param lineNumber the line number to set
+ *
+ * @see #getLinNumner
+ * @since DOM Level 3
+ */
virtual void setLineNumber(const XMLSSize_t lineNumber) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the column number of the error
- *
- * @param columnNumber the column number to set.
- *
- * @see #getColumnNumner
- */
+ /**
+ * Set the column number of the error
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param columnNumber the column number to set.
+ *
+ * @see #getColumnNumner
+ * @since DOM Level 3
+ */
virtual void setColumnNumber(const XMLSSize_t columnNumber) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the byte/character offset.
- *
- * @param offset the byte/characte offset to set.
- *
- * @see #getOffset
- */
+ /**
+ * Set the byte/character offset.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param offset the byte/characte offset to set.
+ *
+ * @see #getOffset
+ * @since DOM Level 3
+ */
virtual void setOffset(const XMLSSize_t offset) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the DOM Node where the error occured
- *
- * @param errorNode the DOM Node to set
- *
- * @see #getErrorNode
- */
+ /**
+ * Set the DOMNode where the error occured
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param errorNode the DOMNode to set
+ *
+ * @see #getErrorNode
+ * @since DOM Level 3
+ */
virtual void setErrorNode(DOMNode* const errorNode) = 0;
- /**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Set the URI where the error occured
- *
- * @param uri the URI to set.
- *
- * @see #getURI
- */
+ /**
+ * Set the URI where the error occured
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param uri the URI to set.
+ *
+ * @see #getURI
+ * @since DOM Level 3
+ */
virtual void setURI(const XMLCh* const uri) = 0;
//@}
-
-
-private :
- /* Unimplemented constructors and operators */
-
- /* Copy constructor */
- DOMLocator(const DOMLocator&);
-
- /* Assignment operator */
- void operator=(const DOMLocator&);
};
#endif
diff --git a/src/xercesc/dom/DOMNamedNodeMap.hpp b/src/xercesc/dom/DOMNamedNodeMap.hpp
index ce5c18b70ccb1400bd2cb2ac79a076e8fb165e8d..4b381debdd68c0b20124499b18e560745736baae 100644
--- a/src/xercesc/dom/DOMNamedNodeMap.hpp
+++ b/src/xercesc/dom/DOMNamedNodeMap.hpp
@@ -67,121 +67,140 @@
class DOMNode;
/**
-* <code>NamedNodeMap</code>s are used to
-* represent collections of nodes that can be accessed by name.
-*
-* Note that <code>NamedNodeMap</code> does not inherit from <code>NodeList</code>;
-* <code>NamedNodeMap</code>s are not maintained in any particular order.
-* Nodes contained in a <code>NamedNodeMap</code> may
-* also be accessed by an ordinal index, but this is simply to allow
-* convenient enumeration of the contents, and
-* does not imply that the DOM specifies an order to these Nodes.
-*/
+ * <code>DOMNamedNodeMap</code>s are used to
+ * represent collections of nodes that can be accessed by name.
+ *
+ * Note that <code>DOMNamedNodeMap</code> does not inherit from <code>DOMNodeList</code>;
+ * <code>DOMNamedNodeMap</code>s are not maintained in any particular order.
+ * Nodes contained in a <code>DOMNamedNodeMap</code> may
+ * also be accessed by an ordinal index, but this is simply to allow
+ * convenient enumeration of the contents, and
+ * does not imply that the DOM specifies an order to these Nodes.
+ *
+ * @since DOM Level 1
+ */
class CDOM_EXPORT DOMNamedNodeMap {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMNamedNodeMap() {};
DOMNamedNodeMap(const DOMNamedNodeMap &other) {};
DOMNamedNodeMap & operator = (const DOMNamedNodeMap &other) {return *this;};
-
-
+ //@}
public:
- /** @name Destructor. */
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
//@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMNamedNodeMap() {};
-
//@}
- /** @name Set functions. */
+ // -----------------------------------------------------------------------
+ // Virtual DOMNamedNodeMap interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
//@{
-
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
/**
- * Adds a node using its <code>nodeName</code> attribute.
- *
- * <br>As the <code>nodeName</code> attribute is used to derive the name
- * which the node must be stored under, multiple nodes of certain types
- * (those that have a "special" string value) cannot be stored as the names
- * would clash. This is seen as preferable to allowing nodes to be aliased.
- * @param arg A node to store in a named node map. The node will later be
- * accessible using the value of the <code>nodeName</code> attribute of
- * the node. If a node with that name is already present in the map, it
- * is replaced by the new one.
- * @return If the new <code>Node</code> replaces an existing node the
- * replaced <code>Node</code> is returned,
- * otherwise <code>null</code> is returned.
- * @exception DOMException
- * WRONG_DOCUMENT_ERR: Raised if <code>arg</code> was created from a
- * different document than the one that created the
- * <code>NamedNodeMap</code>.
- * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this
- * <code>NamedNodeMap</code> is readonly.
- * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an
- * <code>Attr</code> that is already an attribute of another
- * <code>Element</code> object. The DOM user must explicitly clone
- * <code>Attr</code> nodes to re-use them in other elements.
- */
+ * Adds a node using its <code>nodeName</code> attribute.
+ *
+ * <br>As the <code>nodeName</code> attribute is used to derive the name
+ * which the node must be stored under, multiple nodes of certain types
+ * (those that have a "special" string value) cannot be stored as the names
+ * would clash. This is seen as preferable to allowing nodes to be aliased.
+ * @param arg A node to store in a named node map. The node will later be
+ * accessible using the value of the <code>nodeName</code> attribute of
+ * the node. If a node with that name is already present in the map, it
+ * is replaced by the new one.
+ * @return If the new <code>DOMNode</code> replaces an existing node the
+ * replaced <code>DOMNode</code> is returned,
+ * otherwise <code>null</code> is returned.
+ * @exception DOMException
+ * WRONG_DOCUMENT_ERR: Raised if <code>arg</code> was created from a
+ * different document than the one that created the
+ * <code>DOMNamedNodeMap</code>.
+ * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this
+ * <code>DOMNamedNodeMap</code> is readonly.
+ * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an
+ * <code>DOMAttr</code> that is already an attribute of another
+ * <code>DOMElement</code> object. The DOM user must explicitly clone
+ * <code>DOMAttr</code> nodes to re-use them in other elements.
+ * @since DOM Level 1
+ */
virtual DOMNode *setNamedItem(DOMNode *arg) = 0;
- //@}
- /** @name Get functions. */
- //@{
-
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
/**
- * Returns the <code>index</code>th item in the map.
- *
- * If <code>index</code>
- * is greater than or equal to the number of nodes in the map, this returns
- * <code>null</code>.
- * @param index Index into the map.
- * @return The node at the <code>index</code>th position in the
- * <code>NamedNodeMap</code>, or <code>null</code> if that is not a valid
- * index.
- */
+ * Returns the <code>index</code>th item in the map.
+ *
+ * If <code>index</code>
+ * is greater than or equal to the number of nodes in the map, this returns
+ * <code>null</code>.
+ * @param index Index into the map.
+ * @return The node at the <code>index</code>th position in the
+ * <code>DOMNamedNodeMap</code>, or <code>null</code> if that is not a valid
+ * index.
+ * @since DOM Level 1
+ */
virtual DOMNode *item(XMLSize_t index) const = 0;
/**
- * Retrieves a node specified by name.
- *
- * @param name The <code>nodeName</code> of a node to retrieve.
- * @return A <code>DOMNode</code> (of any type) with the specified <code>nodeName</code>, or
- * <code>null</code> if it does not identify any node in
- * the map.
- */
+ * Retrieves a node specified by name.
+ *
+ * @param name The <code>nodeName</code> of a node to retrieve.
+ * @return A <code>DOMNode</code> (of any type) with the specified <code>nodeName</code>, or
+ * <code>null</code> if it does not identify any node in
+ * the map.
+ * @since DOM Level 1
+ */
virtual DOMNode *getNamedItem(const XMLCh *name) const = 0;
/**
- * The number of nodes in the map.
- *
- * The range of valid child node indices is
- * 0 to <code>length-1</code> inclusive.
- */
+ * The number of nodes in the map.
+ *
+ * The range of valid child node indices is
+ * 0 to <code>length-1</code> inclusive.
+ * @since DOM Level 1
+ */
virtual XMLSize_t getLength() const = 0;
- //@}
- /** @name Functions to change the node collection. */
- //@{
-
+ // -----------------------------------------------------------------------
+ // Node methods
+ // -----------------------------------------------------------------------
/**
- * Removes a node specified by name.
- *
- * If the removed node is an
- * <code>Attr</code> with a default value it is immediately replaced.
- * @param name The <code>nodeName</code> of a node to remove.
- * @return The node removed from the map or <code>null</code> if no node
- * with such a name exists.
- * @exception DOMException
- * NOT_FOUND_ERR: Raised if there is no node named <code>name</code> in
- * the map.
- * <br>
- * NO_MODIFICATION_ALLOWED_ERR: Raised if this <code>NamedNodeMap</code>
- * is readonly.
- */
+ * Removes a node specified by name.
+ *
+ * If the removed node is an
+ * <code>DOMAttr</code> with a default value it is immediately replaced.
+ * @param name The <code>nodeName</code> of a node to remove.
+ * @return The node removed from the map or <code>null</code> if no node
+ * with such a name exists.
+ * @exception DOMException
+ * NOT_FOUND_ERR: Raised if there is no node named <code>name</code> in
+ * the map.
+ * <br>
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if this <code>DOMNamedNodeMap</code>
+ * is readonly.
+ * @since DOM Level 1
+ */
virtual DOMNode *removeNamedItem(const XMLCh *name) = 0;
-
//@}
- /** @name Functions introduced in DOM Level 2. */
- //@{
+ /** @name Functions introduced in DOM Level 1 */
+ //@{
/**
* Retrieves a node specified by local name and namespace URI.
*
@@ -191,6 +210,7 @@ public:
* @return A <code>DOMNode</code> (of any type) with the specified
* local name and namespace URI, or <code>null</code> if they do not
* identify any node in the map.
+ * @since DOM Level 2
*/
virtual DOMNode *getNamedItemNS(const XMLCh *namespaceURI,
const XMLCh *localName) const = 0;
@@ -211,11 +231,12 @@ public:
* different document than the one that created the
* <code>DOMNamedNodeMap</code>.
* <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this
- * <code>vNamedNodeMap</code> is readonly.
+ * <code>DOMNamedNodeMap</code> is readonly.
* <br>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an
- * <code>DOM_Attr</code> that is already an attribute of another
- * <code>DOM_Element</code> object. The DOM user must explicitly clone
- * <code>DOM_Attr</code> nodes to re-use them in other elements.
+ * <code>DOMAttr</code> that is already an attribute of another
+ * <code>DOMElement</code> object. The DOM user must explicitly clone
+ * <code>DOMAttr</code> nodes to re-use them in other elements.
+ * @since DOM Level 2
*/
virtual DOMNode *setNamedItemNS(DOMNode *arg) = 0;
@@ -239,10 +260,10 @@ public:
* <br>
* NO_MODIFICATION_ALLOWED_ERR: Raised if this <code>DOMNamedNodeMap</code>
* is readonly.
+ * @since DOM Level 2
*/
virtual DOMNode *removeNamedItemNS(const XMLCh *namespaceURI,
const XMLCh *localName) = 0;
-
//@}
};
diff --git a/src/xercesc/dom/DOMNode.hpp b/src/xercesc/dom/DOMNode.hpp
index fc74ebb7f8650716b6a89626455a849abc35d30e..bd0d4337b1f4d76ac542c4aa51f364e23e6ec4d5 100644
--- a/src/xercesc/dom/DOMNode.hpp
+++ b/src/xercesc/dom/DOMNode.hpp
@@ -69,64 +69,151 @@ class DOMNamedNodeMap;
class DOMNodeList;
/**
- * The <code>Node</code> interface is the primary datatype for the entire
- * Document Object Model.
- *
- * It represents a single node in the document tree.
- * While all objects implementing the <code>Node</code> interface expose
+ * The <code>DOMNode</code> interface is the primary datatype for the entire
+ * Document Object Model. It represents a single node in the document tree.
+ * While all objects implementing the <code>DOMNode</code> interface expose
* methods for dealing with children, not all objects implementing the
- * <code>Node</code> interface may have children. For example,
- * <code>Text</code> nodes may not have children, and adding children to such
- * nodes results in a <code>DOMException</code> being raised.
- * <p>The attributes <code>nodeName</code>, <code>nodeValue</code> and
- * <code>attributes</code> are included as a mechanism to get at node
- * information without casting down to the specific derived interface. In
- * cases where there is no obvious mapping of these attributes for a specific
- * <code>nodeType</code> (e.g., <code>nodeValue</code> for an Element or
- * <code>attributes</code> for a Comment), this returns <code>null</code>.
- * Note that the specialized interfaces may contain additional and more
- * convenient mechanisms to get and set the relevant information.
+ * <code>DOMNode</code> interface may have children. For example,
+ * <code>DOMText</code> nodes may not have children, and adding children to
+ * such nodes results in a <code>DOMException</code> being raised.
+ * <p>The attributes <code>nodeName</code>, <code>nodeValue</code> and
+ * <code>attributes</code> are included as a mechanism to get at node
+ * information without casting down to the specific derived interface. In
+ * cases where there is no obvious mapping of these attributes for a
+ * specific <code>nodeType</code> (e.g., <code>nodeValue</code> for an
+ * <code>DOMElement</code> or <code>attributes</code> for a <code>DOMComment</code>
+ * ), this returns <code>null</code>. Note that the specialized interfaces
+ * may contain additional and more convenient mechanisms to get and set the
+ * relevant information.
+ * <p>The values of <code>nodeName</code>,
+ * <code>nodeValue</code>, and <code>attributes</code> vary according to the
+ * node type as follows:
+ * <table border='1'>
+ * <tr>
+ * <td>Interface</td>
+ * <td>nodeName</td>
+ * <td>nodeValue</td>
+ * <td>attributes</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMAttr</td>
+ * <td valign='top' rowspan='1' colspan='1'>name of
+ * attribute</td>
+ * <td valign='top' rowspan='1' colspan='1'>value of attribute</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMCDATASection</td>
+ * <td valign='top' rowspan='1' colspan='1'><code>"#cdata-section"</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * content of the CDATA Section</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMComment</td>
+ * <td valign='top' rowspan='1' colspan='1'><code>"#comment"</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>content of
+ * the comment</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMDocument</td>
+ * <td valign='top' rowspan='1' colspan='1'><code>"#document"</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMDocumentFragment</td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>"#document-fragment"</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMDocumentType</td>
+ * <td valign='top' rowspan='1' colspan='1'>document type name</td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * null</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMElement</td>
+ * <td valign='top' rowspan='1' colspan='1'>tag name</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * <td valign='top' rowspan='1' colspan='1'>NamedNodeMap</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMEntity</td>
+ * <td valign='top' rowspan='1' colspan='1'>entity name</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMEntityReference</td>
+ * <td valign='top' rowspan='1' colspan='1'>name of entity referenced</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMNotation</td>
+ * <td valign='top' rowspan='1' colspan='1'>notation name</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMProcessingInstruction</td>
+ * <td valign='top' rowspan='1' colspan='1'>target</td>
+ * <td valign='top' rowspan='1' colspan='1'>entire content excluding the target</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * <tr>
+ * <td valign='top' rowspan='1' colspan='1'>DOMText</td>
+ * <td valign='top' rowspan='1' colspan='1'>
+ * <code>"#text"</code></td>
+ * <td valign='top' rowspan='1' colspan='1'>content of the text node</td>
+ * <td valign='top' rowspan='1' colspan='1'>null</td>
+ * </tr>
+ * </table>
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
+ *
+ * @since DOM Level 1
*/
class CDOM_EXPORT DOMNode {
-
- protected:
- /** @name Constructors and assignment operators */
+protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
//@{
- /**
- * Default constructor for DOMNode. Protected, because
- * DOMNode is an abstract base class.
- *
- */
- DOMNode() {};
-
- /**
- * Copy constructor.
- *
- * @param other The object to be copied.
- */
- DOMNode(const DOMNode &other) {};
-
- /**
- * Assignment operator.
- *
- * @param other The source to be assigned.
- */
- DOMNode & operator = (const DOMNode &other) {return *this;};
-
- public:
+ DOMNode() {};
+ DOMNode(const DOMNode &other) {};
+ DOMNode & operator = (const DOMNode &other) {return *this;};
+ //@}
- //@}
- /** @name Destructor. */
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
//@{
- /**
- * Destructor for DOMNode.
- *
- */
- virtual ~DOMNode() {};
-
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMNode() {};
//@}
-
+ // -----------------------------------------------------------------------
+ // Class Types
+ // -----------------------------------------------------------------------
+ /** @name Public Contants */
+ //@{
+ /**
+ * NodeType
+ *
+ * @since DOM Level 1
+ */
enum NodeType {
ELEMENT_NODE = 1,
ATTRIBUTE_NODE = 2,
@@ -142,12 +229,19 @@ class CDOM_EXPORT DOMNode {
NOTATION_NODE = 12,
XML_DECL_NODE = 13
};
+ //@}
- /** @name Get functions. */
+ // -----------------------------------------------------------------------
+ // Virtual DOMNode interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
//@{
-
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
/**
* The name of this node, depending on its type; see the table above.
+ * @since DOM Level 1
*/
virtual const XMLCh * getNodeName() const = 0;
@@ -156,43 +250,48 @@ class CDOM_EXPORT DOMNode {
*
* @exception DOMException
* NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
+ * @since DOM Level 1
*/
virtual const XMLCh * getNodeValue() const = 0;
/**
* An enum value representing the type of the underlying object.
+ * @since DOM Level 1
*/
virtual short getNodeType() const = 0;
/**
* Gets the parent of this node.
*
- * All nodes, except <code>Document</code>,
- * <code>DocumentFragment</code>, and <code>Attr</code> may have a parent.
+ * All nodes, except <code>DOMDocument</code>,
+ * <code>DOMDocumentFragment</code>, and <code>DOMAttr</code> may have a parent.
* However, if a node has just been created and not yet added to the tree,
* or if it has been removed from the tree, a <code>null</code> DOMNode
* is returned.
+ * @since DOM Level 1
*/
virtual DOMNode *getParentNode() const = 0;
/**
- * Gets a <code>NodeList</code> that contains all children of this node.
+ * Gets a <code>DOMNodeList</code> that contains all children of this node.
*
* If there
- * are no children, this is a <code>NodeList</code> containing no nodes.
- * The content of the returned <code>NodeList</code> is "live" in the sense
+ * are no children, this is a <code>DOMNodeList</code> containing no nodes.
+ * The content of the returned <code>DOMNodeList</code> is "live" in the sense
* that, for instance, changes to the children of the node object that
* it was created from are immediately reflected in the nodes returned by
- * the <code>NodeList</code> accessors; it is not a static snapshot of the
- * content of the node. This is true for every <code>NodeList</code>,
+ * the <code>DOMNodeList</code> accessors; it is not a static snapshot of the
+ * content of the node. This is true for every <code>DOMNodeList</code>,
* including the ones returned by the <code>getElementsByTagName</code>
* method.
+ * @since DOM Level 1
*/
virtual DOMNodeList *getChildNodes() const = 0;
/**
* Gets the first child of this node.
*
* If there is no such node, this returns <code>null</code>.
+ * @since DOM Level 1
*/
virtual DOMNode *getFirstChild() const = 0;
@@ -200,6 +299,7 @@ class CDOM_EXPORT DOMNode {
* Gets the last child of this node.
*
* If there is no such node, this returns <code>null</code>.
+ * @since DOM Level 1
*/
virtual DOMNode *getLastChild() const = 0;
@@ -207,6 +307,7 @@ class CDOM_EXPORT DOMNode {
* Gets the node immediately preceding this node.
*
* If there is no such node, this returns <code>null</code>.
+ * @since DOM Level 1
*/
virtual DOMNode *getPreviousSibling() const = 0;
@@ -214,12 +315,14 @@ class CDOM_EXPORT DOMNode {
* Gets the node immediately following this node.
*
* If there is no such node, this returns <code>null</code>.
+ * @since DOM Level 1
*/
virtual DOMNode *getNextSibling() const = 0;
/**
- * Gets a <code>NamedNodeMap</code> containing the attributes of this node (if it
- * is an <code>Element</code>) or <code>null</code> otherwise.
+ * Gets a <code>DOMNamedNodeMap</code> containing the attributes of this node (if it
+ * is an <code>DOMElement</code>) or <code>null</code> otherwise.
+ * @since DOM Level 1
*/
virtual DOMNamedNodeMap *getAttributes() const = 0;
@@ -232,14 +335,13 @@ class CDOM_EXPORT DOMNode {
* which is not used with any <code>DOMDocument</code> yet, this is
* <code>null</code>.
*
+ * @since DOM Level 1
*/
virtual DOMDocument *getOwnerDocument() const = 0;
-
- //@}
- /** @name Cloning function. */
- //@{
-
+ // -----------------------------------------------------------------------
+ // Node methods
+ // -----------------------------------------------------------------------
/**
* Returns a duplicate of this node.
*
@@ -247,30 +349,27 @@ class CDOM_EXPORT DOMNode {
*
* The duplicate node has no parent (
* <code>parentNode</code> returns <code>null</code>.).
- * <br>Cloning an <code>Element</code> copies all attributes and their
+ * <br>Cloning an <code>DOMElement</code> copies all attributes and their
* values, including those generated by the XML processor to represent
* defaulted attributes, but this method does not copy any text it contains
* unless it is a deep clone, since the text is contained in a child
- * <code>Text</code> node. Cloning any other type of node simply returns a
+ * <code>DOMText</code> node. Cloning any other type of node simply returns a
* copy of this node.
* @param deep If <code>true</code>, recursively clone the subtree under the
* specified node; if <code>false</code>, clone only the node itself (and
- * its attributes, if it is an <code>Element</code>).
+ * its attributes, if it is an <code>DOMElement</code>).
* @return The duplicate node.
+ * @since DOM Level 1
*/
virtual DOMNode * cloneNode(bool deep) const = 0;
- //@}
- /** @name Functions to modify the DOM Node. */
- //@{
-
/**
* Inserts the node <code>newChild</code> before the existing child node
* <code>refChild</code>.
*
* If <code>refChild</code> is <code>null</code>,
* insert <code>newChild</code> at the end of the list of children.
- * <br>If <code>newChild</code> is a <code>DocumentFragment</code> object,
+ * <br>If <code>newChild</code> is a <code>DOMDocumentFragment</code> object,
* all of its children are inserted, in the same order, before
* <code>refChild</code>. If the <code>newChild</code> is already in the
* tree, it is first removed. Note that a <code>DOMNode</code> that
@@ -289,6 +388,7 @@ class CDOM_EXPORT DOMNode {
* inserted is readonly.
* <br>NOT_FOUND_ERR: Raised if <code>refChild</code> is not a child of
* this node.
+ * @since DOM Level 1
*/
virtual DOMNode *insertBefore(DOMNode *newChild,
DOMNode *refChild) = 0;
@@ -315,6 +415,7 @@ class CDOM_EXPORT DOMNode {
* <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the new node is readonly.
* <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of
* this node.
+ * @since DOM Level 1
*/
virtual DOMNode *replaceChild(DOMNode *newChild,
DOMNode *oldChild) = 0;
@@ -328,6 +429,7 @@ class CDOM_EXPORT DOMNode {
* NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
* <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of
* this node.
+ * @since DOM Level 1
*/
virtual DOMNode *removeChild(DOMNode *oldChild) = 0;
@@ -337,7 +439,7 @@ class CDOM_EXPORT DOMNode {
*
* If the <code>newChild</code> is already in the tree, it is
* first removed.
- * @param newChild The node to add.If it is a <code>DocumentFragment</code>
+ * @param newChild The node to add.If it is a <code>DOMDocumentFragment</code>
* object, the entire contents of the document fragment are moved into
* the child list of this node
* @return The node added.
@@ -349,48 +451,45 @@ class CDOM_EXPORT DOMNode {
* from a different document than the one that created this node.
* <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the node being
* appended is readonly.
+ * @since DOM Level 1
*/
virtual DOMNode *appendChild(DOMNode *newChild) = 0;
- //@}
- /** @name Query functions. */
- //@{
-
+ // -----------------------------------------------------------------------
+ // Query methods
+ // -----------------------------------------------------------------------
/**
* This is a convenience method to allow easy determination of whether a
* node has any children.
*
* @return <code>true</code> if the node has any children,
* <code>false</code> if the node has no children.
+ * @since DOM Level 1
*/
virtual bool hasChildNodes() const = 0;
-
-
- //@}
- /** @name Set functions. */
- //@{
-
-
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
/**
- * Sets the value of the node.
- *
- * Any node which can have a nodeValue (@see getNodeValue) will
- * also accept requests to set it to a string. The exact response to
- * this varies from node to node -- Attribute, for example, stores
- * its values in its children and has to replace them with a new Text
- * holding the replacement value.
- *
- * For most types of Node, value is null and attempting to set it
- * will throw DOMException(NO_MODIFICATION_ALLOWED_ERR). This will
- * also be thrown if the node is read-only.
- */
+ * Sets the value of the node.
+ *
+ * Any node which can have a nodeValue (@see getNodeValue) will
+ * also accept requests to set it to a string. The exact response to
+ * this varies from node to node -- Attribute, for example, stores
+ * its values in its children and has to replace them with a new Text
+ * holding the replacement value.
+ *
+ * For most types of Node, value is null and attempting to set it
+ * will throw DOMException(NO_MODIFICATION_ALLOWED_ERR). This will
+ * also be thrown if the node is read-only.
+ * @since DOM Level 1
+ */
virtual void setNodeValue(const XMLCh *nodeValue) = 0;
-
//@}
+
/** @name Functions introduced in DOM Level 2. */
//@{
-
/**
* Puts all <CODE>DOMText</CODE>
* nodes in the full depth of the sub-tree underneath this <CODE>DOMNode</CODE>,
@@ -409,7 +508,7 @@ class CDOM_EXPORT DOMNode {
* nodes and <CODE>DOMCDATASection</CODE>
* nodes.</P>
*
- *
+ * @since DOM Level 2
*/
virtual void normalize() = 0;
@@ -426,6 +525,7 @@ class CDOM_EXPORT DOMNode {
* method to return <code>true</code>.
* @return Returns <code>true</code> if the specified feature is supported
* on this node, <code>false</code> otherwise.
+ * @since DOM Level 2
*/
virtual bool isSupported(const XMLCh *feature,
const XMLCh *version) const = 0;
@@ -443,6 +543,7 @@ class CDOM_EXPORT DOMNode {
* such as <CODE>createElement</CODE> from the <CODE>DOMDocument</CODE>
* interface, this is always <CODE>null</CODE>.
*
+ * @since DOM Level 2
*/
virtual const XMLCh * getNamespaceURI() const = 0;
@@ -450,6 +551,7 @@ class CDOM_EXPORT DOMNode {
* Get the <em>namespace prefix</em>
* of this node, or <code>null</code> if it is unspecified.
*
+ * @since DOM Level 2
*/
virtual const XMLCh * getPrefix() const = 0;
@@ -460,7 +562,7 @@ class CDOM_EXPORT DOMNode {
* <code>createElement</code> from the <code>DOMDocument</code> interface,
* it is null.
*
- *
+ * @since DOM Level 2
*/
virtual const XMLCh * getLocalName() const = 0;
@@ -495,6 +597,7 @@ class CDOM_EXPORT DOMNode {
* <CODE>namespaceURI</CODE> of this node is different from
* "http://www.w3.org/2000/xmlns/", or if this node is an attribute and
* the <CODE>qualifiedName</CODE> of this node is "xmlns".
+ * @since DOM Level 2
*/
virtual void setPrefix(const XMLCh * prefix) = 0;
@@ -502,9 +605,9 @@ class CDOM_EXPORT DOMNode {
* Returns whether this node (if it is an element) has any attributes.
* @return <code>true</code> if this node has any attributes,
* <code>false</code> otherwise.
+ * @since DOM Level 2
*/
virtual bool hasAttributes() const = 0;
-
//@}
diff --git a/src/xercesc/dom/DOMNodeFilter.hpp b/src/xercesc/dom/DOMNodeFilter.hpp
index ed79d32a084fb8a4c643ed5adcfbc4965e354627..c92f16001f380d7a4402331831cf642002ecac4f 100644
--- a/src/xercesc/dom/DOMNodeFilter.hpp
+++ b/src/xercesc/dom/DOMNodeFilter.hpp
@@ -61,101 +61,184 @@
* $Id$
*/
-//////////////////////////////////////////////////////////////////////
-// DOMNodeFilter.h: interface for the DOMNodeFilter class.
-//
-//////////////////////////////////////////////////////////////////////
-
#include "DOMNode.hpp"
-class DOMNodeFilterImpl;
-
/**
* Filters are objects that know how to "filter out" nodes. If a
* <code>DOMNodeIterator</code> or <code>DOMTreeWalker</code> is given a
- * filter, it applies the filter before it returns the next node.
- *
- * If the filter says to accept the node, the iterator returns it; otherwise, the
- * iterator looks for the next node and pretends that the node that was rejected
- * was not there.
- *
- * The DOM does not provide any filters. Filter is just an interface that users can
- * implement to provide their own filters.
- *
- * Filters do not need to know how to iterate, nor do they need to know anything
- * about the data structure that is being iterated. This makes it very easy to write
- * filters, since the only thing they have to know how to do is evaluate a single node.
- * One filter may be used with a number of different kinds of iterators, encouraging
- * code reuse.
- *
+ * <code>DOMNodeFilter</code>, it applies the filter before it returns the next
+ * node. If the filter says to accept the node, the traversal logic returns
+ * it; otherwise, traversal looks for the next node and pretends that the
+ * node that was rejected was not there.
+ * <p>The DOM does not provide any filters. <code>DOMNodeFilter</code> is just an
+ * interface that users can implement to provide their own filters.
+ * <p><code>DOMNodeFilters</code> do not need to know how to traverse from node
+ * to node, nor do they need to know anything about the data structure that
+ * is being traversed. This makes it very easy to write filters, since the
+ * only thing they have to know how to do is evaluate a single node. One
+ * filter may be used with a number of different kinds of traversals,
+ * encouraging code reuse.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.
+ * @since DOM Level 2
*/
+
class CDOM_EXPORT DOMNodeFilter
{
- protected:
- DOMNodeFilter() {};
- DOMNodeFilter(const DOMNodeFilter &other) {};
- DOMNodeFilter & operator = (const DOMNodeFilter &other) {return *this;};
+protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
+ DOMNodeFilter() {};
+ DOMNodeFilter(const DOMNodeFilter &other) {};
+ DOMNodeFilter & operator = (const DOMNodeFilter &other) {return *this;};
+ //@}
+
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMNodeFilter() {};
+ //@}
- public:
- /** @name Enumerators for Node Filter */
- //@{
- /*
- * <table><tr><td>FILTER_ACCEPT</td>
- * <td>Accept the node. Navigation methods defined for
- * NodeIterator or TreeWalker will return this node.</td>
- * </tr>
- * <tr>
- * <td>FILTER_REJECT</td>
- * <td>Reject the node. Navigation methods defined for
- * NodeIterator or TreeWalker will not return this
- * node. For TreeWalker, the children of this node will
- * also be rejected. Iterators treat this as a synonym
- * for FILTER_SKIP.</td>
- * </tr>
- * <tr><td>FILTER_SKIP</td>
- * <td>Reject the node. Navigation methods defined for
- * NodeIterator or TreeWalker will not return this
- * node. For both NodeIterator and Treewalker, the
- * children of this node will still be considered.</td>
- * </tr>
- * </table>
- *
- */
- enum FilterAction {FILTER_ACCEPT = 1,
- FILTER_REJECT = 2,
- FILTER_SKIP = 3};
+ // -----------------------------------------------------------------------
+ // Class Types
+ // -----------------------------------------------------------------------
+ /** @name Public Contants */
+ //@{
+ /**
+ * Constants returned by acceptNode.
+ *
+ * <p><code>FILTER_ACCEPT:</code>
+ * Accept the node. Navigation methods defined for
+ * <code>DOMNodeIterator</code> or <code>DOMTreeWalker</code> will return this
+ * node.</p>
+ *
+ * <p><code>FILTER_REJECT:</code>
+ * Reject the node. Navigation methods defined for
+ * <code>DOMNodeIterator</code> or <code>DOMTreeWalker</code> will not return
+ * this node. For <code>DOMTreeWalker</code>, the children of this node
+ * will also be rejected. <code>DOMNodeIterators</code> treat this as a
+ * synonym for <code>FILTER_SKIP.</code></p>
+ *
+ * <p><code>FILTER_SKIP:</code>
+ * Skip this single node. Navigation methods defined for
+ * <code>DOMNodeIterator</code> or <code>DOMTreeWalker</code> will not return
+ * this node. For both <code>DOMNodeIterator</code> and
+ * <code>DOMTreeWalker</code>, the children of this node will still be
+ * considered.</p>
+ *
+ * @since DOM Level 2
+ */
+ enum FilterAction {FILTER_ACCEPT = 1,
+ FILTER_REJECT = 2,
+ FILTER_SKIP = 3};
- enum ShowType {
- SHOW_ALL = 0x0000FFFF,
- SHOW_ELEMENT = 0x00000001,
- SHOW_ATTRIBUTE = 0x00000002,
- SHOW_TEXT = 0x00000004,
- SHOW_CDATA_SECTION = 0x00000008,
- SHOW_ENTITY_REFERENCE = 0x00000010,
- SHOW_ENTITY = 0x00000020,
- SHOW_PROCESSING_INSTRUCTION = 0x00000040,
- SHOW_COMMENT = 0x00000080,
- SHOW_DOCUMENT = 0x00000100,
- SHOW_DOCUMENT_TYPE = 0x00000200,
- SHOW_DOCUMENT_FRAGMENT = 0x00000400,
- SHOW_NOTATION = 0x00000800
- };
- //@}
+ /**
+ * Constants for whatToShow
+ *
+ * <p><code>SHOW_ALL:</code>
+ * Show all <code>DOMNode(s)</code>.</p>
+ *
+ * <p><code>SHOW_ELEMENT:</code>
+ * Show <code>DOMElement</code> nodes.</p>
+ *
+ * <p><code>SHOW_ATTRIBUTE:</code>
+ * Show <code>DOMAttr</code> nodes. This is meaningful only when creating an
+ * <code>DOMNodeIterator</code> or <code>DOMTreeWalker</code> with an
+ * attribute node as its <code>root</code>; in this case, it means that
+ * the attribute node will appear in the first position of the iteration
+ * or traversal. Since attributes are never children of other nodes,
+ * they do not appear when traversing over the document tree.</p>
+ *
+ * <p><code>SHOW_TEXT:</code>
+ * Show <code>DOMText</code> nodes.</p>
+ *
+ * <p><code>SHOW_CDATA_SECTION:</code>
+ * Show <code>DOMCDATASection</code> nodes.</p>
+ *
+ * <p><code>SHOW_ENTITY_REFERENCE:</code>
+ * Show <code>DOMEntityReference</code> nodes.</p>
+ *
+ * <p><code>SHOW_ENTITY:</code>
+ * Show <code>DOMEntity</code> nodes. This is meaningful only when creating
+ * an <code>DOMNodeIterator</code> or <code>DOMTreeWalker</code> with an
+ * <code>DOMEntity</code> node as its <code>root</code>; in this case, it
+ * means that the <code>DOMEntity</code> node will appear in the first
+ * position of the traversal. Since entities are not part of the
+ * document tree, they do not appear when traversing over the document
+ * tree.</p>
+ *
+ * <p><code>SHOW_PROCESSING_INSTRUCTION:</code>
+ * Show <code>DOMProcessingInstruction</code> nodes.</p>
+ *
+ * <p><code>SHOW_COMMENT:</code>
+ * Show <code>DOMComment</code> nodes.</p>
+ *
+ * <p><code>SHOW_DOCUMENT:</code>
+ * Show <code>DOMDocument</code> nodes.</p>
+ *
+ * <p><code>SHOW_DOCUMENT_TYPE:</code>
+ * Show <code>DOMDocumentType</code> nodes.</p>
+ *
+ * <p><code>SHOW_DOCUMENT_FRAGMENT:</code>
+ * Show <code>DOMDocumentFragment</code> nodes.</p>
+ *
+ * <p><code>SHOW_NOTATION:</code>
+ * Show <code>DOMNotation</code> nodes. This is meaningful only when creating
+ * an <code>DOMNodeIterator</code> or <code>DOMTreeWalker</code> with a
+ * <code>DOMNotation</code> node as its <code>root</code>; in this case, it
+ * means that the <code>DOMNotation</code> node will appear in the first
+ * position of the traversal. Since notations are not part of the
+ * document tree, they do not appear when traversing over the document
+ * tree.</p>
+ *
+ * @since DOM Level 2
+ */
+ enum ShowType {
+ SHOW_ALL = 0x0000FFFF,
+ SHOW_ELEMENT = 0x00000001,
+ SHOW_ATTRIBUTE = 0x00000002,
+ SHOW_TEXT = 0x00000004,
+ SHOW_CDATA_SECTION = 0x00000008,
+ SHOW_ENTITY_REFERENCE = 0x00000010,
+ SHOW_ENTITY = 0x00000020,
+ SHOW_PROCESSING_INSTRUCTION = 0x00000040,
+ SHOW_COMMENT = 0x00000080,
+ SHOW_DOCUMENT = 0x00000100,
+ SHOW_DOCUMENT_TYPE = 0x00000200,
+ SHOW_DOCUMENT_FRAGMENT = 0x00000400,
+ SHOW_NOTATION = 0x00000800
+ };
+ //@}
- /** @name Test function. */
- //@{
- /**
- * Test whether a specified node is visible in the logical view of a DOMTreeWalker
- * or DOMNodeIterator. This function will be called by the implementation of
- * DOMTreeWalker and DOMNodeIterator; it is not intended to be called directly from user
- * code.
- *
- * @param node The node to check to see if it passes the filter or not.
- * @return A constant to determine whether the node is accepted, rejected, or skipped.
- */
- virtual short acceptNode (const DOMNode* node) const =0;
- //@}
+ // -----------------------------------------------------------------------
+ // Virtual DOMNodeFilter interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 2 */
+ //@{
+ /**
+ * Test whether a specified node is visible in the logical view of a
+ * <code>DOMTreeWalker</code> or <code>DOMNodeIterator</code>. This function
+ * will be called by the implementation of <code>DOMTreeWalker</code> and
+ * <code>DOMNodeIterator</code>; it is not normally called directly from
+ * user code. (Though you could do so if you wanted to use the same
+ * filter to guide your own application logic.)
+ * @param node The node to check to see if it passes the filter or not.
+ * @return A constant to determine whether the node is accepted,
+ * rejected, or skipped, as defined above.
+ * @since DOM Level 2
+ */
+ virtual short acceptNode (const DOMNode* node) const =0;
+ //@}
};
diff --git a/src/xercesc/dom/DOMNodeIterator.hpp b/src/xercesc/dom/DOMNodeIterator.hpp
index 7952380a4d53ec3a755601682eb2b4b8f9f5ccd3..981504c38f28c6379bd135eb71fb7a70626d9b20 100644
--- a/src/xercesc/dom/DOMNodeIterator.hpp
+++ b/src/xercesc/dom/DOMNodeIterator.hpp
@@ -64,88 +64,142 @@
#include "DOMNodeFilter.hpp"
#include "DOMNode.hpp"
-class DOMNodeIteratorImpl;
-
/**
- * NodeIterators are used to step through a set of nodes
- * e.g. the set of nodes in a NodeList, the document subtree governed by
- * a particular node, the results of a query, or any other set of nodes.
- * The set of nodes to be iterated is determined by the implementation
- * of the NodeIterator. DOM Level 2 specifies a single NodeIterator
- * implementation for document-order traversal of a document
- * subtree. Instances of these iterators are created by calling
- * <code>DocumentTraversal.createNodeIterator()</code>.
- *
+ * <code>DOMNodeIterators</code> are used to step through a set of nodes, e.g.
+ * the set of nodes in a <code>DOMNodeList</code>, the document subtree
+ * governed by a particular <code>DOMNode</code>, the results of a query, or
+ * any other set of nodes. The set of nodes to be iterated is determined by
+ * the implementation of the <code>DOMNodeIterator</code>. DOM Level 2
+ * specifies a single <code>DOMNodeIterator</code> implementation for
+ * document-order traversal of a document subtree. Instances of these
+ * <code>DOMNodeIterators</code> are created by calling
+ * <code>DOMDocumentTraversal</code><code>.createNodeIterator()</code>.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.
+ * @since DOM Level 2
*/
class CDOM_EXPORT DOMNodeIterator
{
- protected:
- DOMNodeIterator() {};
- DOMNodeIterator(const DOMNodeIterator &other) {};
- DOMNodeIterator & operator = (const DOMNodeIterator &other) {return *this;};
+protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
+ DOMNodeIterator() {};
+ DOMNodeIterator(const DOMNodeIterator &other) {};
+ DOMNodeIterator & operator = (const DOMNodeIterator &other) {return *this;};
+ //@}
+
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMNodeIterator() {};
+ //@}
- public:
- /** @name Get functions. */
- //@{
- /**
- * The <code>root</code> node of the <code>NodeIterator</code>, as specified
- * when it was created.
- */
- virtual DOMNode* getRoot() = 0;
- /**
- * Return which node types are presented via the iterator.
- * The available set of constants is defined in the DOMNodeFilter interface.
- *
- */
- virtual unsigned long getWhatToShow() = 0;
+ // -----------------------------------------------------------------------
+ // Virtual DOMNodeFilter interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 2 */
+ //@{
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
+ /**
+ * The <code>root</code> node of the <code>DOMNodeIterator</code>, as specified
+ * when it was created.
+ * @since DOM Level 2
+ */
+ virtual DOMNode* getRoot() = 0;
+ /**
+ * Return which node types are presented via the iterator.
+ * This attribute determines which node types are presented via the
+ * <code>DOMNodeIterator</code>. The available set of constants is defined
+ * in the <code>DOMNodeFilter</code> interface. Nodes not accepted by
+ * <code>whatToShow</code> will be skipped, but their children may still
+ * be considered. Note that this skip takes precedence over the filter,
+ * if any.
+ * @since DOM Level 2
+ *
+ */
+ virtual unsigned long getWhatToShow() = 0;
- /**
- * Return The filter used to screen nodes.
- *
- */
- virtual DOMNodeFilter* getFilter() = 0;
+ /**
+ * The <code>DOMNodeFilter</code> used to screen nodes.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNodeFilter* getFilter() = 0;
- /**
- * Return the expandEntityReferences flag.
- * The value of this flag determines whether the children of entity reference
- * nodes are visible to the DOMNodeFilter. If false, they will be skipped over.
- *
- */
- virtual bool getExpandEntityReferences() = 0;
+ /**
+ * Return the expandEntityReferences flag.
+ * The value of this flag determines whether the children of entity
+ * reference nodes are visible to the <code>DOMNodeIterator</code>. If
+ * false, these children and their descendants will be rejected. Note
+ * that this rejection takes precedence over <code>whatToShow</code> and
+ * the filter. Also note that this is currently the only situation where
+ * <code>DOMNodeIterators</code> may reject a complete subtree rather than
+ * skipping individual nodes.
+ * <br>
+ * <br> To produce a view of the document that has entity references
+ * expanded and does not expose the entity reference node itself, use
+ * the <code>whatToShow</code> flags to hide the entity reference node
+ * and set <code>expandEntityReferences</code> to true when creating the
+ * <code>DOMNodeIterator</code>. To produce a view of the document that has
+ * entity reference nodes but no entity expansion, use the
+ * <code>whatToShow</code> flags to show the entity reference node and
+ * set <code>expandEntityReferences</code> to false.
+ *
+ * @since DOM Level 2
+ */
+ virtual bool getExpandEntityReferences() = 0;
- /**
- * Returns the next node in the set and advances the position of the iterator
- * in the set. After a DOMNodeIterator is created, the first call to nextNode()
- * returns the first node in the set.
- *
- * @exception DOMException
- * INVALID_STATE_ERR: Raised if this method is called after the
- * <code>detach</code> method was invoked.
- */
- virtual DOMNode* nextNode() = 0;
+ // -----------------------------------------------------------------------
+ // Query methods
+ // -----------------------------------------------------------------------
+ /**
+ * Returns the next node in the set and advances the position of the
+ * <code>DOMNodeIterator</code> in the set. After a
+ * <code>DOMNodeIterator</code> is created, the first call to
+ * <code>nextNode()</code> returns the first node in the set.
+ * @return The next <code>DOMNode</code> in the set being iterated over, or
+ * <code>null</code> if there are no more members in that set.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if this method is called after the
+ * <code>detach</code> method was invoked.
+ * @since DOM Level 2
+ */
+ virtual DOMNode* nextNode() = 0;
- /**
- * Returns the previous node in the set and moves the position of the iterator
- * backwards in the set.
- *
- * @exception DOMException
- * INVALID_STATE_ERR: Raised if this method is called after the
- * <code>detach</code> method was invoked.
- */
- virtual DOMNode* previousNode() = 0;
- //@}
+ /**
+ * Returns the previous node in the set and moves the position of the
+ * <code>DOMNodeIterator</code> backwards in the set.
+ * @return The previous <code>DOMNode</code> in the set being iterated over,
+ * or <code>null</code> if there are no more members in that set.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if this method is called after the
+ * <code>detach</code> method was invoked.
+ * @since DOM Level 2
+ */
+ virtual DOMNode* previousNode() = 0;
- /** @name Detaching functions. */
- //@{
- /**
- * Detaches the iterator from the set which it iterated over, releasing any
- * computational resources and placing the iterator in the INVALID state. After
- * <code>detach</code> has been invoked, calls to <code>nextNode</code> or
- * <code>previousNode</code> will raise the exception INVALID_STATE_ERR.
- *
- */
- virtual void detach() = 0;
- //@}
+ /**
+ * Detaches the <code>DOMNodeIterator</code> from the set which it iterated
+ * over, releasing any computational resources and placing the
+ * <code>DOMNodeIterator</code> in the INVALID state. After
+ * <code>detach</code> has been invoked, calls to <code>nextNode</code>
+ * or <code>previousNode</code> will raise the exception
+ * INVALID_STATE_ERR.
+ * @since DOM Level 2
+ */
+ virtual void detach() = 0;
+ //@}
};
#endif
diff --git a/src/xercesc/dom/DOMNodeList.hpp b/src/xercesc/dom/DOMNodeList.hpp
index 3eddd2db5685d3bc00db8c54216e4115386e9d02..cee9a0292c8fc2c16460591d98502d5271f78417 100644
--- a/src/xercesc/dom/DOMNodeList.hpp
+++ b/src/xercesc/dom/DOMNodeList.hpp
@@ -67,43 +67,61 @@ class DOMNode;
/**
- * The <code>NodeList</code> interface provides the abstraction of an ordered
- * collection of nodes. NodeLists are created by DOM_Document::getElementsByTagName(),
- * DOM_Node::getChildNodes(),
+ * The <code>DOMNodeList</code> interface provides the abstraction of an ordered
+ * collection of nodes. DOMNodeLists are created by DOMDocument::getElementsByTagName(),
+ * DOMNode::getChildNodes(),
*
- * <p>The items in the <code>NodeList</code> are accessible via an integral
+ * <p>The items in the <code>DOMNodeList</code> are accessible via an integral
* index, starting from 0.
*
- * NodeLists are "live", in that any changes to the document tree are immediately
- * reflected in any NodeLists that may have been created for that tree.
+ * DOMNodeLists are "live", in that any changes to the document tree are immediately
+ * reflected in any DOMNodeLists that may have been created for that tree.
*/
class CDOM_EXPORT DOMNodeList {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMNodeList() {};
DOMNodeList(const DOMNodeList &other) {};
DOMNodeList & operator = (const DOMNodeList &other) {return *this;};
+ //@}
public:
- /** @name Destructor. */
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
//@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMNodeList() {};
//@}
-
-
- /** @name Get functions. */
+ // -----------------------------------------------------------------------
+ // Virtual DOMNodeList interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
//@{
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
/**
- * Returns the <code>index</code>th item in the collection.
+ * Returns the <code>index</code> item in the collection.
*
* If <code>index</code> is greater than or equal to the number of nodes in
* the list, this returns <code>null</code>.
*
* @param index Index into the collection.
* @return The node at the <code>index</code>th position in the
- * <code>NodeList</code>, or <code>null</code> if that is not a valid
+ * <code>DOMNodeList</code>, or <code>null</code> if that is not a valid
* index.
+ * @since DOM Level 1
*/
virtual DOMNode *item(XMLSize_t index) = 0;
@@ -111,6 +129,7 @@ public:
* Returns the number of nodes in the list.
*
* The range of valid child node indices is 0 to <code>length-1</code> inclusive.
+ * @since DOM Level 1
*/
virtual XMLSize_t getLength() = 0;
//@}
diff --git a/src/xercesc/dom/DOMNotation.hpp b/src/xercesc/dom/DOMNotation.hpp
index 8fb7c397b7219d371956fbdb4f323089ff116baf..c844c07c27bcdace44a6ac1b0201882bb119dbf7 100644
--- a/src/xercesc/dom/DOMNotation.hpp
+++ b/src/xercesc/dom/DOMNotation.hpp
@@ -71,37 +71,64 @@
* the XML 1.0 specification), or is used for formal declaration of
* Processing Instruction targets (see section 2.6 of the XML 1.0
* specification). The <code>nodeName</code> attribute inherited from
- * <code>Node</code> is set to the declared name of the notation.
- * <p>The DOM Level 1 does not support editing <code>Notation</code> nodes;
+ * <code>DOMNode</code> is set to the declared name of the notation.
+ * <p>The DOM Level 1 does not support editing <code>DOMNotation</code> nodes;
* they are therefore readonly.
- * <p>A <code>Notation</code> node does not have any parent.
+ * <p>A <code>DOMNotation</code> node does not have any parent.
+ *
+ * @since DOM Level 1
*/
class CDOM_EXPORT DOMNotation: public DOMNode {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMNotation() {};
DOMNotation(const DOMNotation &other) {};
DOMNotation & operator = (const DOMNotation &other) {return *this;};
+ //@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMNotation() {};
+ //@}
- /** @name Get functions. */
- //@{
+ // -----------------------------------------------------------------------
+ // Virtual DOMNotation interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
+ //@{
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
/**
* Get the public identifier of this notation.
*
* If the public identifier was not
* specified, this is <code>null</code>.
* @return Returns the public identifier of the notation
+ * @since DOM Level 1
*/
virtual const XMLCh *getPublicId() const = 0;
+
/**
* Get the system identifier of this notation.
*
* If the system identifier was not
* specified, this is <code>null</code>.
* @return Returns the system identifier of the notation
+ * @since DOM Level 1
*/
virtual const XMLCh *getSystemId() const = 0;
diff --git a/src/xercesc/dom/DOMProcessingInstruction.hpp b/src/xercesc/dom/DOMProcessingInstruction.hpp
index 69b1b8f983bfb2b70504eee9576af865663e5505..130ddd783d8baf7125df8205174a117015e3b33a 100644
--- a/src/xercesc/dom/DOMProcessingInstruction.hpp
+++ b/src/xercesc/dom/DOMProcessingInstruction.hpp
@@ -67,27 +67,52 @@
/**
- * The <code>ProcessingInstruction</code> interface represents a "processing
+ * The <code>DOMProcessingInstruction</code> interface represents a "processing
* instruction", used in XML as a way to keep processor-specific information
* in the text of the document.
+ *
+ * @since DOM Level 1
*/
class CDOM_EXPORT DOMProcessingInstruction: public DOMNode {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMProcessingInstruction() {};
-
DOMProcessingInstruction(const DOMProcessingInstruction &other) {};
DOMProcessingInstruction & operator = (const DOMProcessingInstruction &other) {return *this;};
+ //@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
virtual ~DOMProcessingInstruction() {};
+ //@}
- /** @name Get functions. */
+ // -----------------------------------------------------------------------
+ // Virtual DOMProcessingInstruction interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
//@{
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
/**
* The target of this processing instruction.
*
* XML defines this as being the
* first token following the markup that begins the processing instruction.
+ *
+ * @since DOM Level 1
*/
virtual const XMLCh * getTarget() const = 0;
@@ -99,20 +124,22 @@ public:
* preceding the <code>?></code>.
* @exception DOMException
* NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
+ * @since DOM Level 1
*/
virtual const XMLCh * getData() const = 0;
- //@}
- /** @name Set functions. */
- //@{
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
/**
- * Sets the content of this processing instruction.
- *
- * This is from the first non
- * white space character after the target to the character immediately
- * preceding the <code>?></code>.
- * @param data The string containing the processing instruction
- */
+ * Sets the content of this processing instruction.
+ *
+ * This is from the first non
+ * white space character after the target to the character immediately
+ * preceding the <code>?></code>.
+ * @param data The string containing the processing instruction
+ * @since DOM Level 1
+ */
virtual void setData(const XMLCh * data) = 0;
//@}
diff --git a/src/xercesc/dom/DOMRange.hpp b/src/xercesc/dom/DOMRange.hpp
index c250055fd71a1367b75466b8674ebdb5b7792cbe..8c5d6928bd477c5824b4fb0586d059a7841581a0 100644
--- a/src/xercesc/dom/DOMRange.hpp
+++ b/src/xercesc/dom/DOMRange.hpp
@@ -66,14 +66,65 @@
class DOMNode;
class DOMDocumentFragment;
+/**
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.
+ * @since DOM Level 2
+ */
class CDOM_EXPORT DOMRange {
protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
DOMRange() {};
DOMRange(const DOMRange &other) {};
DOMRange & operator = (const DOMRange &other) {return *this;};
+ //@}
public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMRange() {};
+ //@}
+ // -----------------------------------------------------------------------
+ // Class Types
+ // -----------------------------------------------------------------------
+ /** @name Public Contants */
+ //@{
+ /**
+ * Constants CompareHow.
+ *
+ * <p><code>START_TO_START:</code>
+ * Compare start boundary-point of <code>sourceRange</code> to start
+ * boundary-point of Range on which <code>compareBoundaryPoints</code>
+ * is invoked.</p>
+ *
+ * <p><code>START_TO_END:</code>
+ * Compare start boundary-point of <code>sourceRange</code> to end
+ * boundary-point of Range on which <code>compareBoundaryPoints</code>
+ * is invoked.</p>
+ *
+ * <p><code>END_TO_END:</code>
+ * Compare end boundary-point of <code>sourceRange</code> to end
+ * boundary-point of Range on which <code>compareBoundaryPoints</code>
+ * is invoked.</p>
+ *
+ * <p><code>END_TO_START:</code>
+ * Compare end boundary-point of <code>sourceRange</code> to start
+ * boundary-point of Range on which <code>compareBoundaryPoints</code>
+ * is invoked.</p>
+ *
+ * @since DOM Level 2
+ */
enum CompareHow {
START_TO_START = 0,
START_TO_END = 1,
@@ -81,42 +132,411 @@ public:
END_TO_START = 3
};
- virtual ~DOMRange() {};
+ //@}
- //getter functions
+ // -----------------------------------------------------------------------
+ // Virtual DOMRange interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 2 */
+ //@{
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
+ /**
+ * DOMNode within which the Range begins
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual DOMNode* getStartContainer() const = 0;
+
+ /**
+ * Offset within the starting node of the Range.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual XMLSize_t getStartOffset() const = 0;
+
+ /**
+ * DOMNode within which the Range ends
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual DOMNode* getEndContainer() const = 0;
+
+ /**
+ * Offset within the ending node of the Range.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual XMLSize_t getEndOffset() const = 0;
+
+ /**
+ * TRUE if the Range is collapsed
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual bool getCollapsed() const = 0;
+
+ /**
+ * The deepest common ancestor container of the Range's two
+ * boundary-points.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual const DOMNode* getCommonAncestorContainer() const = 0;
- //setter functions
- virtual void setStart(const DOMNode *parent, XMLSize_t offset) = 0;
- virtual void setEnd(const DOMNode *parent, XMLSize_t offset) = 0;
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
+ /**
+ * Sets the attributes describing the start of the Range.
+ * @param refNode The <code>refNode</code> value. This parameter must be
+ * different from <code>null</code>.
+ * @param offset The <code>startOffset</code> value.
+ * @exception DOMRangeException
+ * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
+ * of <code>refNode</code> is an DOMEntity, DOMNotation, or DOMDocumentType
+ * node.
+ * @exception DOMException
+ * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater
+ * than the number of child units in <code>refNode</code>. Child units
+ * are 16-bit units if <code>refNode</code> is a type of DOMCharacterData
+ * node (e.g., a DOMText or DOMComment node) or a DOMProcessingInstruction
+ * node. Child units are Nodes in all other cases.
+ * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
+ * been invoked on this object.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
+ * from a different document than the one that created this range.
+ *
+ * @since DOM Level 2
+ */
+ virtual void setStart(const DOMNode *refNode, XMLSize_t offset) = 0;
+
+ /**
+ * Sets the attributes describing the end of a Range.
+ * @param refNode The <code>refNode</code> value. This parameter must be
+ * different from <code>null</code>.
+ * @param offset The <code>endOffset</code> value.
+ * @exception DOMRangeException
+ * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
+ * of <code>refNode</code> is an DOMEntity, DOMNotation, or DOMDocumentType
+ * node.
+ * @exception DOMException
+ * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater
+ * than the number of child units in <code>refNode</code>. Child units
+ * are 16-bit units if <code>refNode</code> is a type of DOMCharacterData
+ * node (e.g., a DOMText or DOMComment node) or a DOMProcessingInstruction
+ * node. Child units are Nodes in all other cases.
+ * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
+ * been invoked on this object.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
+ * from a different document than the one that created this range.
+ *
+ * @since DOM Level 2
+ */
+ virtual void setEnd(const DOMNode *refNode, XMLSize_t offset) = 0;
+ /**
+ * Sets the start position to be before a node
+ * @param refNode Range starts before <code>refNode</code>
+ * @exception DOMRangeException
+ * INVALID_NODE_TYPE_ERR: Raised if the root container of
+ * <code>refNode</code> is not an DOMAttr, DOMDocument, or DOMDocumentFragment
+ * node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment,
+ * DOMAttr, DOMEntity, or DOMNotation node.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
+ * from a different document than the one that created this range.
+ *
+ * @since DOM Level 2
+ */
virtual void setStartBefore(const DOMNode *refNode) = 0;
+
+ /**
+ * Sets the start position to be after a node
+ * @param refNode Range starts after <code>refNode</code>
+ * @exception DOMRangeException
+ * INVALID_NODE_TYPE_ERR: Raised if the root container of
+ * <code>refNode</code> is not an DOMAttr, DOMDocument, or DOMDocumentFragment
+ * node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment,
+ * DOMAttr, DOMEntity, or DOMNotation node.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
+ * from a different document than the one that created this range.
+ *
+ * @since DOM Level 2
+ */
virtual void setStartAfter(const DOMNode *refNode) = 0;
+
+ /**
+ * Sets the end position to be before a node.
+ * @param refNode Range ends before <code>refNode</code>
+ * @exception DOMRangeException
+ * INVALID_NODE_TYPE_ERR: Raised if the root container of
+ * <code>refNode</code> is not an DOMAttr, DOMDocument, or DOMDocumentFragment
+ * node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment,
+ * DOMAttr, DOMEntity, or DOMNotation node.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
+ * from a different document than the one that created this range.
+ *
+ * @since DOM Level 2
+ */
virtual void setEndBefore(const DOMNode *refNode) = 0;
+
+ /**
+ * Sets the end of a Range to be after a node
+ * @param refNode Range ends after <code>refNode</code>.
+ * @exception DOMRangeException
+ * INVALID_NODE_TYPE_ERR: Raised if the root container of
+ * <code>refNode</code> is not a DOMAttr, DOMDocument or DOMDocumentFragment
+ * node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment,
+ * DOMAttr, DOMEntity, or DOMNotation node.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
+ * from a different document than the one that created this range.
+ *
+ * @since DOM Level 2
+ */
virtual void setEndAfter(const DOMNode *refNode) = 0;
- //misc functions
+ // -----------------------------------------------------------------------
+ // Misc methods
+ // -----------------------------------------------------------------------
+ /**
+ * Collapse a Range onto one of its boundary-points
+ * @param toStart If TRUE, collapses the Range onto its start; if FALSE,
+ * collapses it onto its end.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual void collapse(bool toStart) = 0;
- virtual void selectNode(const DOMNode *node) = 0;
- virtual void selectNodeContents(const DOMNode *node) = 0;
- //Functions related to comparing range Boundrary-Points
- virtual short compareBoundaryPoints(CompareHow how, const DOMRange* range) const = 0;
+ /**
+ * Select a node and its contents
+ * @param refNode The node to select.
+ * @exception DOMRangeException
+ * INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code>
+ * is an DOMEntity, DOMNotation or DOMDocumentType node or if
+ * <code>refNode</code> is a DOMDocument, DOMDocumentFragment, DOMAttr, DOMEntity,
+ * or DOMNotation node.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
+ * from a different document than the one that created this range.
+ *
+ * @since DOM Level 2
+ */
+ virtual void selectNode(const DOMNode *refNode) = 0;
+
+ /**
+ * Select the contents within a node
+ * @param refNode DOMNode to select from
+ * @exception DOMRangeException
+ * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
+ * of <code>refNode</code> is an DOMEntity, DOMNotation or DOMDocumentType node.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
+ * from a different document than the one that created this range.
+ *
+ * @since DOM Level 2
+ */
+ virtual void selectNodeContents(const DOMNode *refNode) = 0;
+
+ /**
+ * Compare the boundary-points of two Ranges in a document.
+ * @param how A code representing the type of comparison, as defined
+ * above.
+ * @param sourceRange The <code>Range</code> on which this current
+ * <code>Range</code> is compared to.
+ * @return -1, 0 or 1 depending on whether the corresponding
+ * boundary-point of the Range is respectively before, equal to, or
+ * after the corresponding boundary-point of <code>sourceRange</code>.
+ * @exception DOMException
+ * WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same
+ * DOMDocument or DOMDocumentFragment.
+ * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
+ * been invoked on this object.
+ *
+ * @since DOM Level 2
+ */
+ virtual short compareBoundaryPoints(CompareHow how, const DOMRange* sourceRange) const = 0;
+
+ /**
+ * Removes the contents of a Range from the containing document or
+ * document fragment without returning a reference to the removed
+ * content.
+ * @exception DOMException
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
+ * the Range is read-only or any of the nodes that contain any of the
+ * content of the Range are read-only.
+ * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
+ * been invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual void deleteContents() = 0;
+
+ /**
+ * Moves the contents of a Range from the containing document or document
+ * fragment to a new DOMDocumentFragment.
+ * @return A DOMDocumentFragment containing the extracted contents.
+ * @exception DOMException
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
+ * the Range is read-only or any of the nodes which contain any of the
+ * content of the Range are read-only.
+ * <br>HIERARCHY_REQUEST_ERR: Raised if a DOMDocumentType node would be
+ * extracted into the new DOMDocumentFragment.
+ * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
+ * been invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual DOMDocumentFragment* extractContents() = 0;
+
+ /**
+ * Duplicates the contents of a Range
+ * @return A DOMDocumentFragment that contains content equivalent to this
+ * Range.
+ * @exception DOMException
+ * HIERARCHY_REQUEST_ERR: Raised if a DOMDocumentType node would be
+ * extracted into the new DOMDocumentFragment.
+ * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
+ * been invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual DOMDocumentFragment* cloneContents() const = 0;
- virtual void insertNode(DOMNode *node) = 0;
- //Misc functions
- virtual void surroundContents(DOMNode *node) = 0;
+
+ /**
+ * Inserts a node into the DOMDocument or DOMDocumentFragment at the start of
+ * the Range. If the container is a DOMText node, this will be split at the
+ * start of the Range (as if the DOMText node's splitText method was
+ * performed at the insertion point) and the insertion will occur
+ * between the two resulting DOMText nodes. Adjacent DOMText nodes will not be
+ * automatically merged. If the node to be inserted is a
+ * DOMDocumentFragment node, the children will be inserted rather than the
+ * DOMDocumentFragment node itself.
+ * @param newNode The node to insert at the start of the Range
+ * @exception DOMException
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the
+ * start of the Range is read-only.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the
+ * container of the start of the Range were not created from the same
+ * document.
+ * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
+ * the Range is of a type that does not allow children of the type of
+ * <code>newNode</code> or if <code>newNode</code> is an ancestor of
+ * the container.
+ * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
+ * been invoked on this object.
+ * @exception DOMRangeException
+ * INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an DOMAttr,
+ * DOMEntity, DOMNotation, or DOMDocument node.
+ *
+ * @since DOM Level 2
+ */
+ virtual void insertNode(DOMNode *newNode) = 0;
+
+ /**
+ * Reparents the contents of the Range to the given node and inserts the
+ * node at the position of the start of the Range.
+ * @param newParent The node to surround the contents with.
+ * @exception DOMException
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of
+ * either boundary-point of the Range is read-only.
+ * <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the
+ * container of the start of the Range were not created from the same
+ * document.
+ * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
+ * the Range is of a type that does not allow children of the type of
+ * <code>newParent</code> or if <code>newParent</code> is an ancestor
+ * of the container or if <code>node</code> would end up with a child
+ * node of a type not allowed by the type of <code>node</code>.
+ * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
+ * been invoked on this object.
+ * @exception DOMRangeException
+ * BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a
+ * non-text node.
+ * <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an DOMAttr,
+ * DOMEntity, DOMDocumentType, DOMNotation, DOMDocument, or DOMDocumentFragment node.
+ *
+ * @since DOM Level 2
+ */
+ virtual void surroundContents(DOMNode *newParent) = 0;
+
+ /**
+ * Produces a new Range whose boundary-points are equal to the
+ * boundary-points of the Range.
+ * @return The duplicated Range.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual DOMRange* cloneRange() const = 0;
+
+ /**
+ * Returns the contents of a Range as a string. This string contains only
+ * the data characters, not any markup.
+ * @return The contents of the Range.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual const XMLCh* toString() const = 0;
+
+ /**
+ * Called to indicate that the Range is no longer in use and that the
+ * implementation may relinquish any resources associated with this
+ * Range. Subsequent calls to any methods or attribute getters on this
+ * Range will result in a <code>DOMException</code> being thrown with an
+ * error code of <code>INVALID_STATE_ERR</code>.
+ * @exception DOMException
+ * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
+ * invoked on this object.
+ *
+ * @since DOM Level 2
+ */
virtual void detach() = 0;
+ //@}
+
};
diff --git a/src/xercesc/dom/DOMRangeException.hpp b/src/xercesc/dom/DOMRangeException.hpp
index 2b62e297a6e7b3ffb687e3a31a4c71087deb8811..6c8a243cefd6ec09f0885a09c44803bfb267190b 100644
--- a/src/xercesc/dom/DOMRangeException.hpp
+++ b/src/xercesc/dom/DOMRangeException.hpp
@@ -64,31 +64,42 @@
#include <xercesc/dom/DOMException.hpp>
/**
- * Encapsulate range related DOM error or warning. DOM level 2 implementation.
- *
- * <p> The DOM will create and throw an instance of DOMRangeException
- * when an error condition in range is detected. Exceptions can occur
- * when an application directly manipulates the range elements in DOM document
- * tree that is produced by the parser.
- *
- * <p>Unlike the other classes in the C++ DOM API, DOMRangeException
- * is NOT a reference to an underlying implementation class, and
- * does not provide automatic memory management. Code that catches
- * a DOM Range exception is responsible for deleting it, or otherwise
- * arranging for its disposal.
- *
- */
+ * Range operations may throw a <code>DOMRangeException</code> as specified in
+ * their method descriptions.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.
+ * @since DOM Level 2
+ */
class CDOM_EXPORT DOMRangeException : public DOMException {
public:
- /** @name Enumerators for DOM Range Exceptions */
+ // -----------------------------------------------------------------------
+ // Class Types
+ // -----------------------------------------------------------------------
+ /** @name Public Contants */
//@{
+ /**
+ * Enumerators for DOM Range Exceptions
+ *
+ * <p><code>BAD_BOUNDARYPOINTS_ERR:</code>
+ * If the boundary-points of a Range do not meet specific requirements.</p>
+ *
+ * <p><code>INVALID_NODE_TYPE_ERR:</code>
+ * If the container of an boundary-point of a Range is being set to either
+ * a node of an invalid type or a node with an ancestor of an invalid
+ * type.</p>
+ *
+ * @since DOM Level 2
+ */
enum RangeExceptionCode {
BAD_BOUNDARYPOINTS_ERR = 1,
INVALID_NODE_TYPE_ERR = 2
};
//@}
+
public:
- /** @name Constructors and assignment operator */
+ // -----------------------------------------------------------------------
+ // Constructors
+ // -----------------------------------------------------------------------
+ /** @name Constructors */
//@{
/**
* Default constructor for DOMRangeException.
@@ -110,26 +121,33 @@ public:
* @param other The object to be copied.
*/
DOMRangeException(const DOMRangeException &other);
-
//@}
+
+ // -----------------------------------------------------------------------
+ // Destructors
+ // -----------------------------------------------------------------------
/** @name Destructor. */
//@{
/**
- * Destructor for DOMRangeException. Applications are responsible
- * for deleting DOMRangeException objects that they catch after they
- * have completed their exception processing.
+ * Destructor for DOMRangeException.
*
*/
virtual ~DOMRangeException();
//@}
- /** @name Public variables. */
- //@{
+public:
+ // -----------------------------------------------------------------------
+ // Class Types
+ // -----------------------------------------------------------------------
+ /** @name Public variables */
+ //@{
/**
* A code value, from the set defined by the RangeExceptionCode enum,
- * indicating the type of error that occured.
+ * indicating the type of error that occured.
+ *
+ * @since DOM Level 2
*/
- RangeExceptionCode code;
+ RangeExceptionCode code;
//@}
diff --git a/src/xercesc/dom/DOMText.hpp b/src/xercesc/dom/DOMText.hpp
index ea93912ebd03b717a785c5cafc3be435f25d2f0c..0c9cd52dd66a55d20c7fe07a119589e8c69bdf41 100644
--- a/src/xercesc/dom/DOMText.hpp
+++ b/src/xercesc/dom/DOMText.hpp
@@ -67,51 +67,55 @@
/**
- * The <code>Text</code> interface inherits from <code>CharacterData</code>
+ * The <code>DOMText</code> interface inherits from <code>DOMCharacterData</code>
* and represents the textual content (termed character data in XML) of an
- * <code>Element</code> or <code>Attr</code>. If there is no markup inside
+ * <code>DOMElement</code> or <code>DOMAttr</code>. If there is no markup inside
* an element's content, the text is contained in a single object
- * implementing the <code>Text</code> interface that is the only child of
+ * implementing the <code>DOMText</code> interface that is the only child of
* the element. If there is markup, it is parsed into the information items
- * (elements, comments, etc.) and <code>Text</code> nodes that form the list
+ * (elements, comments, etc.) and <code>DOMText</code> nodes that form the list
* of children of the element.
* <p>When a document is first made available via the DOM, there is only one
- * <code>Text</code> node for each block of text. Users may create adjacent
- * <code>Text</code> nodes that represent the contents of a given element
+ * <code>DOMText</code> node for each block of text. Users may create adjacent
+ * <code>DOMText</code> nodes that represent the contents of a given element
* without any intervening markup, but should be aware that there is no way
* to represent the separations between these nodes in XML or HTML, so they
* will not (in general) persist between DOM editing sessions. The
- * <code>normalize()</code> method on <code>Node</code> merges any such
- * adjacent <code>Text</code> objects into a single node for each block of
+ * <code>normalize()</code> method on <code>DOMNode</code> merges any such
+ * adjacent <code>DOMText</code> objects into a single node for each block of
* text.
* <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
*/
class CDOM_EXPORT DOMText: public DOMCharacterData {
-
- protected:
- /** @name Constructors and assignment operator */
+protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
//@{
- DOMText() {};
-
- DOMText(const DOMText &other) {};
-
- DOMText & operator = (const DOMText &other) {return *this;};
- //@}
+ DOMText() {};
+ DOMText(const DOMText &other) {};
+ DOMText & operator = (const DOMText &other) {return *this;};
+ //@}
- public:
- /** @name Destructor. */
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
//@{
- /**
- * Destructor for DOMText. The object being destroyed is the reference
- * object, not the underlying Comment node itself.
- *
- */
- virtual ~DOMText() {};
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMText() {};
//@}
- /** @name Functions to modify the Text node. */
+ // -----------------------------------------------------------------------
+ // Virtual DOMText interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 1 */
//@{
-
/**
* Breaks this node into two nodes at the specified <code>offset</code>,
* keeping both in the tree as siblings. After being split, this node
@@ -128,13 +132,18 @@ class CDOM_EXPORT DOMText: public DOMCharacterData {
* INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
* than the number of 16-bit units in <code>data</code>.
* <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
+ * @since DOM Level 1
*/
virtual DOMText *splitText(XMLSize_t offset) = 0;
//@}
- /** @name Non-standard (not defined by the DOM specification) functions. */
+ // -----------------------------------------------------------------------
+ // Non-standard extension
+ // -----------------------------------------------------------------------
+ /** @name Non-standard extension */
//@{
/**
+ * Non-standard extension
*
* Return true if this node contains ignorable whitespaces only.
* @return True if this node contains ignorable whitespaces only.
diff --git a/src/xercesc/dom/DOMTreeWalker.hpp b/src/xercesc/dom/DOMTreeWalker.hpp
index 78edc5a4f975ad45cd7e7255d888b5eb8a3ff97b..e31ac5f3ed6a86128be27bc6bc54ce072f289c00 100644
--- a/src/xercesc/dom/DOMTreeWalker.hpp
+++ b/src/xercesc/dom/DOMTreeWalker.hpp
@@ -67,131 +67,221 @@
/**
* <code>DOMTreeWalker</code> objects are used to navigate a document tree or
- * subtree using the view of the document defined by its <code>whatToShow</code>
- * flags and any filters that are defined for the <code>DOMTreeWalker</code>. Any
- * function which performs navigation using a <code>DOMTreeWalker</code> will
- * automatically support any view defined by a <code>DOMTreeWalker</code>.
- *
- * Omitting nodes from the logical view of a subtree can result in a structure that is
- * substantially different from the same subtree in the complete, unfiltered document. Nodes
- * that are siblings in the DOMTreeWalker view may be children of different, widely separated
- * nodes in the original view. For instance, consider a Filter that skips all nodes except for
- * Text nodes and the root node of a document. In the logical view that results, all text
- * nodes will be siblings and appear as direct children of the root node, no matter how
- * deeply nested the structure of the original document.
+ * subtree using the view of the document defined by their
+ * <code>whatToShow</code> flags and filter (if any). Any function which
+ * performs navigation using a <code>DOMTreeWalker</code> will automatically
+ * support any view defined by a <code>DOMTreeWalker</code>.
+ * <p>Omitting nodes from the logical view of a subtree can result in a
+ * structure that is substantially different from the same subtree in the
+ * complete, unfiltered document. Nodes that are siblings in the
+ * <code>DOMTreeWalker</code> view may be children of different, widely
+ * separated nodes in the original view. For instance, consider a
+ * <code>DOMNodeFilter</code> that skips all nodes except for DOMText nodes and
+ * the root node of a document. In the logical view that results, all text
+ * nodes will be siblings and appear as direct children of the root node, no
+ * matter how deeply nested the structure of the original document.
+ * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.
*
+ * @since DOM Level 2
*/
class CDOM_EXPORT DOMTreeWalker {
- protected:
- DOMTreeWalker() {};
- DOMTreeWalker(const DOMTreeWalker &other) {};
- DOMTreeWalker & operator = (const DOMTreeWalker &other) {return *this;};
-
- public:
- /** @name Get functions. */
- //@{
- /**
- * The <code>root</code> node of the <code>TreeWalker</code>, as specified
- * when it was created.
- */
- virtual DOMNode* getRoot() = 0;
- /**
- * Return which node types are presented via the DOMTreeWalker.
- * These constants are defined in the DOMNodeFilter interface.
- *
- */
- virtual unsigned long getWhatToShow()= 0;
-
- /**
- * Return The filter used to screen nodes.
- *
- */
- virtual DOMNodeFilter* getFilter()= 0;
-
- /**
- * Return the expandEntityReferences flag.
- * The value of this flag determines whether the children of entity reference
- * nodes are visible to the DOMTreeWalker. If false, they will be skipped over.
- *
- */
- virtual bool getExpandEntityReferences()= 0;
-
- /**
- * Return the node at which the DOMTreeWalker is currently positioned.
- *
- */
- virtual DOMNode* getCurrentNode()= 0;
-
- /**
- * Moves to and returns the closest visible ancestor node of the current node.
- * If the search for parentNode attempts to step upward from the DOMTreeWalker's root
- * node, or if it fails to find a visible ancestor node, this method retains the
- * current position and returns null.
- *
- */
- virtual DOMNode* parentNode()= 0;
-
- /**
- * Moves the <code>DOMTreeWalker</code> to the first child of the current node,
- * and returns the new node. If the current node has no children, returns
- * <code>null</code>, and retains the current node.
- *
- */
- virtual DOMNode* firstChild()= 0;
-
- /**
- * Moves the <code>DOMTreeWalker</code> to the last child of the current node, and
- * returns the new node. If the current node has no children, returns
- * <code>null</code>, and retains the current node.
- *
- */
- virtual DOMNode* lastChild()= 0;
-
- /**
- * Moves the <code>DOMTreeWalker</code> to the previous sibling of the current
- * node, and returns the new node. If the current node has no previous sibling,
- * returns <code>null</code>, and retains the current node.
- *
- */
- virtual DOMNode* previousSibling()= 0;
-
- /**
- * Moves the <code>DOMTreeWalker</code> to the next sibling of the current node,
- * and returns the new node. If the current node has no next sibling, returns
- * <code>null</code>, and retains the current node.
- *
- */
- virtual DOMNode* nextSibling()= 0;
-
- /**
- * Moves the <code>DOMTreeWalker</code> to the previous visible node in document
- * order relative to the current node, and returns the new node. If the current
- * node has no previous node,
- * or if the search for previousNode attempts to step upward from the DOMTreeWalker's
- * root node, returns <code>null</code>, and retains the current node.
- *
- */
- virtual DOMNode* previousNode()= 0;
-
- /**
- * Moves the <code>DOMTreeWalker</code> to the next visible node in document order
- * relative to the current node, and returns the new node. If the current node has
- * no next node,
- * or if the search for nextNode attempts to step upward from the DOMTreeWalker's
- * root node, returns <code>null</code>, and retains the current node.
- *
- */
- virtual DOMNode* nextNode()= 0;
- //@}
-
- /** @name Set functions. */
- //@{
- /**
- * Set the node at which the DOMTreeWalker is currently positioned.
- *
- */
- virtual void setCurrentNode(DOMNode* currentNode)= 0;
- //@}
+protected :
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
+ DOMTreeWalker() {};
+ DOMTreeWalker(const DOMTreeWalker &other) {};
+ DOMTreeWalker & operator = (const DOMTreeWalker &other) {return *this;};
+ //@}
+
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMTreeWalker() {};
+ //@}
+
+ // -----------------------------------------------------------------------
+ // Virtual DOMTreeWalker interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 2 */
+ //@{
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
+
+ /**
+ * The <code>root</code> node of the <code>DOMTreeWalker</code>, as specified
+ * when it was created.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNode* getRoot() = 0;
+ /**
+ * This attribute determines which node types are presented via the
+ * <code>DOMTreeWalker</code>. The available set of constants is defined in
+ * the <code>DOMNodeFilter</code> interface. Nodes not accepted by
+ * <code>whatToShow</code> will be skipped, but their children may still
+ * be considered. Note that this skip takes precedence over the filter,
+ * if any.
+ *
+ * @since DOM Level 2
+ */
+ virtual unsigned long getWhatToShow()= 0;
+
+ /**
+ * Return The filter used to screen nodes.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNodeFilter* getFilter()= 0;
+
+ /**
+ * The value of this flag determines whether the children of entity
+ * reference nodes are visible to the <code>DOMTreeWalker</code>. If false,
+ * these children and their descendants will be rejected. Note that
+ * this rejection takes precedence over <code>whatToShow</code> and the
+ * filter, if any.
+ * <br> To produce a view of the document that has entity references
+ * expanded and does not expose the entity reference node itself, use
+ * the <code>whatToShow</code> flags to hide the entity reference node
+ * and set <code>expandEntityReferences</code> to true when creating the
+ * <code>DOMTreeWalker</code>. To produce a view of the document that has
+ * entity reference nodes but no entity expansion, use the
+ * <code>whatToShow</code> flags to show the entity reference node and
+ * set <code>expandEntityReferences</code> to false.
+ *
+ * @since DOM Level 2
+ */
+ virtual bool getExpandEntityReferences()= 0;
+
+ /**
+ * Return the node at which the DOMTreeWalker is currently positioned.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNode* getCurrentNode()= 0;
+
+ // -----------------------------------------------------------------------
+ // Query methods
+ // -----------------------------------------------------------------------
+ /**
+ * Moves to and returns the closest visible ancestor node of the current
+ * node. If the search for <code>parentNode</code> attempts to step
+ * upward from the <code>DOMTreeWalker</code>'s <code>root</code> node, or
+ * if it fails to find a visible ancestor node, this method retains the
+ * current position and returns <code>null</code>.
+ * @return The new parent node, or <code>null</code> if the current node
+ * has no parent in the <code>DOMTreeWalker</code>'s logical view.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNode* parentNode()= 0;
+
+ /**
+ * Moves the <code>DOMTreeWalker</code> to the first visible child of the
+ * current node, and returns the new node. If the current node has no
+ * visible children, returns <code>null</code>, and retains the current
+ * node.
+ * @return The new node, or <code>null</code> if the current node has no
+ * visible children in the <code>DOMTreeWalker</code>'s logical view.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNode* firstChild()= 0;
+
+ /**
+ * Moves the <code>DOMTreeWalker</code> to the last visible child of the
+ * current node, and returns the new node. If the current node has no
+ * visible children, returns <code>null</code>, and retains the current
+ * node.
+ * @return The new node, or <code>null</code> if the current node has no
+ * children in the <code>DOMTreeWalker</code>'s logical view.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNode* lastChild()= 0;
+
+ /**
+ * Moves the <code>DOMTreeWalker</code> to the previous sibling of the
+ * current node, and returns the new node. If the current node has no
+ * visible previous sibling, returns <code>null</code>, and retains the
+ * current node.
+ * @return The new node, or <code>null</code> if the current node has no
+ * previous sibling. in the <code>DOMTreeWalker</code>'s logical view.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNode* previousSibling()= 0;
+
+ /**
+ * Moves the <code>DOMTreeWalker</code> to the next sibling of the current
+ * node, and returns the new node. If the current node has no visible
+ * next sibling, returns <code>null</code>, and retains the current node.
+ * @return The new node, or <code>null</code> if the current node has no
+ * next sibling. in the <code>DOMTreeWalker</code>'s logical view.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNode* nextSibling()= 0;
+
+ /**
+ * Moves the <code>DOMTreeWalker</code> to the previous visible node in
+ * document order relative to the current node, and returns the new
+ * node. If the current node has no previous node, or if the search for
+ * <code>previousNode</code> attempts to step upward from the
+ * <code>DOMTreeWalker</code>'s <code>root</code> node, returns
+ * <code>null</code>, and retains the current node.
+ * @return The new node, or <code>null</code> if the current node has no
+ * previous node in the <code>DOMTreeWalker</code>'s logical view.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNode* previousNode()= 0;
+
+ /**
+ * Moves the <code>DOMTreeWalker</code> to the next visible node in document
+ * order relative to the current node, and returns the new node. If the
+ * current node has no next node, or if the search for nextNode attempts
+ * to step upward from the <code>DOMTreeWalker</code>'s <code>root</code>
+ * node, returns <code>null</code>, and retains the current node.
+ * @return The new node, or <code>null</code> if the current node has no
+ * next node in the <code>DOMTreeWalker</code>'s logical view.
+ *
+ * @since DOM Level 2
+ */
+ virtual DOMNode* nextNode()= 0;
+
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
+ /**
+ * The node at which the <code>DOMTreeWalker</code> is currently positioned.
+ * <br>Alterations to the DOM tree may cause the current node to no longer
+ * be accepted by the <code>DOMTreeWalker</code>'s associated filter.
+ * <code>currentNode</code> may also be explicitly set to any node,
+ * whether or not it is within the subtree specified by the
+ * <code>root</code> node or would be accepted by the filter and
+ * <code>whatToShow</code> flags. Further traversal occurs relative to
+ * <code>currentNode</code> even if it is not part of the current view,
+ * by applying the filters in the requested direction; if no traversal
+ * is possible, <code>currentNode</code> is not changed.
+ * @exception DOMException
+ * NOT_SUPPORTED_ERR: Raised if an attempt is made to set
+ * <code>currentNode</code> to <code>null</code>.
+ *
+ * @since DOM Level 2
+ */
+ virtual void setCurrentNode(DOMNode* currentNode)= 0;
+ //@}
};
#endif
diff --git a/src/xercesc/dom/DOMWriter.hpp b/src/xercesc/dom/DOMWriter.hpp
index 23944f461f2730a2d257c37434fbd3e4f95c4417..1f991c1d415e7aaf0a90e4d6f5a93820bcd0b595 100644
--- a/src/xercesc/dom/DOMWriter.hpp
+++ b/src/xercesc/dom/DOMWriter.hpp
@@ -1,3 +1,6 @@
+#ifndef DOMWriter_HEADER_GUARD_
+#define DOMWriter_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
*
@@ -57,6 +60,9 @@
/*
* $Id$
* $Log$
+ * Revision 1.5 2002/06/06 20:53:07 tng
+ * Documentation Fix: Update the API Documentation for DOM headers
+ *
* Revision 1.4 2002/06/03 22:33:21 peiyongz
* DOMWriter: constants moved to XMLUni
*
@@ -72,8 +78,6 @@
*/
/**
- *
- * Introduced in DOM Level 3
*
* DOMWriter provides an API for serializing (writing) a DOM document out in
* an XML document. The XML data is written to an output stream, the type of
@@ -107,7 +111,7 @@
* unrepresentable characters in a CDATA section are reported as errors. The
* error is not recoverable - there is no mechanism for supplying
* alternative characters and continuing with the serialization. All other
- * node types (Element, Text, etc.) are serialized to their corresponding
+ * node types (DOMElement, DOMText, etc.) are serialized to their corresponding
* XML source form.
* <p> Within the character data of a document (outside of markup), any
* characters that cannot be represented directly are replaced with
@@ -286,12 +290,12 @@
* (default) Don't pretty-print the result. </dd>
* </dl></dd>
* </dl>
- * <p>See also the <a href='http://www.w3.org/TR/2001/WD-DOM-Level-3-ASLS-20011025'>Document Object Model (DOM) Level 3 Abstract Schemas and Load
+ * <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409'>Document Object Model (DOM) Level 3 Abstract Schemas and Load
* and Save Specification</a>.
+ *
+ * @since DOM Level 3
*/
-#ifndef DOMWriter_HEADER_GUARD_
-#define DOMWriter_HEADER_GUARD_
#include <xercesc/dom/DOMNode.hpp>
#include <xercesc/dom/DOMWriterFilter.hpp>
@@ -299,23 +303,45 @@
#include <xercesc/framework/XMLFormatter.hpp>
class CDOM_EXPORT DOMWriter {
-public:
+protected :
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
+ DOMWriter() {};
+ DOMWriter(const DOMWriter &other) {};
+ DOMWriter & operator = (const DOMWriter &other) {return *this;};
+ //@}
- /** @name Destructor */
- //@{
- /**
- * Destructor.
- */
- virtual ~DOMWriter(){};
- //@}
- /** @name Query */
- //@{
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
/**
- * <p><b>"Experimental - subject to change"</b></p>
+ * Destructor
*
+ */
+ virtual ~DOMWriter() {};
+ //@}
+
+ // -----------------------------------------------------------------------
+ // Virtual DOMWriter interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 3 */
+ //@{
+ // -----------------------------------------------------------------------
+ // Feature methods
+ // -----------------------------------------------------------------------
+ /**
* Query whether setting a feature to a specific value is supported.
* <br>The feature name has the same form as a DOM hasFeature string.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param featName The feature name, which is a DOM has-feature style string.
* @param state The requested state of the feature (<code>true</code> or
* <code>false</code>).
@@ -323,20 +349,18 @@ public:
* the specified value, or <code>false</code> if the feature is not
* recognized or the requested value is not supported. The value of
* the feature itself is not changed.
+ * @since DOM Level 3
*/
virtual bool canSetFeature(const XMLCh* const featName
, bool state) const = 0;
- //@}
-
- /** @name setter */
- //@{
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
* Set the state of a feature.
* <br>The feature name has the same form as a DOM hasFeature string.
* <br>It is possible for a <code>DOMWriter</code> to recognize a feature
* name but to be unable to set its value.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param featName The feature name.
* @param state The requested state of the feature (<code>true</code> or
* <code>false</code>).
@@ -345,14 +369,35 @@ public:
* recognizes the feature name but cannot set the requested value.
* <br>Raise a NOT_FOUND_ERR When the <code>DOMWriter</code> does not
* recognize the feature name.
+ * @see getFeature
+ * @since DOM Level 3
*/
virtual void setFeature(const XMLCh* const featName
, bool state) = 0;
/**
+ * Look up the value of a feature.
+ * <br>The feature name has the same form as a DOM hasFeature string
+ * @param featName The feature name, which is a string with DOM has-feature
+ * syntax.
+ * @return The current state of the feature (<code>true</code> or
+ * <code>false</code>).
+ * @exception DOMException
+ * Raise a NOT_FOUND_ERR When the <code>DOMWriter</code> does not
+ * recognize the feature name.
+ *
* <p><b>"Experimental - subject to change"</b></p>
*
- * The character encoding in which the output will be written.
+ * @see setFeature
+ * @since DOM Level 3
+ */
+ virtual bool getFeature(const XMLCh* const featName) const = 0;
+
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
+ /**
+ * The character encoding in which the output will be written.
* <br> The encoding to use when writing is determined as follows: If the
* encoding attribute has been set, that value will be used.If the
* encoding attribute is <code>null</code> or empty, but the item to be
@@ -360,13 +405,17 @@ public:
* neither of the above provides an encoding name, a default encoding of
* "UTF-8" will be used.
* <br>The default value is <code>null</code>.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param encoding The character encoding in which the output will be written.
+ * @see getEncoding
+ * @since DOM Level 3
*/
- virtual void setEncoding(const XMLCh* const encoding) = 0;
+ virtual void setEncoding(const XMLCh* const encoding) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * The end-of-line sequence of characters to be used in the XML being
+ * The end-of-line sequence of characters to be used in the XML being
* written out. The only permitted values are these:
* <dl>
* <dt><code>null</code></dt>
@@ -386,62 +435,106 @@ public:
* character (#xA). </dd>
* </dl>
* <br>The default value for this attribute is <code>null</code>.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param newLine The end-of-line sequence of characters to be used.
+ * @see getNewLine
+ * @since DOM Level 3
*/
- virtual void setNewLine(const XMLCh* const newLine) = 0;
+ virtual void setNewLine(const XMLCh* const newLine) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * The error handler that will receive error notifications during
+ * The error handler that will receive error notifications during
* serialization. The node where the error occured is passed to this
* error handler, any modification to nodes from within an error
* callback should be avoided since this will result in undefined,
* implementation dependent behavior.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param errorHandler The error handler to be used.
+ * @see getErrorHandler
+ * @since DOM Level 3
*/
- virtual void setErrorHandler(DOMErrorHandler *errorHandler) = 0;
+ virtual void setErrorHandler(DOMErrorHandler *errorHandler) = 0;
- virtual void setFilter(DOMWriterFilter *filter) = 0;
-
- //@}
-
- /** @name Getter functions */
- //@{
/**
+ * When the application provides a filter, the serializer will call out
+ * to the filter before serializing each Node. Attribute nodes are never
+ * passed to the filter. The filter implementation can choose to remove
+ * the node from the stream or to terminate the serialization early.
+ *
* <p><b>"Experimental - subject to change"</b></p>
*
- * Look up the value of a feature.
- * <br>The feature name has the same form as a DOM hasFeature string
- * @param featName The feature name, which is a string with DOM has-feature
- * syntax.
- * @return The current state of the feature (<code>true</code> or
- * <code>false</code>).
- * @exception DOMException
- * Raise a NOT_FOUND_ERR When the <code>DOMWriter</code> does not
- * recognize the feature name.
+ * @param filter The writer filter to be used.
+ * @see getFilter
+ * @since DOM Level 3
*/
- virtual bool getFeature(const XMLCh* const featName) const = 0;
+ virtual void setFilter(DOMWriterFilter *filter) = 0;
+ // -----------------------------------------------------------------------
+ // Getter methods
+ // -----------------------------------------------------------------------
+ /**
+ * Return the character encoding in which the output will be written.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return The character encoding used.
+ * @see setEncoding
+ * @since DOM Level 3
+ */
virtual const XMLCh* getEncoding() const = 0;
+ /**
+ * Return the end-of-line sequence of characters to be used in the XML being
+ * written out.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return The end-of-line sequence of characters to be used.
+ * @see setNewLine
+ * @since DOM Level 3
+ */
virtual const XMLCh* getNewLine() const = 0;
+ /**
+ * Return the error handler that will receive error notifications during
+ * serialization.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return The error handler to be used.
+ * @see setErrorHandler
+ * @since DOM Level 3
+ */
virtual DOMErrorHandler* getErrorHandler() const = 0;
- virtual DOMWriterFilter* getFilter() const = 0;
-
- //@}
-
- /** @name Write function */
- //@{
/**
+ * Return the WriterFilter used.
+ *
* <p><b>"Experimental - subject to change"</b></p>
*
+ * @return The writer filter used.
+ * @see setFilter
+ * @since DOM Level 3
+ */
+ virtual DOMWriterFilter* getFilter() const = 0;
+
+ // -----------------------------------------------------------------------
+ // Write methods
+ // -----------------------------------------------------------------------
+ /**
* Write out the specified node as described above in the description of
* <code>DOMWriter</code>. Writing a Document or Entity node produces a
* serialized form that is well formed XML. Writing other node types
* produces a fragment of text in a form that is not fully defined by
* this document, but that should be useful to a human for debugging or
* diagnostic purposes.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param destination The destination for the data to be written.
* @param nodeToWrite The <code>Document</code> or <code>Entity</code> node to
* be written. For other node types, something sensible should be
@@ -453,48 +546,32 @@ public:
* This exception will be raised in response to any sort of IO or system
* error that occurs while writing to the destination. It may wrap an
* underlying system exception.
+ * @since DOM Level 3
*/
virtual bool writeNode(XMLFormatTarget* const destination
, const DOMNode &nodeToWrite) = 0;
/**
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * Serialize the specified node as described above in the description of
+ * Serialize the specified node as described above in the description of
* <code>DOMWriter</code>. The result of serializing the node is
* returned as a string. Writing a Document or Entity node produces a
* serialized form that is well formed XML. Writing other node types
* produces a fragment of text in a form that is not fully defined by
* this document, but that should be useful to a human for debugging or
* diagnostic purposes.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
* @param nodeToWrite The node to be written.
* @return Returns the serialized data, or <code>null</code> in case a
* failure occured and the failure wasn't canceled by the error
* handler.
- * @exception DOMException
- * DOMSTRING_SIZE_ERR: The resulting string is too long to fit in a
- * <code>XMLCh*</code>.
+ * @since DOM Level 3
*/
virtual XMLCh* writeToString(const DOMNode &nodeToWrite) = 0;
//@}
-protected:
-
- /** @name default constructors */
- //@{
- /**
- * The default constructor
- */
- DOMWriter(){};
- //@}
-
-private:
-
- /** unimplemented copy ctor and assignment operator */
- DOMWriter(const DOMWriter&);
- DOMWriter & operator = (const DOMWriter&);
-
};
#endif
diff --git a/src/xercesc/dom/DOMWriterFilter.hpp b/src/xercesc/dom/DOMWriterFilter.hpp
index 51cab80588a06d169afb974419bc988beca89916..8634c32194086d4efd61e400c35684cee8c21b05 100644
--- a/src/xercesc/dom/DOMWriterFilter.hpp
+++ b/src/xercesc/dom/DOMWriterFilter.hpp
@@ -1,3 +1,6 @@
+#ifndef DOMWriterFilter_HEADER_GUARD_
+#define DOMWriterFilter_HEADER_GUARD_
+
/*
* The Apache Software License, Version 1.1
*
@@ -57,6 +60,9 @@
/*
* $Id$
* $Log$
+ * Revision 1.6 2002/06/06 20:53:07 tng
+ * Documentation Fix: Update the API Documentation for DOM headers
+ *
* Revision 1.5 2002/06/04 14:24:04 peiyongz
* Make DOMWriterFilter pure abstract class w/o implementing any method
* and data
@@ -77,85 +83,110 @@
/**
*
- * Introduced in DOM Level 3
+ * DOMWriterFilter.hpp: interface for the DOMWriterFilter class.
+ *
+ * DOMWriterFilter provide applications the ability to examine nodes
+ * as they are being serialized.
+ *
+ * DOMWriterFilter lets the application decide what nodes should be
+ * serialized or not.
+ *
+ * The DOMDocument, DOMDocumentType, DOMNotation, and DOMEntity nodes are not passed
+ * to the filter.
+ *
+ * @since DOM Level 3
*/
-//////////////////////////////////////////////////////////////////////
-// DOMWriterFilter.hpp: interface for the DOMWriterFilter class.
-//
-// DOMWriterFilter provide applications the ability to examine nodes
-// as they are being serialized.
-//
-// DOMWriterFilter lets the application decide what nodes should be
-// serialized or not.
-//
-// The Document, DocumentType, Notation, and Entity nodes are not passed
-// to the filter.
-//
-//////////////////////////////////////////////////////////////////////
-
-#ifndef DOMWriterFilter_HEADER_GUARD_
-#define DOMWriterFilter_HEADER_GUARD_
#include <xercesc/dom/DOMNodeFilter.hpp>
class CDOM_EXPORT DOMWriterFilter : public DOMNodeFilter {
-public:
-
- /** @name Destructors */
+protected :
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
//@{
- virtual ~DOMWriterFilter(){};
+ DOMWriterFilter() {};
+ DOMWriterFilter(const DOMWriterFilter &other) {};
+ DOMWriterFilter & operator = (const DOMWriterFilter &other) {return *this;};
//@}
- /** @ Interface from DOMNodeFilter,
- * to be implemented by implementation (derived class)
- */
+
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
//@{
- virtual short acceptNode(const DOMNode* node) const = 0;
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMWriterFilter() {};
//@}
- /** @ Getter and Settter
- *
- * <p><b>"Experimental - subject to change"</b></p>
- */
+ // -----------------------------------------------------------------------
+ // Virtual DOMWriterFilter interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 3 */
//@{
- virtual unsigned long getWhatToShow() const =0;
+ /**
+ * Interface from <code>DOMNodeFilter</code>,
+ * to be implemented by implementation (derived class)
+ */
+ virtual short acceptNode(const DOMNode* node) const = 0;
- virtual void setWhatToShow(unsigned long toShow) =0;
- //@}
+ /**
+ * Tells the DOMWriter what types of nodes to show to the filter.
+ * See <code>DOMNodeFilter</code> for definition of the constants.
+ * The constant SHOW_ATTRIBUTE is meaningless here, attribute nodes will
+ * never be passed to a DOMWriterFilter.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @return The constants of what types of nodes to show.
+ * @see setWhatToShow
+ * @since DOM Level 3
+ */
+ virtual unsigned long getWhatToShow() const =0;
-protected:
- /** @name Constructors */
- //@{
- DOMWriterFilter(){};
+ /**
+ * Set what types of nodes are to be presented.
+ * See <code>DOMNodeFilter</code> for definition of the constants.
+ *
+ * <p><b>"Experimental - subject to change"</b></p>
+ *
+ * @param toShow The constants of what types of nodes to show.
+ * @see getWhatToShow
+ * @since DOM Level 3
+ */
+ virtual void setWhatToShow(unsigned long toShow) =0;
//@}
private:
- // unimplemented copy ctor and assignement operator
- DOMWriterFilter(const DOMWriterFilter&);
- DOMWriterFilter & operator = (const DOMWriterFilter&);
// -----------------------------------------------------------------------
// Private data members
//
- // fWhatToShow
- //
- // The whatToShow mask.
+ // fWhatToShow
+ //
+ // The whatToShow mask.
// Tells the DOMWriter what types of nodes to show to the filter.
- // See NodeFilter for definition of the constants.
- // The constants
- // SHOW_ATTRIBUTE,
- // SHOW_DOCUMENT,
- // SHOW_DOCUMENT_TYPE,
- // SHOW_NOTATION, and
- // SHOW_DOCUMENT_FRAGMENT are meaningless here,
- // Entity nodes are not passed to the filter.
+ // See NodeFilter for definition of the constants.
+ // The constants
+ // SHOW_ATTRIBUTE,
+ // SHOW_DOCUMENT,
+ // SHOW_DOCUMENT_TYPE,
+ // SHOW_NOTATION, and
+ // SHOW_DOCUMENT_FRAGMENT are meaningless here,
+ // Entity nodes are not passed to the filter.
+ //
+ // Those nodes will never be passed to a DOMWriterFilter.
+ //
+ // Derived class shall add this data member:
//
- // Those nodes will never be passed to a DOMWriterFilter.
- //
- // Derived class shall add this data member:
- //
- // unsigned long fWhatToShow;
+ // unsigned long fWhatToShow;
// -----------------------------------------------------------------------
};