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 nameThe 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 nameThe name of the attribute to create or alter.
069: * @param valueValue 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 nameThe 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 nameThe 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 newAttrThe <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 oldAttrThe <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 nameThe 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. HTML-only
151: * DOM implementations do not need to implement this method.
152: * @param namespaceURIThe namespace URI of the attribute to retrieve.
153: * @param localNameThe local name of the attribute to retrieve.
154: * @return The <code>Attr</code> value as a string, or the empty string
155: * if that attribute does not have a specified or default value.
156: * @since DOM Level 2
157: */
158: public String getAttributeNS(String namespaceURI, String localName);
159:
160: /**
161: * Adds a new attribute. If an attribute with the same local name and
162: * namespace URI is already present on the element, its prefix is
163: * changed to be the prefix part of the <code>qualifiedName</code>, and
164: * its value is changed to be the <code>value</code> parameter. This
165: * value is a simple string; it is not parsed as it is being set. So any
166: * markup (such as syntax to be recognized as an entity reference) is
167: * treated as literal text, and needs to be appropriately escaped by the
168: * implementation when it is written out. In order to assign an
169: * attribute value that contains entity references, the user must create
170: * an <code>Attr</code> node plus any <code>Text</code> and
171: * <code>EntityReference</code> nodes, build the appropriate subtree,
172: * and use <code>setAttributeNodeNS</code> or
173: * <code>setAttributeNode</code> to assign it as the value of an
174: * attribute.
175: * <br>HTML-only DOM implementations do not need to implement this method.
176: * @param namespaceURIThe namespace URI of the attribute to create or
177: * alter.
178: * @param qualifiedNameThe qualified name of the attribute to create or
179: * alter.
180: * @param valueThe value to set in string form.
181: * @exception DOMException
182: * INVALID_CHARACTER_ERR: Raised if the specified qualified name
183: * contains an illegal character.
184: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
185: * <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
186: * malformed, if the <code>qualifiedName</code> has a prefix and the
187: * <code>namespaceURI</code> is <code>null</code>, if the
188: * <code>qualifiedName</code> has a prefix that is "xml" and the
189: * <code>namespaceURI</code> is different from "
190: * http://www.w3.org/XML/1998/namespace", or if the
191: * <code>qualifiedName</code> is "xmlns" and the
192: * <code>namespaceURI</code> is different from "
193: * http://www.w3.org/2000/xmlns/".
194: * @since DOM Level 2
195: */
196: public void setAttributeNS(String namespaceURI,
197: String qualifiedName, String value) throws DOMException;
198:
199: /**
200: * Removes an attribute by local name and namespace URI. If the removed
201: * attribute has a default value it is immediately replaced. The
202: * replacing attribute has the same namespace URI and local name, as
203: * well as the original prefix.
204: * <br>HTML-only DOM implementations do not need to implement this method.
205: * @param namespaceURIThe namespace URI of the attribute to remove.
206: * @param localNameThe local name of the attribute to remove.
207: * @exception DOMException
208: * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
209: * @since DOM Level 2
210: */
211: public void removeAttributeNS(String namespaceURI, String localName)
212: throws DOMException;
213:
214: /**
215: * Retrieves an <code>Attr</code> node by local name and namespace URI.
216: * HTML-only DOM implementations do not need to implement this method.
217: * @param namespaceURIThe namespace URI of the attribute to retrieve.
218: * @param localNameThe local name of the attribute to retrieve.
219: * @return The <code>Attr</code> node with the specified attribute local
220: * name and namespace URI or <code>null</code> if there is no such
221: * attribute.
222: * @since DOM Level 2
223: */
224: public Attr getAttributeNodeNS(String namespaceURI, String localName);
225:
226: /**
227: * Adds a new attribute. If an attribute with that local name and that
228: * namespace URI is already present in the element, it is replaced by
229: * the new one.
230: * <br>HTML-only DOM implementations do not need to implement this method.
231: * @param newAttrThe <code>Attr</code> node to add to the attribute list.
232: * @return If the <code>newAttr</code> attribute replaces an existing
233: * attribute with the same local name and namespace URI, the replaced
234: * <code>Attr</code> node is returned, otherwise <code>null</code> is
235: * returned.
236: * @exception DOMException
237: * WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was created from a
238: * different document than the one that created the element.
239: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
240: * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
241: * attribute of another <code>Element</code> object. The DOM user must
242: * explicitly clone <code>Attr</code> nodes to re-use them in other
243: * elements.
244: * @since DOM Level 2
245: */
246: public Attr setAttributeNodeNS(Attr newAttr) throws DOMException;
247:
248: /**
249: * Returns a <code>NodeList</code> of all the descendant
250: * <code>Elements</code> with a given local name and namespace URI in
251: * the order in which they are encountered in a preorder traversal of
252: * this <code>Element</code> tree.
253: * <br>HTML-only DOM implementations do not need to implement this method.
254: * @param namespaceURIThe namespace URI of the elements to match on. The
255: * special value "*" matches all namespaces.
256: * @param localNameThe local name of the elements to match on. The
257: * special value "*" matches all local names.
258: * @return A new <code>NodeList</code> object containing all the matched
259: * <code>Elements</code>.
260: * @since DOM Level 2
261: */
262: public NodeList getElementsByTagNameNS(String namespaceURI,
263: String localName);
264:
265: /**
266: * Returns <code>true</code> when an attribute with a given name is
267: * specified on this element or has a default value, <code>false</code>
268: * otherwise.
269: * @param nameThe name of the attribute to look for.
270: * @return <code>true</code> if an attribute with the given name is
271: * specified on this element or has a default value, <code>false</code>
272: * otherwise.
273: * @since DOM Level 2
274: */
275: public boolean hasAttribute(String name);
276:
277: /**
278: * Returns <code>true</code> when an attribute with a given local name and
279: * namespace URI is specified on this element or has a default value,
280: * <code>false</code> otherwise. HTML-only DOM implementations do not
281: * need to implement this method.
282: * @param namespaceURIThe namespace URI of the attribute to look for.
283: * @param localNameThe local name of the attribute to look for.
284: * @return <code>true</code> if an attribute with the given local name
285: * and namespace URI is specified or has a default value on this
286: * element, <code>false</code> otherwise.
287: * @since DOM Level 2
288: */
289: public boolean hasAttributeNS(String namespaceURI, String localName);
290:
291: }
|