1 /* 2 * Copyright (c) 2004 World Wide Web Consortium, 3 * 4 * (Massachusetts Institute of Technology, European Research Consortium for 5 * Informatics and Mathematics, Keio University). All Rights Reserved. This 6 * work is distributed under the W3C(r) Software License [1] in the hope that 7 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 8 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 9 * 10 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 11 */ 12 13 package org.w3c.dom; 14 15 /** 16 * The <code>Element</code> interface represents an element in an HTML or XML 17 * document. Elements may have attributes associated with them; since the 18 * <code>Element</code> interface inherits from <code>Node</code>, the 19 * generic <code>Node</code> interface attribute <code>attributes</code> may 20 * be used to retrieve the set of all attributes for an element. There are 21 * methods on the <code>Element</code> interface to retrieve either an 22 * <code>Attr</code> object by name or an attribute value by name. In XML, 23 * where an attribute value may contain entity references, an 24 * <code>Attr</code> object should be retrieved to examine the possibly 25 * fairly complex sub-tree representing the attribute value. On the other 26 * hand, in HTML, where all attributes have simple string values, methods to 27 * directly access an attribute value can safely be used as a convenience. 28 * <p ><b>Note:</b> In DOM Level 2, the method <code>normalize</code> is 29 * inherited from the <code>Node</code> interface where it was moved. 30 * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>Document Object Model (DOM) Level 3 Core Specification</a>. 31 */ 32 public interface Element extends Node { 33 /** 34 * The name of the element. If <code>Node.localName</code> is different 35 * from <code>null</code>, this attribute is a qualified name. For 36 * example, in: 37 * <pre> <elementExample id="demo"> ... 38 * </elementExample> , </pre> 39 * <code>tagName</code> has the value 40 * <code>"elementExample"</code>. Note that this is case-preserving in 41 * XML, as are all of the operations of the DOM. The HTML DOM returns 42 * the <code>tagName</code> of an HTML element in the canonical 43 * uppercase form, regardless of the case in the source HTML document. 44 */ 45 public String getTagName(); 46 47 /** 48 * Retrieves an attribute value by name. 49 * @param name The name of the attribute to retrieve. 50 * @return The <code>Attr</code> value as a string, or the empty string 51 * if that attribute does not have a specified or default value. 52 */ 53 public String getAttribute(String name); 54 55 /** 56 * Adds a new attribute. If an attribute with that name is already present 57 * in the element, its value is changed to be that of the value 58 * parameter. This value is a simple string; it is not parsed as it is 59 * being set. So any markup (such as syntax to be recognized as an 60 * entity reference) is treated as literal text, and needs to be 61 * appropriately escaped by the implementation when it is written out. 62 * In order to assign an attribute value that contains entity 63 * references, the user must create an <code>Attr</code> node plus any 64 * <code>Text</code> and <code>EntityReference</code> nodes, build the 65 * appropriate subtree, and use <code>setAttributeNode</code> to assign 66 * it as the value of an attribute. 67 * <br>To set an attribute with a qualified name and namespace URI, use 68 * the <code>setAttributeNS</code> method. 69 * @param name The name of the attribute to create or alter. 70 * @param value Value to set in string form. 71 * @exception DOMException 72 * INVALID_CHARACTER_ERR: Raised if the specified name is not an XML 73 * name according to the XML version in use specified in the 74 * <code>Document.xmlVersion</code> attribute. 75 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 76 */ 77 public void setAttribute(String name, 78 String value) 79 throws DOMException; 80 81 /** 82 * Removes an attribute by name. If a default value for the removed 83 * attribute is defined in the DTD, a new attribute immediately appears 84 * with the default value as well as the corresponding namespace URI, 85 * local name, and prefix when applicable. The implementation may handle 86 * default values from other schemas similarly but applications should 87 * use <code>Document.normalizeDocument()</code> to guarantee this 88 * information is up-to-date. 89 * <br>If no attribute with this name is found, this method has no effect. 90 * <br>To remove an attribute by local name and namespace URI, use the 91 * <code>removeAttributeNS</code> method. 92 * @param name The name of the attribute to remove. 93 * @exception DOMException 94 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 95 */ 96 public void removeAttribute(String name) 97 throws DOMException; 98 99 /** 100 * Retrieves an attribute node by name. 101 * <br>To retrieve an attribute node by qualified name and namespace URI, 102 * use the <code>getAttributeNodeNS</code> method. 103 * @param name The name (<code>nodeName</code>) of the attribute to 104 * retrieve. 105 * @return The <code>Attr</code> node with the specified name ( 106 * <code>nodeName</code>) or <code>null</code> if there is no such 107 * attribute. 108 */ 109 public Attr getAttributeNode(String name); 110 111 /** 112 * Adds a new attribute node. If an attribute with that name ( 113 * <code>nodeName</code>) is already present in the element, it is 114 * replaced by the new one. Replacing an attribute node by itself has no 115 * effect. 116 * <br>To add a new attribute node with a qualified name and namespace 117 * URI, use the <code>setAttributeNodeNS</code> method. 118 * @param newAttr The <code>Attr</code> node to add to the attribute list. 119 * @return If the <code>newAttr</code> attribute replaces an existing 120 * attribute, the replaced <code>Attr</code> node is returned, 121 * otherwise <code>null</code> is returned. 122 * @exception DOMException 123 * WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a 124 * different document than the one that created the element. 125 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 126 * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an 127 * attribute of another <code>Element</code> object. The DOM user must 128 * explicitly clone <code>Attr</code> nodes to re-use them in other 129 * elements. 130 */ 131 public Attr setAttributeNode(Attr newAttr) 132 throws DOMException; 133 134 /** 135 * Removes the specified attribute node. If a default value for the 136 * removed <code>Attr</code> node is defined in the DTD, a new node 137 * immediately appears with the default value as well as the 138 * corresponding namespace URI, local name, and prefix when applicable. 139 * The implementation may handle default values from other schemas 140 * similarly but applications should use 141 * <code>Document.normalizeDocument()</code> to guarantee this 142 * information is up-to-date. 143 * @param oldAttr The <code>Attr</code> node to remove from the attribute 144 * list. 145 * @return The <code>Attr</code> node that was removed. 146 * @exception DOMException 147 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 148 * <br>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute 149 * of the element. 150 */ 151 public Attr removeAttributeNode(Attr oldAttr) 152 throws DOMException; 153 154 /** 155 * Returns a <code>NodeList</code> of all descendant <code>Elements</code> 156 * with a given tag name, in document order. 157 * @param name The name of the tag to match on. The special value "*" 158 * matches all tags. 159 * @return A list of matching <code>Element</code> nodes. 160 */ 161 public NodeList getElementsByTagName(String name); 162 163 /** 164 * Retrieves an attribute value by local name and namespace URI. 165 * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 166 * , applications must use the value <code>null</code> as the 167 * <code>namespaceURI</code> parameter for methods if they wish to have 168 * no namespace. 169 * @param namespaceURI The namespace URI of the attribute to retrieve. 170 * @param localName The local name of the attribute to retrieve. 171 * @return The <code>Attr</code> value as a string, or the empty string 172 * if that attribute does not have a specified or default value. 173 * @exception DOMException 174 * NOT_SUPPORTED_ERR: May be raised if the implementation does not 175 * support the feature <code>"XML"</code> and the language exposed 176 * through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 177 * @since DOM Level 2 178 */ 179 public String getAttributeNS(String namespaceURI, 180 String localName) 181 throws DOMException; 182 183 /** 184 * Adds a new attribute. If an attribute with the same local name and 185 * namespace URI is already present on the element, its prefix is 186 * changed to be the prefix part of the <code>qualifiedName</code>, and 187 * its value is changed to be the <code>value</code> parameter. This 188 * value is a simple string; it is not parsed as it is being set. So any 189 * markup (such as syntax to be recognized as an entity reference) is 190 * treated as literal text, and needs to be appropriately escaped by the 191 * implementation when it is written out. In order to assign an 192 * attribute value that contains entity references, the user must create 193 * an <code>Attr</code> node plus any <code>Text</code> and 194 * <code>EntityReference</code> nodes, build the appropriate subtree, 195 * and use <code>setAttributeNodeNS</code> or 196 * <code>setAttributeNode</code> to assign it as the value of an 197 * attribute. 198 * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 199 * , applications must use the value <code>null</code> as the 200 * <code>namespaceURI</code> parameter for methods if they wish to have 201 * no namespace. 202 * @param namespaceURI The namespace URI of the attribute to create or 203 * alter. 204 * @param qualifiedName The qualified name of the attribute to create or 205 * alter. 206 * @param value The value to set in string form. 207 * @exception DOMException 208 * INVALID_CHARACTER_ERR: Raised if the specified qualified name is not 209 * an XML name according to the XML version in use specified in the 210 * <code>Document.xmlVersion</code> attribute. 211 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 212 * <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is 213 * malformed per the Namespaces in XML specification, if the 214 * <code>qualifiedName</code> has a prefix and the 215 * <code>namespaceURI</code> is <code>null</code>, if the 216 * <code>qualifiedName</code> has a prefix that is "xml" and the 217 * <code>namespaceURI</code> is different from "<a href='http://www.w3.org/XML/1998/namespace'> 218 * http://www.w3.org/XML/1998/namespace</a>", if the <code>qualifiedName</code> or its prefix is "xmlns" and the 219 * <code>namespaceURI</code> is different from "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>", or if the <code>namespaceURI</code> is "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>" and neither the <code>qualifiedName</code> nor its prefix is "xmlns". 220 * <br>NOT_SUPPORTED_ERR: May be raised if the implementation does not 221 * support the feature <code>"XML"</code> and the language exposed 222 * through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 223 * @since DOM Level 2 224 */ 225 public void setAttributeNS(String namespaceURI, 226 String qualifiedName, 227 String value) 228 throws DOMException; 229 230 /** 231 * Removes an attribute by local name and namespace URI. If a default 232 * value for the removed attribute is defined in the DTD, a new 233 * attribute immediately appears with the default value as well as the 234 * corresponding namespace URI, local name, and prefix when applicable. 235 * The implementation may handle default values from other schemas 236 * similarly but applications should use 237 * <code>Document.normalizeDocument()</code> to guarantee this 238 * information is up-to-date. 239 * <br>If no attribute with this local name and namespace URI is found, 240 * this method has no effect. 241 * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 242 * , applications must use the value <code>null</code> as the 243 * <code>namespaceURI</code> parameter for methods if they wish to have 244 * no namespace. 245 * @param namespaceURI The namespace URI of the attribute to remove. 246 * @param localName The local name of the attribute to remove. 247 * @exception DOMException 248 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 249 * <br>NOT_SUPPORTED_ERR: May be raised if the implementation does not 250 * support the feature <code>"XML"</code> and the language exposed 251 * through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 252 * @since DOM Level 2 253 */ 254 public void removeAttributeNS(String namespaceURI, 255 String localName) 256 throws DOMException; 257 258 /** 259 * Retrieves an <code>Attr</code> node by local name and namespace URI. 260 * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 261 * , applications must use the value <code>null</code> as the 262 * <code>namespaceURI</code> parameter for methods if they wish to have 263 * no namespace. 264 * @param namespaceURI The namespace URI of the attribute to retrieve. 265 * @param localName The local name of the attribute to retrieve. 266 * @return The <code>Attr</code> node with the specified attribute local 267 * name and namespace URI or <code>null</code> if there is no such 268 * attribute. 269 * @exception DOMException 270 * NOT_SUPPORTED_ERR: May be raised if the implementation does not 271 * support the feature <code>"XML"</code> and the language exposed 272 * through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 273 * @since DOM Level 2 274 */ 275 public Attr getAttributeNodeNS(String namespaceURI, 276 String localName) 277 throws DOMException; 278 279 /** 280 * Adds a new attribute. If an attribute with that local name and that 281 * namespace URI is already present in the element, it is replaced by 282 * the new one. Replacing an attribute node by itself has no effect. 283 * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 284 * , applications must use the value <code>null</code> as the 285 * <code>namespaceURI</code> parameter for methods if they wish to have 286 * no namespace. 287 * @param newAttr The <code>Attr</code> node to add to the attribute list. 288 * @return If the <code>newAttr</code> attribute replaces an existing 289 * attribute with the same local name and namespace URI, the replaced 290 * <code>Attr</code> node is returned, otherwise <code>null</code> is 291 * returned. 292 * @exception DOMException 293 * WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a 294 * different document than the one that created the element. 295 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 296 * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an 297 * attribute of another <code>Element</code> object. The DOM user must 298 * explicitly clone <code>Attr</code> nodes to re-use them in other 299 * elements. 300 * <br>NOT_SUPPORTED_ERR: May be raised if the implementation does not 301 * support the feature <code>"XML"</code> and the language exposed 302 * through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 303 * @since DOM Level 2 304 */ 305 public Attr setAttributeNodeNS(Attr newAttr) 306 throws DOMException; 307 308 /** 309 * Returns a <code>NodeList</code> of all the descendant 310 * <code>Elements</code> with a given local name and namespace URI in 311 * document order. 312 * @param namespaceURI The namespace URI of the elements to match on. The 313 * special value "*" matches all namespaces. 314 * @param localName The local name of the elements to match on. The 315 * special value "*" matches all local names. 316 * @return A new <code>NodeList</code> object containing all the matched 317 * <code>Elements</code>. 318 * @exception DOMException 319 * NOT_SUPPORTED_ERR: May be raised if the implementation does not 320 * support the feature <code>"XML"</code> and the language exposed 321 * through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 322 * @since DOM Level 2 323 */ 324 public NodeList getElementsByTagNameNS(String namespaceURI, 325 String localName) 326 throws DOMException; 327 328 /** 329 * Returns <code>true</code> when an attribute with a given name is 330 * specified on this element or has a default value, <code>false</code> 331 * otherwise. 332 * @param name The name of the attribute to look for. 333 * @return <code>true</code> if an attribute with the given name is 334 * specified on this element or has a default value, <code>false</code> 335 * otherwise. 336 * @since DOM Level 2 337 */ 338 public boolean hasAttribute(String name); 339 340 /** 341 * Returns <code>true</code> when an attribute with a given local name and 342 * namespace URI is specified on this element or has a default value, 343 * <code>false</code> otherwise. 344 * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 345 * , applications must use the value <code>null</code> as the 346 * <code>namespaceURI</code> parameter for methods if they wish to have 347 * no namespace. 348 * @param namespaceURI The namespace URI of the attribute to look for. 349 * @param localName The local name of the attribute to look for. 350 * @return <code>true</code> if an attribute with the given local name 351 * and namespace URI is specified or has a default value on this 352 * element, <code>false</code> otherwise. 353 * @exception DOMException 354 * NOT_SUPPORTED_ERR: May be raised if the implementation does not 355 * support the feature <code>"XML"</code> and the language exposed 356 * through the Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 357 * @since DOM Level 2 358 */ 359 public boolean hasAttributeNS(String namespaceURI, 360 String localName) 361 throws DOMException; 362 363 /** 364 * The type information associated with this element. 365 * @since DOM Level 3 366 */ 367 public TypeInfo getSchemaTypeInfo(); 368 369 /** 370 * If the parameter <code>isId</code> is <code>true</code>, this method 371 * declares the specified attribute to be a user-determined ID attribute 372 * . This affects the value of <code>Attr.isId</code> and the behavior 373 * of <code>Document.getElementById</code>, but does not change any 374 * schema that may be in use, in particular this does not affect the 375 * <code>Attr.schemaTypeInfo</code> of the specified <code>Attr</code> 376 * node. Use the value <code>false</code> for the parameter 377 * <code>isId</code> to undeclare an attribute for being a 378 * user-determined ID attribute. 379 * <br> To specify an attribute by local name and namespace URI, use the 380 * <code>setIdAttributeNS</code> method. 381 * @param name The name of the attribute. 382 * @param isId Whether the attribute is a of type ID. 383 * @exception DOMException 384 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 385 * <br>NOT_FOUND_ERR: Raised if the specified node is not an attribute 386 * of this element. 387 * @since DOM Level 3 388 */ 389 public void setIdAttribute(String name, 390 boolean isId) 391 throws DOMException; 392 393 /** 394 * If the parameter <code>isId</code> is <code>true</code>, this method 395 * declares the specified attribute to be a user-determined ID attribute 396 * . This affects the value of <code>Attr.isId</code> and the behavior 397 * of <code>Document.getElementById</code>, but does not change any 398 * schema that may be in use, in particular this does not affect the 399 * <code>Attr.schemaTypeInfo</code> of the specified <code>Attr</code> 400 * node. Use the value <code>false</code> for the parameter 401 * <code>isId</code> to undeclare an attribute for being a 402 * user-determined ID attribute. 403 * @param namespaceURI The namespace URI of the attribute. 404 * @param localName The local name of the attribute. 405 * @param isId Whether the attribute is a of type ID. 406 * @exception DOMException 407 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 408 * <br>NOT_FOUND_ERR: Raised if the specified node is not an attribute 409 * of this element. 410 * @since DOM Level 3 411 */ 412 public void setIdAttributeNS(String namespaceURI, 413 String localName, 414 boolean isId) 415 throws DOMException; 416 417 /** 418 * If the parameter <code>isId</code> is <code>true</code>, this method 419 * declares the specified attribute to be a user-determined ID attribute 420 * . This affects the value of <code>Attr.isId</code> and the behavior 421 * of <code>Document.getElementById</code>, but does not change any 422 * schema that may be in use, in particular this does not affect the 423 * <code>Attr.schemaTypeInfo</code> of the specified <code>Attr</code> 424 * node. Use the value <code>false</code> for the parameter 425 * <code>isId</code> to undeclare an attribute for being a 426 * user-determined ID attribute. 427 * @param idAttr The attribute node. 428 * @param isId Whether the attribute is a of type ID. 429 * @exception DOMException 430 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 431 * <br>NOT_FOUND_ERR: Raised if the specified node is not an attribute 432 * of this element. 433 * @since DOM Level 3 434 */ 435 public void setIdAttributeNode(Attr idAttr, 436 boolean isId) 437 throws DOMException; 438 439 } 440
