/* * 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: DOM_Element.hpp 568078 2007-08-21 11:43:25Z amassari $ */ #ifndef DOM_Element_HEADER_GUARD_ #define DOM_Element_HEADER_GUARD_ #include #include "DOM_Node.hpp" XERCES_CPP_NAMESPACE_BEGIN class DOM_Attr; class DOM_NodeList; class ElementImpl; /** * By far the vast majority of objects (apart from text) that authors * encounter when traversing a document are DOM_Element nodes. * * Assume the following XML document:<elementExample id="demo"> * <subelement1/> * <subelement2><subsubelement/></subelement2> * </elementExample> *

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

Elements may have attributes associated with them; since the * DOM_Element interface inherits from DOM_Node, the generic * DOM_Node interface method getAttributes may be used * to retrieve the set of all attributes for an element. There are methods on * the DOM_Element interface to retrieve either an DOM_Attr * object by name or an attribute value by name. In XML, where an attribute * value may contain entity references, an DOM_Attr 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. */ class DEPRECATED_DOM_EXPORT DOM_Element: public DOM_Node { private: public: /** @name Constructors and assignment operator */ //@{ /** * Default constructor for DOM_Element. The resulting object does not * refer to an actual Element node; it will compare == to 0, and is similar * to a null object reference variable in Java. It may subsequently be * assigned to refer to an actual Element node. *

* New comment nodes are created by DOM_Document::createElement(). * */ DOM_Element(); /** * Copy constructor. Creates a new DOM_Element that refers to the * same underlying actual element as the original. * * @param other The object to be copied */ DOM_Element(const DOM_Element &other); /** * Assignment operator. * * @param other The object to be copied. */ DOM_Element & operator = (const DOM_Element &other); /** * Assignment operator. This overloaded variant is provided for * the sole purpose of setting a DOM_Node reference variable to * zero. Nulling out a reference variable in this way will decrement * the reference count on the underlying Node object that the variable * formerly referenced. This effect is normally obtained when reference * variable goes out of scope, but zeroing them can be useful for * global instances, or for local instances that will remain in scope * for an extended time, when the storage belonging to the underlying * node needs to be reclaimed. * * @param val Only a value of 0, or null, is allowed. */ DOM_Element & operator = (const DOM_NullPtr *val); //@} /** @name Destructor. */ //@{ /** * Destructor. The object being destroyed is the reference * object, not the underlying Element itself. * */ ~DOM_Element(); //@} /** @name Getter functions. */ //@{ /** * 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. */ DOMString getTagName() const; /** * Retrieves an attribute value by name. * * @param name The name of the attribute to retrieve. * @return The DOM_Attr value as a string, or the empty string if * that attribute does not have a specified or default value. */ DOMString getAttribute(const DOMString &name) const; /** * Retrieves an DOM_Attr node by name. * * @param name The name (nodeName) of the attribute to retrieve. * @return The DOM_Attr node with the specified name (nodeName) or * null if there is no such attribute. */ DOM_Attr getAttributeNode(const DOMString &name) const; /** * Returns a NodeList of all descendant elements with a given * tag name, in the order in which they would be encountered in a preorder * traversal of the DOM_Element tree. * * @param name The name of the tag to match on. The special value "*" * matches all tags. * @return A list of matching DOM_Element nodes. */ DOM_NodeList getElementsByTagName(const DOMString &name) const; //@} /** @name Set functions. */ //@{ /** * 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 * DOM_Attr node plus any Text and * EntityReference 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. */ void setAttribute(const DOMString &name, const DOMString &value); /** * 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 DOM_Attr node to add to the attribute list. * @return If the newAttr attribute replaces an existing * attribute, the replaced * DOM_Attr 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 DOM_Element object. The DOM user must * explicitly clone DOM_Attr nodes to re-use them in other * elements. */ DOM_Attr setAttributeNode(DOM_Attr newAttr); //@} /** @name Functions which modify the Element. */ //@{ /** * Removes the specified attribute node. * If the removed DOM_Attr * 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 DOM_Attr node to remove from the attribute * list. * @return The DOM_Attr 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. */ DOM_Attr removeAttributeNode(DOM_Attr oldAttr); /** * 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. */ void removeAttribute(const DOMString &name); //@} /** @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 DOM_Attr value as a string, or an null if * that attribute does not have a specified or default value. */ DOMString getAttributeNS(const DOMString &namespaceURI, const DOMString &localName) const; /** * 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 DOM_Attr * node plus any DOM_Text and DOM_EntityReference * 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/". */ void setAttributeNS(const DOMString &namespaceURI, const DOMString &qualifiedName, const DOMString &value); /** * 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. */ void removeAttributeNS(const DOMString &namespaceURI, const DOMString &localName); /** * Retrieves an DOM_Attr 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 DOM_Attr node with the specified attribute local * name and namespace URI or null if there is no such attribute. */ DOM_Attr getAttributeNodeNS(const DOMString &namespaceURI, const DOMString &localName) const; /** * 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 DOM_Attr 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 DOM_Attr 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 DOM_Element object. The DOM user must * explicitly clone DOM_Attr nodes to re-use them in other * elements. */ DOM_Attr setAttributeNodeNS(DOM_Attr newAttr); /** * Returns a DOM_NodeList of all the DOM_Elements * with a given local name and namespace URI in the order in which they * would be encountered in a preorder traversal of the * DOM_Document 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 DOM_NodeList object containing all the matched * DOM_Elements. */ DOM_NodeList getElementsByTagNameNS(const DOMString &namespaceURI, const DOMString &localName) const; /** * Returns whether this node (if it is an element) has any attributes. * @return true if this node has any attributes, * false otherwise. */ bool hasAttributes() const; /** * 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. */ bool hasAttribute(const DOMString &name) const; /** * 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 */ bool hasAttributeNS(const DOMString &namespaceURI, const DOMString &localName) const; //@} protected: DOM_Element(ElementImpl *impl); friend class DOM_Document; friend class DOM_Attr; }; XERCES_CPP_NAMESPACE_END #endif