xercesc/dom/DOMElement.hpp

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *      http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 /*
0019  * $Id$
0020  */
0021
0022 #if !defined(XERCESC_INCLUDE_GUARD_DOMELEMENT_HPP)
0023 #define XERCESC_INCLUDE_GUARD_DOMELEMENT_HPP
0024
0025 #include <xercesc/util/XercesDefs.hpp>
0026 #include <xercesc/dom/DOMNode.hpp>
0027
0028 XERCES_CPP_NAMESPACE_BEGIN
0029
0030
0031 class DOMAttr;
0032 class DOMNodeList;
0033 class DOMTypeInfo;
0034
0035
0036 /**
0037  * By far the vast majority of objects (apart from text) that authors
0038  * encounter when traversing a document are <code>DOMElement</code> nodes.
0039  *
0040  * Assume the following XML document:&lt;elementExample id="demo"&gt;
0041  * &lt;subelement1/&gt;
0042  * &lt;subelement2&gt;&lt;subsubelement/&gt;&lt;/subelement2&gt;
0043  * &lt;/elementExample&gt;
0044  * <p>When represented using DOM, the top node is an <code>DOMElement</code> node
0045  * for "elementExample", which contains two child <code>DOMElement</code> nodes,
0046  * one for "subelement1" and one for "subelement2". "subelement1" contains no
0047  * child nodes.
0048  * <p>Elements may have attributes associated with them; since the
0049  * <code>DOMElement</code> interface inherits from <code>DOMNode</code>, the generic
0050  *  <code>DOMNode</code> interface method <code>getAttributes</code> may be used
0051  * to retrieve the set of all attributes for an element.  There are methods on
0052  *  the <code>DOMElement</code> interface to retrieve either an <code>DOMAttr</code>
0053  *  object by name or an attribute value by name. In XML, where an attribute
0054  * value may contain entity references, an <code>DOMAttr</code> object should be
0055  * retrieved to examine the possibly fairly complex sub-tree representing the
0056  * attribute value. On the other hand, in HTML, where all attributes have
0057  * simple string values, methods to directly access an attribute value can
0058  * safely be used as a convenience.
0059  *
0060  * @since DOM Level 1
0061  *
0062  * It also defines the ElementTraversal helper interface defined by http://www.w3.org/TR/2008/REC-ElementTraversal-20081222/
0063  *
0064  */
0065
0066 class CDOM_EXPORT DOMElement: public DOMNode {
0067 protected:
0068     // -----------------------------------------------------------------------
0069     //  Hidden constructors
0070     // -----------------------------------------------------------------------
0071     /** @name Hidden constructors */
0072     //@{
0073     DOMElement() {}
0074     DOMElement(const DOMElement &other) : DOMNode(other) {}
0075     //@}
0076
0077 private:
0078     // -----------------------------------------------------------------------
0079     // Unimplemented constructors and operators
0080     // -----------------------------------------------------------------------
0081     /** @name Unimplemented operators */
0082     //@{
0083     DOMElement & operator = (const DOMElement &);
0084     //@}
0085
0086 public:
0087     // -----------------------------------------------------------------------
0088     //  All constructors are hidden, just the destructor is available
0089     // -----------------------------------------------------------------------
0090     /** @name Destructor */
0091     //@{
0092     /**
0093      * Destructor
0094      *
0095      */
0096     virtual ~DOMElement() {};
0097     //@}
0098
0099     // -----------------------------------------------------------------------
0100     //  Virtual DOMElement interface
0101     // -----------------------------------------------------------------------
0102     /** @name Functions introduced in DOM Level 1 */
0103     //@{
0104     // -----------------------------------------------------------------------
0105     //  Getter methods
0106     // -----------------------------------------------------------------------
0107     /**
0108      * The name of the element.
0109      *
0110      * For example, in: &lt;elementExample
0111      * id="demo"&gt;  ... &lt;/elementExample&gt; , <code>tagName</code> has
0112      * the value <code>"elementExample"</code>. Note that this is
0113      * case-preserving in XML, as are all of the operations of the DOM.
0114      * @since DOM Level 1
0115      */
0116     virtual const XMLCh *         getTagName() const = 0;
0117
0118     /**
0119      * Retrieves an attribute value by name.
0120      *
0121      * @param name The name of the attribute to retrieve.
0122      * @return The <code>DOMAttr</code> value as a string, or the empty  string if
0123      *   that attribute does not have a specified or default value.
0124      * @since DOM Level 1
0125      */
0126     virtual const XMLCh *         getAttribute(const XMLCh *name) const = 0;
0127
0128     /**
0129      * Retrieves an <code>DOMAttr</code> node by name.
0130      *
0131      * @param name The name (<CODE>nodeName</CODE>) of the attribute to retrieve.
0132      * @return The <code>DOMAttr</code> node with the specified name (<CODE>nodeName</CODE>) or
0133      *   <code>null</code> if there is no such attribute.
0134      * @since DOM Level 1
0135      */
0136     virtual DOMAttr       * getAttributeNode(const XMLCh *name) const = 0;
0137
0138     /**
0139      * Returns a <code>DOMNodeList</code> of all descendant elements with a given
0140      * tag name, in the order in which they would be encountered in a preorder
0141      * traversal of the <code>DOMElement</code> tree.
0142      *
0143      * @param name The name of the tag to match on. The special value "*"
0144      *   matches all tags.
0145      * @return A list of matching <code>DOMElement</code> nodes.
0146      * @since DOM Level 1
0147      */
0148     virtual DOMNodeList   * getElementsByTagName(const XMLCh *name) const = 0;
0149
0150     // -----------------------------------------------------------------------
0151     //  Setter methods
0152     // -----------------------------------------------------------------------
0153     /**
0154      * Adds a new attribute.
0155      *
0156      * If an attribute with that name is already present
0157      * in the element, its value is changed to be that of the value parameter.
0158      * This value is a simple string, it is not parsed as it is being set. So
0159      * any markup (such as syntax to be recognized as an entity reference) is
0160      * treated as literal text, and needs to be appropriately escaped by the
0161      * implementation when it is written out. In order to assign an attribute
0162      * value that contains entity references, the user must create an
0163      * <code>DOMAttr</code> node plus any <code>DOMText</code> and
0164      * <code>DOMEntityReference</code> nodes, build the appropriate subtree, and
0165      * use <code>setAttributeNode</code> to assign it as the value of an
0166      * attribute.
0167      * @param name The name of the attribute to create or alter.
0168      * @param value Value to set in string form.
0169      * @exception DOMException
0170      *   INVALID_CHARACTER_ERR: Raised if the specified name contains an
0171      *   illegal character.
0172      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0173      * @since DOM Level 1
0174      */
0175     virtual void             setAttribute(const XMLCh *name,
0176                                   const XMLCh *value) = 0;
0177     /**
0178      * Adds a new attribute.
0179      *
0180      * If an attribute with that name (<CODE>nodeName</CODE>) is already present
0181      * in the element, it is replaced by the new one.
0182      * @param newAttr The <code>DOMAttr</code> node to add to the attribute list.
0183      * @return If the <code>newAttr</code> attribute replaces an existing
0184      *   attribute, the replaced
0185      *   <code>DOMAttr</code> node is returned, otherwise <code>null</code> is
0186      *   returned.
0187      * @exception DOMException
0188      *   WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a
0189      *   different document than the one that created the element.
0190      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0191      *   <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
0192      *   attribute of another <code>DOMElement</code> object. The DOM user must
0193      *   explicitly clone <code>DOMAttr</code> nodes to re-use them in other
0194      *   elements.
0195      * @since DOM Level 1
0196      */
0197     virtual DOMAttr       * setAttributeNode(DOMAttr *newAttr) = 0;
0198
0199     /**
0200      * Removes the specified attribute node.
0201      * If the removed <CODE>DOMAttr</CODE>
0202      *   has a default value it is immediately replaced. The replacing attribute
0203      *   has the same namespace URI and local name, as well as the original prefix,
0204      *   when applicable.
0205      *
0206      * @param oldAttr The <code>DOMAttr</code> node to remove from the attribute
0207      *   list.
0208      * @return The <code>DOMAttr</code> node that was removed.
0209      * @exception DOMException
0210      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0211      *   <br>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute
0212      *   of the element.
0213      * @since DOM Level 1
0214      */
0215     virtual DOMAttr       * removeAttributeNode(DOMAttr *oldAttr) = 0;
0216
0217     /**
0218      * Removes an attribute by name.
0219      *
0220      * If the removed attribute
0221      *   is known to have a default value, an attribute immediately appears
0222      *   containing the default value as well as the corresponding namespace URI,
0223      *   local name, and prefix when applicable.<BR>To remove an attribute by local
0224      *   name and namespace URI, use the <CODE>removeAttributeNS</CODE> method.
0225      * @param name The name of the attribute to remove.
0226      * @exception DOMException
0227      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0228      * @since DOM Level 1
0229      */
0230     virtual void              removeAttribute(const XMLCh *name) = 0;
0231     //@}
0232
0233     /** @name Functions introduced in DOM Level 2. */
0234     //@{
0235     /**
0236      * Retrieves an attribute value by local name and namespace URI.
0237      *
0238      * @param namespaceURI The <em>namespace URI</em> of
0239      *    the attribute to retrieve.
0240      * @param localName The <em>local name</em> of the
0241      *    attribute to retrieve.
0242      * @return The <code>DOMAttr</code> value as a string, or an <CODE>null</CODE> if
0243      *    that attribute does not have a specified or default value.
0244      * @since DOM Level 2
0245      */
0246     virtual const XMLCh *         getAttributeNS(const XMLCh *namespaceURI,
0247                                                  const XMLCh *localName) const = 0;
0248
0249     /**
0250      * Adds a new attribute. If an attribute with the same
0251      * local name and namespace URI is already present on the element, its prefix
0252      * is changed to be the prefix part of the <CODE>qualifiedName</CODE>, and
0253      * its value is changed to be the <CODE>value</CODE> parameter. This value is
0254      * a simple string, it is not parsed as it is being set. So any markup (such
0255      * as syntax to be recognized as an entity reference) is treated as literal
0256      * text, and needs to be appropriately escaped by the implementation when it
0257      * is written out. In order to assign an attribute value that contains entity
0258      * references, the user must create an <CODE>DOMAttr</CODE>
0259      * node plus any <CODE>DOMText</CODE> and <CODE>DOMEntityReference</CODE>
0260      * nodes, build the appropriate subtree, and use
0261      * <CODE>setAttributeNodeNS</CODE> or <CODE>setAttributeNode</CODE> to assign
0262      * it as the value of an attribute.
0263      *
0264      * @param namespaceURI The <em>namespace URI</em> of
0265      *    the attribute to create or alter.
0266      * @param qualifiedName The <em>qualified name</em> of the
0267      *    attribute to create or alter.
0268      * @param value The value to set in string form.
0269      * @exception DOMException
0270      *   INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an
0271      *   illegal character.
0272      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0273      * <br>
0274      *   NAMESPACE_ERR: Raised if the <CODE>qualifiedName</CODE> is
0275      *        malformed, if the <CODE>qualifiedName</CODE> has a prefix and the
0276      *        <CODE>namespaceURI</CODE> is <CODE>null</CODE> or an empty string,
0277      *        if the <CODE>qualifiedName</CODE> has a prefix that is "xml" and the
0278      *        <CODE>namespaceURI</CODE> is different from
0279      *        "http://www.w3.org/XML/1998/namespace", if the
0280      *        <CODE>qualifiedName</CODE> has a prefix that is "xmlns" and the
0281      *        <CODE>namespaceURI</CODE> is different from
0282      *        "http://www.w3.org/2000/xmlns/", or if the
0283      *        <CODE>qualifiedName</CODE> is "xmlns" and the
0284      *        <CODE>namespaceURI</CODE> is different from
0285      *        "http://www.w3.org/2000/xmlns/".
0286      * @since DOM Level 2
0287      */
0288     virtual void             setAttributeNS(const XMLCh *namespaceURI,
0289                                             const XMLCh *qualifiedName, const XMLCh *value) = 0;
0290
0291     /**
0292      * Removes an attribute by local name and namespace URI. If the
0293      * removed attribute has a default value it is immediately replaced.
0294      * The replacing attribute has the same namespace URI and local name, as well as
0295      * the original prefix.
0296      *
0297      * @param namespaceURI The <em>namespace URI</em> of
0298      *    the attribute to remove.
0299      * @param localName The <em>local name</em> of the
0300      *    attribute to remove.
0301      * @exception DOMException
0302      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0303      * @since DOM Level 2
0304      */
0305     virtual void              removeAttributeNS(const XMLCh *namespaceURI,
0306                                                 const XMLCh *localName) = 0;
0307
0308     /**
0309      * Retrieves an <code>DOMAttr</code> node by local name and namespace URI.
0310      *
0311      * @param namespaceURI The <em>namespace URI</em> of
0312      *    the attribute to retrieve.
0313      * @param localName The <em>local name</em> of the
0314      *    attribute to retrieve.
0315      * @return The <code>DOMAttr</code> node with the specified attribute local
0316      *    name and namespace URI or <code>null</code> if there is no such attribute.
0317      * @since DOM Level 2
0318      */
0319     virtual DOMAttr      *  getAttributeNodeNS(const XMLCh *namespaceURI,
0320                                                const XMLCh *localName) const = 0;
0321
0322     /**
0323      * Adds a new attribute.
0324      *
0325      * If an attribute with that local name and namespace URI is already present
0326      * in the element, it is replaced by the new one.
0327      *
0328      * @param newAttr The <code>DOMAttr</code> node to add to the attribute list.
0329      * @return If the <code>newAttr</code> attribute replaces an existing
0330      *    attribute with the same <em>local name</em> and <em>namespace URI</em>,
0331      *    the replaced <code>DOMAttr</code> node is
0332      *    returned, otherwise <code>null</code> is returned.
0333      * @exception DOMException
0334      *   WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a
0335      *   different document than the one that created the element.
0336      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0337      *   <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
0338      *   attribute of another <code>DOMElement</code> object. The DOM user must
0339      *   explicitly clone <code>DOMAttr</code> nodes to re-use them in other
0340      *   elements.
0341      * @since DOM Level 2
0342      */
0343     virtual DOMAttr      *  setAttributeNodeNS(DOMAttr *newAttr) = 0;
0344
0345     /**
0346      * Returns a <code>DOMNodeList</code> of all the <code>DOMElement</code>s
0347      * with a given local name and namespace URI in the order in which they
0348      * would be encountered in a preorder traversal of the
0349      * <code>DOMDocument</code> tree, starting from this node.
0350      *
0351      * @param namespaceURI The <em>namespace URI</em> of
0352      *    the elements to match on. The special value "*" matches all
0353      *    namespaces.
0354      * @param localName The <em>local name</em> of the
0355      *    elements to match on. The special value "*" matches all local names.
0356      * @return A new <code>DOMNodeList</code> object containing all the matched
0357      *    <code>DOMElement</code>s.
0358      * @since DOM Level 2
0359      */
0360     virtual DOMNodeList   * getElementsByTagNameNS(const XMLCh *namespaceURI,
0361                                                    const XMLCh *localName) const = 0;
0362
0363     /**
0364      * Returns <code>true</code> when an attribute with a given name is
0365      * specified on this element or has a default value, <code>false</code>
0366      * otherwise.
0367      * @param name The name of the attribute to look for.
0368      * @return <code>true</code> if an attribute with the given name is
0369      *   specified on this element or has a default value, <code>false</code>
0370      *    otherwise.
0371      * @since DOM Level 2
0372      */
0373     virtual bool         hasAttribute(const XMLCh *name) const = 0;
0374
0375     /**
0376      * Returns <code>true</code> when an attribute with a given local name and
0377      * namespace URI is specified on this element or has a default value,
0378      * <code>false</code> otherwise. HTML-only DOM implementations do not
0379      * need to implement this method.
0380      * @param namespaceURI The namespace URI of the attribute to look for.
0381      * @param localName The local name of the attribute to look for.
0382      * @return <code>true</code> if an attribute with the given local name
0383      *   and namespace URI is specified or has a default value on this
0384      *   element, <code>false</code> otherwise.
0385      * @since DOM Level 2
0386      */
0387     virtual bool         hasAttributeNS(const XMLCh *namespaceURI,
0388                                         const XMLCh *localName) const = 0;
0389     //@}
0390
0391     /** @name Functions introduced in DOM Level 3 */
0392     //@{
0393
0394     /**
0395      * If the parameter isId is <code>true</code>, this method declares the specified
0396      * attribute to be a user-determined ID attribute.
0397      * This affects the value of <code>DOMAttr::isId</code> and the behavior of
0398      * <code>DOMDocument::getElementById</code>, but does not change any schema that
0399      * may be in use, in particular this does not affect the <code>DOMAttr::getSchemaTypeInfo</code>
0400      * of the specified DOMAttr node. Use the value <code>false</code> for the parameter isId
0401      * to undeclare an attribute for being a user-determined ID attribute.
0402      * To specify an <code>DOMAttr</code> by local name and namespace URI, use the
0403      * setIdAttributeNS method.
0404      *
0405      * @param name The name of the <code>DOMAttr</code>.
0406      * @param isId Whether the attribute is of type ID.
0407      * @exception DOMException
0408      *    NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.<br>
0409      *    NOT_FOUND_ERR: Raised if the specified node is not an <code>DOMAttr</code>
0410      * of this element.
0411      *
0412      * @since DOM Level 3
0413      */
0414     virtual void setIdAttribute(const XMLCh* name, bool isId) = 0;
0415
0416
0417     /**
0418      * If the parameter isId is <code>true</code>, this method declares the specified
0419      * attribute to be a user-determined ID attribute.
0420      * This affects the value of <code>DOMAttr::isId</code> and the behavior of
0421      * <code>DOMDocument::getElementById</code>, but does not change any schema that
0422      * may be in use, in particular this does not affect the <code>DOMAttr::getSchemaTypeInfo</code>
0423      * of the specified DOMAttr node. Use the value <code>false</code> for the parameter isId
0424      * to undeclare an attribute for being a user-determined ID attribute.
0425      *
0426      * @param namespaceURI The namespace URI of the <code>DOMAttr</code>.
0427      * @param localName The local name of the <code>DOMAttr</code>.
0428      * @param isId Whether the attribute is of type ID.
0429      * @exception  DOMException
0430      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.<br>
0431      *   NOT_FOUND_ERR: Raised if the specified node is not an <code>DOMAttr</code> of this element.
0432      *
0433      * @since DOM Level 3
0434      */
0435     virtual void setIdAttributeNS(const XMLCh* namespaceURI, const XMLCh* localName, bool isId) = 0;
0436
0437
0438
0439     /**
0440      * If the parameter isId is <code>true</code>, this method declares the specified
0441      * attribute to be a user-determined ID attribute.
0442      * This affects the value of <code>DOMAttr::isId</code> and the behavior of
0443      * <code>DOMDocument::getElementById</code>, but does not change any schema that
0444      * may be in use, in particular this does not affect the <code>DOMAttr::getSchemaTypeInfo</code>
0445      * of the specified DOMAttr node. Use the value <code>false</code> for the parameter isId
0446      * to undeclare an attribute for being a user-determined ID attribute.
0447      *
0448      * @param idAttr The <code>DOMAttr</code> node.
0449      * @param isId Whether the attribute is of type ID.
0450      * @exception  DOMException
0451      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.<br>
0452      *   NOT_FOUND_ERR: Raised if the specified node is not an <code>DOMAttr</code> of this element.
0453      *
0454      * @since DOM Level 3
0455      */
0456     virtual void setIdAttributeNode(const DOMAttr *idAttr, bool isId) = 0;
0457
0458
0459
0460     /**
0461      * Returns the type information associated with this element.
0462      *
0463      * @return the <code>DOMTypeInfo</code> associated with this element
0464      * @since DOM level 3
0465      */
0466     virtual const DOMTypeInfo* getSchemaTypeInfo() const = 0;
0467
0468     //@}
0469
0470     // -----------------------------------------------------------------------
0471     //  DOMElementTraversal interface
0472     // -----------------------------------------------------------------------
0473     /** @name Functions introduced in the ElementTraversal specification (http://www.w3.org/TR/2008/REC-ElementTraversal-20081222/)*/
0474     //@{
0475     // -----------------------------------------------------------------------
0476     //  Getter methods
0477     // -----------------------------------------------------------------------
0478     /**
0479      * The first child of type DOMElement.
0480      *
0481      * @return The <code>DOMElement</code> object that is the first element node
0482      *   among the child nodes of this node, or <code>null</code> if there is none.
0483      */
0484     virtual DOMElement *         getFirstElementChild() const = 0;
0485
0486     /**
0487      * The last child of type DOMElement.
0488      *
0489      * @return The <code>DOMElement</code> object that is the last element node
0490      *   among the child nodes of this node, or <code>null</code> if there is none.
0491      */
0492     virtual DOMElement *         getLastElementChild() const = 0;
0493
0494     /**
0495      * The previous sibling node of type DOMElement.
0496      *
0497      * @return The <code>DOMElement</code> object that is the previous sibling element node
0498      *   in document order, or <code>null</code> if there is none.
0499      */
0500     virtual DOMElement *         getPreviousElementSibling() const = 0;
0501
0502     /**
0503      * The next sibling node of type DOMElement.
0504      *
0505      * @return The <code>DOMElement</code> object that is the next sibling element node
0506      *   in document order, or <code>null</code> if there is none.
0507      */
0508     virtual DOMElement *         getNextElementSibling() const = 0;
0509
0510     /**
0511      * The number of child nodes that are of type DOMElement.
0512      *
0513      * Note: the count is computed every time this function is invoked
0514      *
0515      * @return The number of <code>DOMElement</code> objects that are direct children
0516      *   of this object (nested elements are not counted), or <code>0</code> if there is none.
0517      *
0518      */
0519     virtual XMLSize_t            getChildElementCount() const = 0;
0520     //@}
0521 };
0522
0523 XERCES_CPP_NAMESPACE_END
0524
0525 #endif
0526
0527
0528