2
* Copyright (c) 2003 World Wide Web Consortium,
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.
10
* [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
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/2003/CR-DOM-Level-3-Core-20031107'>Document Object Model (DOM) Level 3 Core Specification</a>.
32
public interface Element extends Node {
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
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.
45
public String getTagName();
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.
53
public String getAttribute(String name);
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 contains an
73
* illegal character according to the XML version in use specified in
74
* the <code>Document.xmlVersion</code> attribute.
75
* <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
77
public void setAttribute(String name,
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.
96
public void removeAttribute(String name)
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
105
* @return The <code>Attr</code> node with the specified name (
106
* <code>nodeName</code>) or <code>null</code> if there is no such
109
public Attr getAttributeNode(String name);
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
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
131
public Attr setAttributeNode(Attr newAttr)
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
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
151
public Attr removeAttributeNode(Attr oldAttr)
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 "*"
159
* @return A list of matching <code>Element</code> nodes.
161
public NodeList getElementsByTagName(String name);
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
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>]).
179
public String getAttributeNS(String namespaceURI,
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
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
202
* @param namespaceURI The namespace URI of the attribute to create or
204
* @param qualifiedName The qualified name of the attribute to create or
206
* @param value The value to set in string form.
207
* @exception DOMException
208
* INVALID_CHARACTER_ERR: Raised if the specified qualified name
209
* contains an illegal character according to the XML version in use
210
* specified in the <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>]).
225
public void setAttributeNS(String namespaceURI,
226
String qualifiedName,
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
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>]).
254
public void removeAttributeNS(String namespaceURI,
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
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
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>]).
275
public Attr getAttributeNodeNS(String namespaceURI,
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
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
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
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>]).
305
public Attr setAttributeNodeNS(Attr newAttr)
309
* Returns a <code>NodeList</code> of all the descendant
310
* <code>Elements</code> with a given local name and namespace URI in
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>]).
324
public NodeList getElementsByTagNameNS(String namespaceURI,
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>
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>
338
public boolean hasAttribute(String name);
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
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>]).
359
public boolean hasAttributeNS(String namespaceURI,
364
* The type information associated with this element.
367
public TypeInfo getSchemaTypeInfo();
370
* Declares the attribute specified by name to be of type ID, i.e. the
371
* <code>Attr</code> node becomes a user-determined ID attribute and its
372
* attribute <code>Attr.isId</code> will be <code>true</code>. Note,
373
* however, that this simply affects the attribute <code>Attr.isId</code>
374
* of the <code>Attr</code> node and does not change any schema that
375
* may be in use, in particular this does not affect the
376
* <code>Attr.schemaTypeInfo</code> of the specified <code>Attr</code>
378
* <br> To specify an attribute by local name and namespace URI, use the
379
* <code>setIdAttributeNS</code> method.
380
* @param name The name of the attribute.
381
* @param isId Whether the attribute is a of type ID.
382
* @exception DOMException
383
* NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
384
* <br>NOT_FOUND_ERR: Raised if the specified node is not an attribute
388
public void setIdAttribute(String name,
393
* Declares the attribute specified by local name and namespace URI to be
394
* of type ID, i.e. the <code>Attr</code> node becomes a user-determined
395
* ID attribute and its attribute <code>Attr.isId</code> will be
396
* <code>true</code>. Note, however, that this simply affects the
397
* attribute <code>Attr.isId</code> of the <code>Attr</code> node and
398
* does not change any schema that may be in use, in particular this
399
* does not affect the <code>Attr.schemaTypeInfo</code> of the specified
400
* <code>Attr</code> node.
401
* @param namespaceURI The namespace URI of the attribute.
402
* @param localName The local name of the attribute.
403
* @param isId Whether the attribute is a of type ID.
404
* @exception DOMException
405
* NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
406
* <br>NOT_FOUND_ERR: Raised if the specified node is not an attribute
410
public void setIdAttributeNS(String namespaceURI,
416
* Declares the attribute specified by node to be of type ID, i.e. the
417
* <code>Attr</code> node becomes a user-determined ID attribute and its
418
* attribute <code>Attr.isId</code> will be <code>true</code>. Note,
419
* however, that this simply affects the attribute <code>Attr.isId</code>
420
* of the <code>Attr</code> node and does not change any schema that
421
* may be in use, in particular this does not affect the
422
* <code>Attr.schemaTypeInfo</code> of the specified <code>Attr</code>
424
* @param idAttr The attribute node.
425
* @param isId Whether the attribute is a of type ID.
426
* @exception DOMException
427
* NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
428
* <br>NOT_FOUND_ERR: Raised if the specified node is not an attribute
432
public void setIdAttributeNode(Attr idAttr,
added
removed
src/dom3/org/w3c/dom/Element.java
