/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /* * $Id: DOMElement.hpp 792236 2009-07-08 17:22:35Z amassari $ */ #if !defined(XERCESC_INCLUDE_GUARD_DOMELEMENT_HPP) #define XERCESC_INCLUDE_GUARD_DOMELEMENT_HPP #include #include XERCES_CPP_NAMESPACE_BEGIN class DOMAttr; class DOMNodeList; class DOMTypeInfo; /** * By far the vast majority of objects (apart from text) that authors * encounter when traversing a document are DOMElement nodes. * * Assume the following XML document:<elementExample id="demo"> * <subelement1/> * <subelement2><subsubelement/></subelement2> * </elementExample> *

When represented using DOM, the top node is an DOMElement node * for "elementExample", which contains two child DOMElement nodes, * one for "subelement1" and one for "subelement2". "subelement1" contains no * child nodes. *

Elements may have attributes associated with them; since the * DOMElement interface inherits from DOMNode, the generic * DOMNode interface method getAttributes may be used * to retrieve the set of all attributes for an element. There are methods on * the DOMElement interface to retrieve either an DOMAttr * object by name or an attribute value by name. In XML, where an attribute * value may contain entity references, an DOMAttr object should be * retrieved to examine the possibly fairly complex sub-tree representing the * 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 * * It also defines the ElementTraversal helper interface defined by http://www.w3.org/TR/2008/REC-ElementTraversal-20081222/ * */ class CDOM_EXPORT DOMElement: public DOMNode { protected: // ----------------------------------------------------------------------- // Hidden constructors // ----------------------------------------------------------------------- /** @name Hidden constructors */ //@{ DOMElement() {} DOMElement(const DOMElement &other) : DOMNode(other) {} //@} private: // ----------------------------------------------------------------------- // Unimplemented constructors and operators // ----------------------------------------------------------------------- /** @name Unimplemented operators */ //@{ DOMElement & operator = (const DOMElement &); //@} public: // ----------------------------------------------------------------------- // All constructors are hidden, just the destructor is available // ----------------------------------------------------------------------- /** @name Destructor */ //@{ /** * Destructor * */ virtual ~DOMElement() {}; //@} // ----------------------------------------------------------------------- // Virtual DOMElement interface // ----------------------------------------------------------------------- /** @name Functions introduced in DOM Level 1 */ //@{ // ----------------------------------------------------------------------- // Getter methods // ----------------------------------------------------------------------- /** * The name of the element. * * For example, in: <elementExample * id="demo"> ... </elementExample> , tagName has * the value "elementExample". 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; /** * Retrieves an attribute value by name. * * @param name The name of the attribute to retrieve. * @return The DOMAttr 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; /** * Retrieves an DOMAttr node by name. * * @param name The name (nodeName) of the attribute to retrieve. * @return The DOMAttr node with the specified name (nodeName) or * null if there is no such attribute. * @since DOM Level 1 */ virtual DOMAttr * getAttributeNode(const XMLCh *name) const = 0; /** * Returns a DOMNodeList of all descendant elements with a given * tag name, in the order in which they would be encountered in a preorder * traversal of the DOMElement tree. * * @param name The name of the tag to match on. The special value "*" * matches all tags. * @return A list of matching DOMElement nodes. * @since DOM Level 1 */ virtual DOMNodeList * getElementsByTagName(const XMLCh *name) const = 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 * DOMAttr node plus any DOMText and * DOMEntityReference nodes, build the appropriate subtree, and * use setAttributeNode 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. *
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 (nodeName) is already present * in the element, it is replaced by the new one. * @param newAttr The DOMAttr node to add to the attribute list. * @return If the newAttr attribute replaces an existing * attribute, the replaced * DOMAttr node is returned, otherwise null is * returned. * @exception DOMException * WRONG_DOCUMENT_ERR: Raised if newAttr was created from a * different document than the one that created the element. *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. *
INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an * attribute of another DOMElement object. The DOM user must * explicitly clone DOMAttr nodes to re-use them in other * elements. * @since DOM Level 1 */ virtual DOMAttr * setAttributeNode(DOMAttr *newAttr) = 0; /** * Removes the specified attribute node. * If the removed DOMAttr * 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 DOMAttr node to remove from the attribute * list. * @return The DOMAttr node that was removed. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. *
NOT_FOUND_ERR: Raised if oldAttr is not an attribute * of the element. * @since DOM Level 1 */ virtual DOMAttr * removeAttributeNode(DOMAttr *oldAttr) = 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.
To remove an attribute by local * name and namespace URI, use the removeAttributeNS 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; //@} /** @name Functions introduced in DOM Level 2. */ //@{ /** * Retrieves an attribute value by local name and namespace URI. * * @param namespaceURI The namespace URI of * the attribute to retrieve. * @param localName The local name of the * attribute to retrieve. * @return The DOMAttr value as a string, or an null 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 qualifiedName, and * its value is changed to be 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 DOMAttr * node plus any DOMText and DOMEntityReference * nodes, build the appropriate subtree, and use * setAttributeNodeNS or setAttributeNode to assign * it as the value of an attribute. * * @param namespaceURI The namespace URI of * the attribute to create or alter. * @param qualifiedName The qualified name 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. *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. *
* NAMESPACE_ERR: Raised if the qualifiedName is * malformed, if the qualifiedName has a prefix and the * namespaceURI is null or an empty string, * if the qualifiedName has a prefix that is "xml" and the * namespaceURI is different from * "http://www.w3.org/XML/1998/namespace", if the * qualifiedName has a prefix that is "xmlns" and the * namespaceURI is different from * "http://www.w3.org/2000/xmlns/", or if the * qualifiedName is "xmlns" and the * namespaceURI 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 namespace URI of * the attribute to remove. * @param localName The local name 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 DOMAttr node by local name and namespace URI. * * @param namespaceURI The namespace URI of * the attribute to retrieve. * @param localName The local name of the * attribute to retrieve. * @return The DOMAttr node with the specified attribute local * name and namespace URI or null 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 DOMAttr node to add to the attribute list. * @return If the newAttr attribute replaces an existing * attribute with the same local name and namespace URI, * the replaced DOMAttr node is * returned, otherwise null is returned. * @exception DOMException * WRONG_DOCUMENT_ERR: Raised if newAttr was created from a * different document than the one that created the element. *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. *
INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an * attribute of another DOMElement object. The DOM user must * explicitly clone DOMAttr nodes to re-use them in other * elements. * @since DOM Level 2 */ virtual DOMAttr * setAttributeNodeNS(DOMAttr *newAttr) = 0; /** * Returns a DOMNodeList of all the DOMElements * with a given local name and namespace URI in the order in which they * would be encountered in a preorder traversal of the * DOMDocument tree, starting from this node. * * @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 DOMNodeList object containing all the matched * DOMElements. * @since DOM Level 2 */ virtual DOMNodeList * getElementsByTagNameNS(const XMLCh *namespaceURI, const XMLCh *localName) const = 0; /** * Returns true when an attribute with a given name is * specified on this element or has a default value, false * otherwise. * @param name The name of the attribute to look for. * @return true if an attribute with the given name is * specified on this element or has a default value, false * otherwise. * @since DOM Level 2 */ virtual bool hasAttribute(const XMLCh *name) const = 0; /** * Returns true when an attribute with a given local name and * namespace URI is specified on this element or has a default value, * false otherwise. HTML-only DOM implementations do not * need to implement this method. * @param namespaceURI The namespace URI of the attribute to look for. * @param localName The local name of the attribute to look for. * @return true if an attribute with the given local name * and namespace URI is specified or has a default value on this * element, false otherwise. * @since DOM Level 2 */ virtual bool hasAttributeNS(const XMLCh *namespaceURI, const XMLCh *localName) const = 0; //@} /** @name Functions introduced in DOM Level 3 */ //@{ /** * If the parameter isId is true, this method declares the specified * attribute to be a user-determined ID attribute. * This affects the value of DOMAttr::isId and the behavior of * DOMDocument::getElementById, but does not change any schema that * may be in use, in particular this does not affect the DOMAttr::getSchemaTypeInfo * of the specified DOMAttr node. Use the value false for the parameter isId * to undeclare an attribute for being a user-determined ID attribute. * To specify an DOMAttr by local name and namespace URI, use the * setIdAttributeNS method. * * @param name The name of the DOMAttr. * @param isId Whether the attribute is of type ID. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
* NOT_FOUND_ERR: Raised if the specified node is not an DOMAttr * of this element. * * @since DOM Level 3 */ virtual void setIdAttribute(const XMLCh* name, bool isId) = 0; /** * If the parameter isId is true, this method declares the specified * attribute to be a user-determined ID attribute. * This affects the value of DOMAttr::isId and the behavior of * DOMDocument::getElementById, but does not change any schema that * may be in use, in particular this does not affect the DOMAttr::getSchemaTypeInfo * of the specified DOMAttr node. Use the value false for the parameter isId * to undeclare an attribute for being a user-determined ID attribute. * * @param namespaceURI The namespace URI of the DOMAttr. * @param localName The local name of the DOMAttr. * @param isId Whether the attribute is of type ID. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
* NOT_FOUND_ERR: Raised if the specified node is not an DOMAttr of this element. * * @since DOM Level 3 */ virtual void setIdAttributeNS(const XMLCh* namespaceURI, const XMLCh* localName, bool isId) = 0; /** * If the parameter isId is true, this method declares the specified * attribute to be a user-determined ID attribute. * This affects the value of DOMAttr::isId and the behavior of * DOMDocument::getElementById, but does not change any schema that * may be in use, in particular this does not affect the DOMAttr::getSchemaTypeInfo * of the specified DOMAttr node. Use the value false for the parameter isId * to undeclare an attribute for being a user-determined ID attribute. * * @param idAttr The DOMAttr node. * @param isId Whether the attribute is of type ID. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
* NOT_FOUND_ERR: Raised if the specified node is not an DOMAttr of this element. * * @since DOM Level 3 */ virtual void setIdAttributeNode(const DOMAttr *idAttr, bool isId) = 0; /** * Returns the type information associated with this element. * * @return the DOMTypeInfo associated with this element * @since DOM level 3 */ virtual const DOMTypeInfo* getSchemaTypeInfo() const = 0; //@} // ----------------------------------------------------------------------- // DOMElementTraversal interface // ----------------------------------------------------------------------- /** @name Functions introduced in the ElementTraversal specification (http://www.w3.org/TR/2008/REC-ElementTraversal-20081222/)*/ //@{ // ----------------------------------------------------------------------- // Getter methods // ----------------------------------------------------------------------- /** * The first child of type DOMElement. * * @return The DOMElement object that is the first element node * among the child nodes of this node, or null if there is none. */ virtual DOMElement * getFirstElementChild() const = 0; /** * The last child of type DOMElement. * * @return The DOMElement object that is the last element node * among the child nodes of this node, or null if there is none. */ virtual DOMElement * getLastElementChild() const = 0; /** * The previous sibling node of type DOMElement. * * @return The DOMElement object that is the previous sibling element node * in document order, or null if there is none. */ virtual DOMElement * getPreviousElementSibling() const = 0; /** * The next sibling node of type DOMElement. * * @return The DOMElement object that is the next sibling element node * in document order, or null if there is none. */ virtual DOMElement * getNextElementSibling() const = 0; /** * The number of child nodes that are of type DOMElement. * * Note: the count is computed every time this function is invoked * * @return The number of DOMElement objects that are direct children * of this object (nested elements are not counted), or 0 if there is none. * */ virtual XMLSize_t getChildElementCount() const = 0; //@} }; XERCES_CPP_NAMESPACE_END #endif