001/* 002 * Copyright (c) 2004 World Wide Web Consortium, 003 * 004 * (Massachusetts Institute of Technology, European Research Consortium for 005 * Informatics and Mathematics, Keio University). All Rights Reserved. This 006 * work is distributed under the W3C(r) Software License [1] in the hope that 007 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 008 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 009 * 010 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 011 */ 012 013package org.w3c.dom; 014 015/** 016 * The <code>Element</code> interface represents an element in an HTML or XML 017 * document. Elements may have attributes associated with them; since the 018 * <code>Element</code> interface inherits from <code>Node</code>, the 019 * generic <code>Node</code> interface attribute <code>attributes</code> may 020 * be used to retrieve the set of all attributes for an element. There are 021 * methods on the <code>Element</code> interface to retrieve either an 022 * <code>Attr</code> object by name or an attribute value by name. In XML, 023 * where an attribute value may contain entity references, an 024 * <code>Attr</code> object should be retrieved to examine the possibly 025 * fairly complex sub-tree representing the attribute value. On the other 026 * hand, in HTML, where all attributes have simple string values, methods to 027 * directly access an attribute value can safely be used as a convenience. 028 * <p ><b>Note:</b> In DOM Level 2, the method <code>normalize</code> is 029 * inherited from the <code>Node</code> interface where it was moved. 030 * <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>. 031 */ 032public interface Element extends Node { 033 /** 034 * The name of the element. If <code>Node.localName</code> is different 035 * from <code>null</code>, this attribute is a qualified name. For 036 * example, in: 037 * <pre> <elementExample id="demo"> ... 038 * </elementExample> , </pre> 039 * <code>tagName</code> has the value 040 * <code>"elementExample"</code>. Note that this is case-preserving in 041 * XML, as are all of the operations of the DOM. The HTML DOM returns 042 * the <code>tagName</code> of an HTML element in the canonical 043 * uppercase form, regardless of the case in the source HTML document. 044 */ 045 public String getTagName(); 046 047 /** 048 * Retrieves an attribute value by name. 049 * @param name The name of the attribute to retrieve. 050 * @return The <code>Attr</code> value as a string, or the empty string 051 * if that attribute does not have a specified or default value. 052 */ 053 public String getAttribute(String name); 054 055 /** 056 * Adds a new attribute. If an attribute with that name is already present 057 * in the element, its value is changed to be that of the value 058 * parameter. This value is a simple string; it is not parsed as it is 059 * being set. So any markup (such as syntax to be recognized as an 060 * entity reference) is treated as literal text, and needs to be 061 * appropriately escaped by the implementation when it is written out. 062 * In order to assign an attribute value that contains entity 063 * references, the user must create an <code>Attr</code> node plus any 064 * <code>Text</code> and <code>EntityReference</code> nodes, build the 065 * appropriate subtree, and use <code>setAttributeNode</code> to assign 066 * it as the value of an attribute. 067 * <br>To set an attribute with a qualified name and namespace URI, use 068 * the <code>setAttributeNS</code> method. 069 * @param name The name of the attribute to create or alter. 070 * @param value Value to set in string form. 071 * @exception DOMException 072 * INVALID_CHARACTER_ERR: Raised if the specified name is not an XML 073 * name according to the XML version in use specified in the 074 * <code>Document.xmlVersion</code> attribute. 075 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 076 */ 077 public void setAttribute(String name, 078 String value) 079 throws DOMException; 080 081 /** 082 * Removes an attribute by name. If a default value for the removed 083 * attribute is defined in the DTD, a new attribute immediately appears 084 * with the default value as well as the corresponding namespace URI, 085 * local name, and prefix when applicable. The implementation may handle 086 * default values from other schemas similarly but applications should 087 * use <code>Document.normalizeDocument()</code> to guarantee this 088 * information is up-to-date. 089 * <br>If no attribute with this name is found, this method has no effect. 090 * <br>To remove an attribute by local name and namespace URI, use the 091 * <code>removeAttributeNS</code> method. 092 * @param name The name of the attribute to remove. 093 * @exception DOMException 094 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 095 */ 096 public void removeAttribute(String name) 097 throws DOMException; 098 099 /** 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}