001: /*
002: * Copyright (c) 2000 World Wide Web Consortium,
003: * (Massachusetts Institute of Technology, Institut National de
004: * Recherche en Informatique et en Automatique, Keio University). All
005: * Rights Reserved. This program is distributed under the W3C's Software
006: * Intellectual Property License. This program is distributed in the
007: * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
008: * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
009: * PURPOSE.
010: * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
011: */
012:
013: package 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.In
028: * DOM Level 2, the method <code>normalize</code> is inherited from the
029: * <code>Node</code> interface where it was moved.
030: * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
031: */
032: public interface Element extends Node {
033: /**
034: * The name of the element. For example, in:
035: * <pre> <elementExample
036: * id="demo"> ... </elementExample> , </pre>
037: * <code>tagName</code> has
038: * the value <code>"elementExample"</code>. Note that this is
039: * case-preserving in XML, as are all of the operations of the DOM. The
040: * HTML DOM returns the <code>tagName</code> of an HTML element in the
041: * canonical uppercase form, regardless of the case in the source HTML
042: * document.
043: */
044: public String getTagName();
045:
046: /**
047: * Retrieves an attribute value by name.
048: * @param name The name of the attribute to retrieve.
049: * @return The <code>Attr</code> value as a string, or the empty string
050: * if that attribute does not have a specified or default value.
051: */
052: public String getAttribute(String name);
053:
054: /**
055: * Adds a new attribute. If an attribute with that name is already present
056: * in the element, its value is changed to be that of the value
057: * parameter. This value is a simple string; it is not parsed as it is
058: * being set. So any markup (such as syntax to be recognized as an
059: * entity reference) is treated as literal text, and needs to be
060: * appropriately escaped by the implementation when it is written out.
061: * In order to assign an attribute value that contains entity
062: * references, the user must create an <code>Attr</code> node plus any
063: * <code>Text</code> and <code>EntityReference</code> nodes, build the
064: * appropriate subtree, and use <code>setAttributeNode</code> to assign
065: * it as the value of an attribute.
066: * <br>To set an attribute with a qualified name and namespace URI, use
067: * the <code>setAttributeNS</code> method.
068: * @param name The name of the attribute to create or alter.
069: * @param value Value to set in string form.
070: * @exception DOMException
071: * INVALID_CHARACTER_ERR: Raised if the specified name contains an
072: * illegal character.
073: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
074: */
075: public void setAttribute(String name, String value)
076: throws DOMException;
077:
078: /**
079: * Removes an attribute by name. If the removed attribute is known to have
080: * a default value, an attribute immediately appears containing the
081: * default value as well as the corresponding namespace URI, local name,
082: * and prefix when applicable.
083: * <br>To remove an attribute by local name and namespace URI, use the
084: * <code>removeAttributeNS</code> method.
085: * @param name The name of the attribute to remove.
086: * @exception DOMException
087: * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
088: */
089: public void removeAttribute(String name) throws DOMException;
090:
091: /**
092: * Retrieves an attribute node by name.
093: * <br>To retrieve an attribute node by qualified name and namespace URI,
094: * use the <code>getAttributeNodeNS</code> method.
095: * @param name The name (<code>nodeName</code>) of the attribute to
096: * retrieve.
097: * @return The <code>Attr</code> node with the specified name (
098: * <code>nodeName</code>) or <code>null</code> if there is no such
099: * attribute.
100: */
101: public Attr getAttributeNode(String name);
102:
103: /**
104: * Adds a new attribute node. If an attribute with that name (
105: * <code>nodeName</code>) is already present in the element, it is
106: * replaced by the new one.
107: * <br>To add a new attribute node with a qualified name and namespace
108: * URI, use the <code>setAttributeNodeNS</code> method.
109: * @param newAttr The <code>Attr</code> node to add to the attribute list.
110: * @return If the <code>newAttr</code> attribute replaces an existing
111: * attribute, the replaced <code>Attr</code> node is returned,
112: * otherwise <code>null</code> is returned.
113: * @exception DOMException
114: * WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a
115: * different document than the one that created the element.
116: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
117: * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
118: * attribute of another <code>Element</code> object. The DOM user must
119: * explicitly clone <code>Attr</code> nodes to re-use them in other
120: * elements.
121: */
122: public Attr setAttributeNode(Attr newAttr) throws DOMException;
123:
124: /**
125: * Removes the specified attribute node. If the removed <code>Attr</code>
126: * has a default value it is immediately replaced. The replacing
127: * attribute has the same namespace URI and local name, as well as the
128: * original prefix, when applicable.
129: * @param oldAttr The <code>Attr</code> node to remove from the attribute
130: * list.
131: * @return The <code>Attr</code> node that was removed.
132: * @exception DOMException
133: * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
134: * <br>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute
135: * of the element.
136: */
137: public Attr removeAttributeNode(Attr oldAttr) throws DOMException;
138:
139: /**
140: * Returns a <code>NodeList</code> of all descendant <code>Elements</code>
141: * with a given tag name, in the order in which they are encountered in
142: * a preorder traversal of this <code>Element</code> tree.
143: * @param name The name of the tag to match on. The special value "*"
144: * matches all tags.
145: * @return A list of matching <code>Element</code> nodes.
146: */
147: public NodeList getElementsByTagName(String name);
148:
149: /**
150: * Retrieves an attribute value by local name and namespace URI.
151: * <br>Documents which do not support the "XML" feature will permit only
152: * the DOM Level 1 calls for creating/setting elements and attributes.
153: * Hence, if you specify a non-null namespace URI, these DOMs will never
154: * find a matching node.
155: * @param namespaceURI The namespace URI of the attribute to retrieve.
156: * @param localName The local name of the attribute to retrieve.
157: * @return The <code>Attr</code> value as a string, or the empty string
158: * if that attribute does not have a specified or default value.
159: * @since DOM Level 2
160: */
161: public String getAttributeNS(String namespaceURI, String localName);
162:
163: /**
164: * Adds a new attribute. If an attribute with the same local name and
165: * namespace URI is already present on the element, its prefix is
166: * changed to be the prefix part of the <code>qualifiedName</code>, and
167: * its value is changed to be the <code>value</code> parameter. This
168: * value is a simple string; it is not parsed as it is being set. So any
169: * markup (such as syntax to be recognized as an entity reference) is
170: * treated as literal text, and needs to be appropriately escaped by the
171: * implementation when it is written out. In order to assign an
172: * attribute value that contains entity references, the user must create
173: * an <code>Attr</code> node plus any <code>Text</code> and
174: * <code>EntityReference</code> nodes, build the appropriate subtree,
175: * and use <code>setAttributeNodeNS</code> or
176: * <code>setAttributeNode</code> to assign it as the value of an
177: * attribute.
178: * @param namespaceURI The namespace URI of the attribute to create or
179: * alter.
180: * @param qualifiedName The qualified name of the attribute to create or
181: * alter.
182: * @param value The value to set in string form.
183: * @exception DOMException
184: * INVALID_CHARACTER_ERR: Raised if the specified qualified name
185: * contains an illegal character, per the XML 1.0 specification .
186: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
187: * <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
188: * malformed per the Namespaces in XML specification, if the
189: * <code>qualifiedName</code> has a prefix and the
190: * <code>namespaceURI</code> is <code>null</code>, if the
191: * <code>qualifiedName</code> has a prefix that is "xml" and the
192: * <code>namespaceURI</code> is different from "
193: * http://www.w3.org/XML/1998/namespace", or if the
194: * <code>qualifiedName</code>, or its prefix, is "xmlns" and the
195: * <code>namespaceURI</code> is different from "
196: * http://www.w3.org/2000/xmlns/".
197: * <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
198: * support the <code>"XML"</code> feature, since namespaces were
199: * defined by XML.
200: * @since DOM Level 2
201: */
202: public void setAttributeNS(String namespaceURI,
203: String qualifiedName, String value) throws DOMException;
204:
205: /**
206: * Removes an attribute by local name and namespace URI. If the removed
207: * attribute has a default value it is immediately replaced. The
208: * replacing attribute has the same namespace URI and local name, as
209: * well as the original prefix.
210: * <br>Documents which do not support the "XML" feature will permit only
211: * the DOM Level 1 calls for creating/setting elements and attributes.
212: * Hence, if you specify a non-null namespace URI, these DOMs will never
213: * find a matching node.
214: * @param namespaceURI The namespace URI of the attribute to remove.
215: * @param localName The local name of the attribute to remove.
216: * @exception DOMException
217: * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
218: * @since DOM Level 2
219: */
220: public void removeAttributeNS(String namespaceURI, String localName)
221: throws DOMException;
222:
223: /**
224: * Retrieves an <code>Attr</code> node by local name and namespace URI.
225: * <br>Documents which do not support the "XML" feature will permit only
226: * the DOM Level 1 calls for creating/setting elements and attributes.
227: * Hence, if you specify a non-null namespace URI, these DOMs will never
228: * find a matching node.
229: * @param namespaceURI The namespace URI of the attribute to retrieve.
230: * @param localName The local name of the attribute to retrieve.
231: * @return The <code>Attr</code> node with the specified attribute local
232: * name and namespace URI or <code>null</code> if there is no such
233: * attribute.
234: * @since DOM Level 2
235: */
236: public Attr getAttributeNodeNS(String namespaceURI, String localName);
237:
238: /**
239: * Adds a new attribute. If an attribute with that local name and that
240: * namespace URI is already present in the element, it is replaced by
241: * the new one.
242: * @param newAttr The <code>Attr</code> node to add to the attribute list.
243: * @return If the <code>newAttr</code> attribute replaces an existing
244: * attribute with the same local name and namespace URI, the replaced
245: * <code>Attr</code> node is returned, otherwise <code>null</code> is
246: * returned.
247: * @exception DOMException
248: * WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a
249: * different document than the one that created the element.
250: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
251: * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
252: * attribute of another <code>Element</code> object. The DOM user must
253: * explicitly clone <code>Attr</code> nodes to re-use them in other
254: * elements.
255: * <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
256: * support the <code>"XML"</code> feature, since namespaces were
257: * defined by XML.
258: * @since DOM Level 2
259: */
260: public Attr setAttributeNodeNS(Attr newAttr) throws DOMException;
261:
262: /**
263: * Returns a <code>NodeList</code> of all the descendant
264: * <code>Elements</code> with a given local name and namespace URI in
265: * the order in which they are encountered in a preorder traversal of
266: * this <code>Element</code> tree.
267: * <br>Documents which do not support the "XML" feature will permit only
268: * the DOM Level 1 calls for creating/setting elements and attributes.
269: * Hence, if you specify a non-null namespace URI, these DOMs will never
270: * find a matching node.
271: * @param namespaceURI The namespace URI of the elements to match on. The
272: * special value "*" matches all namespaces.
273: * @param localName The local name of the elements to match on. The
274: * special value "*" matches all local names.
275: * @return A new <code>NodeList</code> object containing all the matched
276: * <code>Elements</code>.
277: * @since DOM Level 2
278: */
279: public NodeList getElementsByTagNameNS(String namespaceURI,
280: String localName);
281:
282: /**
283: * Returns <code>true</code> when an attribute with a given name is
284: * specified on this element or has a default value, <code>false</code>
285: * otherwise.
286: * @param name The name of the attribute to look for.
287: * @return <code>true</code> if an attribute with the given name is
288: * specified on this element or has a default value, <code>false</code>
289: * otherwise.
290: * @since DOM Level 2
291: */
292: public boolean hasAttribute(String name);
293:
294: /**
295: * Returns <code>true</code> when an attribute with a given local name and
296: * namespace URI is specified on this element or has a default value,
297: * <code>false</code> otherwise.
298: * <br>Documents which do not support the "XML" feature will permit only
299: * the DOM Level 1 calls for creating/setting elements and attributes.
300: * Hence, if you specify a non-null namespace URI, these DOMs will never
301: * find a matching node.
302: * @param namespaceURI The namespace URI of the attribute to look for.
303: * @param localName The local name of the attribute to look for.
304: * @return <code>true</code> if an attribute with the given local name
305: * and namespace URI is specified or has a default value on this
306: * element, <code>false</code> otherwise.
307: * @since DOM Level 2
308: */
309: public boolean hasAttributeNS(String namespaceURI, String localName);
310:
311: }
|