From 5ab0e788b4b6927cc3907af24d271a39ce9e483c Mon Sep 17 00:00:00 2001 From: edwingo Date: Wed, 1 Aug 2001 23:24:39 +0000 Subject: [PATCH] Updated DOM Level 2 Core classes to latest errata. See http://www.w3.org/2000/11/DOM-Level-2-errata core-18. Javadoc fixes. git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@225921 13f79535-47bb-0310-9956-ffa450edef68 --- java/external/src/org/w3c/dom/Attr.java | 31 ++- .../src/org/w3c/dom/CDATASection.java | 4 +- .../src/org/w3c/dom/CharacterData.java | 35 +++- .../src/org/w3c/dom/DOMException.java | 4 +- .../src/org/w3c/dom/DOMImplementation.java | 48 +++-- java/external/src/org/w3c/dom/Document.java | 153 +++++++++----- .../src/org/w3c/dom/DocumentType.java | 9 +- java/external/src/org/w3c/dom/Element.java | 94 +++++---- java/external/src/org/w3c/dom/Entity.java | 2 +- .../src/org/w3c/dom/NamedNodeMap.java | 46 +++-- java/external/src/org/w3c/dom/Node.java | 190 +++++++++++++++--- java/external/src/org/w3c/dom/NodeList.java | 4 +- .../org/w3c/dom/ProcessingInstruction.java | 7 + java/external/src/org/w3c/dom/Text.java | 2 +- 14 files changed, 456 insertions(+), 173 deletions(-) diff --git a/java/external/src/org/w3c/dom/Attr.java b/java/external/src/org/w3c/dom/Attr.java index 05b0c12..4ba62e2 100644 --- a/java/external/src/org/w3c/dom/Attr.java +++ b/java/external/src/org/w3c/dom/Attr.java @@ -13,7 +13,7 @@ package org.w3c.dom; /** - * The Attr interface represents an attribute in an + * The Attr interface represents an attribute in an * Element object. Typically the allowable values for the * attribute are defined in a document type definition. *

Attr objects inherit the Node interface, but @@ -33,7 +33,7 @@ package org.w3c.dom; * DOM need to be aware that Attr nodes have some things in * common with other objects inheriting the Node interface, but * they also are quite distinct. - *

The attribute's effective value is determined as follows: if this + *

The attribute's effective value is determined as follows: if this * attribute has been explicitly assigned any value, that value is the * attribute's effective value; otherwise, if there is a declaration for * this attribute, and that declaration includes a default value, then that @@ -41,19 +41,19 @@ package org.w3c.dom; * attribute does not exist on this element in the structure model until it * has been explicitly added. Note that the nodeValue attribute * on the Attr instance can also be used to retrieve the string - * version of the attribute's value(s). + * version of the attribute's value(s). *

In XML, where the value of an attribute can contain entity references, * the child nodes of the Attr node may be either * Text or EntityReference nodes (when these are * in use; see the description of EntityReference for * discussion). Because the DOM Core is not aware of attribute types, it * treats all attribute values as simple strings, even if the DTD or schema - * declares them as having tokenized types. + * declares them as having tokenized types. *

See also the Document Object Model (DOM) Level 2 Core Specification. */ public interface Attr extends Node { /** - * Returns the name of this attribute. + * Returns the name of this attribute. */ public String getName(); @@ -69,14 +69,14 @@ public interface Attr extends Node { * implementation will then make a new attribute available with * specified set to false and the default * value (if one exists). - *
In summary: If the attribute has an assigned value in the document + *
In summary: If the attribute has an assigned value in the document * then specified is true, and the value is - * the assigned value. If the attribute has no assigned value in the + * the assigned value.If the attribute has no assigned value in the * document and has a default value in the DTD, then * specified is false, and the value is the - * default value in the DTD. If the attribute has no assigned value in + * default value in the DTD.If the attribute has no assigned value in * the document and has a value of #IMPLIED in the DTD, then the - * attribute does not appear in the structure model of the document. If + * attribute does not appear in the structure model of the document.If * the ownerElement attribute is null (i.e. * because it was just created or was set to null by the * various removal and cloning operations) specified is @@ -98,6 +98,19 @@ public interface Attr extends Node { * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly. */ public String getValue(); + /** + * On retrieval, the value of the attribute is returned as a string. + * Character and general entity references are replaced with their + * values. See also the method getAttribute on the + * Element interface. + *
On setting, this creates a Text node with the unparsed + * contents of the string. I.e. any characters that an XML processor + * would recognize as markup are instead treated as literal text. See + * also the method setAttribute on the Element + * interface. + * @exception DOMException + * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly. + */ public void setValue(String value) throws DOMException; diff --git a/java/external/src/org/w3c/dom/CDATASection.java b/java/external/src/org/w3c/dom/CDATASection.java index 9e74734..f3aea8a 100644 --- a/java/external/src/org/w3c/dom/CDATASection.java +++ b/java/external/src/org/w3c/dom/CDATASection.java @@ -24,8 +24,8 @@ package org.w3c.dom; * contain characters that need to be escaped outside of CDATA sections and * that, depending on the character encoding ("charset") chosen for * serialization, it may be impossible to write out some characters as part - * of a CDATA section. - *

The CDATASection interface inherits from the + * of a CDATA section. + *

The CDATASection interface inherits from the * CharacterData interface through the Text * interface. Adjacent CDATASection nodes are not merged by use * of the normalize method of the Node interface. diff --git a/java/external/src/org/w3c/dom/CharacterData.java b/java/external/src/org/w3c/dom/CharacterData.java index 9a25f7d..c067120 100644 --- a/java/external/src/org/w3c/dom/CharacterData.java +++ b/java/external/src/org/w3c/dom/CharacterData.java @@ -44,6 +44,21 @@ public interface CharacterData extends Node { */ public String getData() throws DOMException; + /** + * The character data of the node that implements this interface. The DOM + * implementation may not put arbitrary limits on the amount of data + * that may be stored in a CharacterData node. However, + * implementation limits may mean that the entirety of a node's data may + * not fit into a single DOMString. In such cases, the user + * may call substringData to retrieve the data in + * appropriately sized pieces. + * @exception DOMException + * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly. + * @exception DOMException + * DOMSTRING_SIZE_ERR: Raised when it would return more characters than + * fit in a DOMString variable on the implementation + * platform. + */ public void setData(String data) throws DOMException; @@ -56,8 +71,8 @@ public interface CharacterData extends Node { /** * Extracts a range of data from the node. - * @param offsetStart offset of substring to extract. - * @param countThe number of 16-bit units to extract. + * @param offset Start offset of substring to extract. + * @param count The number of 16-bit units to extract. * @return The specified substring. If the sum of offset and * count exceeds the length, then all 16-bit * units to the end of the data are returned. @@ -77,7 +92,7 @@ public interface CharacterData extends Node { * Append the string to the end of the character data of the node. Upon * success, data provides access to the concatenation of * data and the DOMString specified. - * @param argThe DOMString to append. + * @param arg The DOMString to append. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. */ @@ -86,8 +101,8 @@ public interface CharacterData extends Node { /** * Insert a string at the specified 16-bit unit offset. - * @param offsetThe character offset at which to insert. - * @param argThe DOMString to insert. + * @param offset The character offset at which to insert. + * @param arg The DOMString to insert. * @exception DOMException * INDEX_SIZE_ERR: Raised if the specified offset is * negative or greater than the number of 16-bit units in @@ -101,8 +116,8 @@ public interface CharacterData extends Node { /** * Remove a range of 16-bit units from the node. Upon success, * data and length reflect the change. - * @param offsetThe offset from which to start removing. - * @param countThe number of 16-bit units to delete. If the sum of + * @param offset The offset from which to start removing. + * @param count The number of 16-bit units to delete. If the sum of * offset and count exceeds * length then all 16-bit units from offset * to the end of the data are deleted. @@ -120,14 +135,14 @@ public interface CharacterData extends Node { /** * Replace the characters starting at the specified 16-bit unit offset * with the specified string. - * @param offsetThe offset from which to start replacing. - * @param countThe number of 16-bit units to replace. If the sum of + * @param offset The offset from which to start replacing. + * @param count The number of 16-bit units to replace. If the sum of * offset and count exceeds * length, then all 16-bit units to the end of the data * are replaced; (i.e., the effect is the same as a remove * method call with the same range, followed by an append * method invocation). - * @param argThe DOMString with which the range must be + * @param arg The DOMString with which the range must be * replaced. * @exception DOMException * INDEX_SIZE_ERR: Raised if the specified offset is diff --git a/java/external/src/org/w3c/dom/DOMException.java b/java/external/src/org/w3c/dom/DOMException.java index 098c6c5..16866ce 100644 --- a/java/external/src/org/w3c/dom/DOMException.java +++ b/java/external/src/org/w3c/dom/DOMException.java @@ -18,10 +18,10 @@ package org.w3c.dom; * because data is lost, or because the implementation has become unstable). * In general, DOM methods return specific error values in ordinary * processing situations, such as out-of-bound errors when using - * NodeList. + * NodeList. *

Implementations should raise other exceptions under other circumstances. * For example, implementations should raise an implementation-dependent - * exception if a null argument is passed. + * exception if a null argument is passed. *

Some languages and object systems do not support the concept of * exceptions. For such systems, error conditions may be indicated using * native error reporting mechanisms. For some bindings, for example, diff --git a/java/external/src/org/w3c/dom/DOMImplementation.java b/java/external/src/org/w3c/dom/DOMImplementation.java index 998af94..6e9a554 100644 --- a/java/external/src/org/w3c/dom/DOMImplementation.java +++ b/java/external/src/org/w3c/dom/DOMImplementation.java @@ -21,17 +21,13 @@ package org.w3c.dom; public interface DOMImplementation { /** * Test if the DOM implementation implements a specific feature. - * @param featureThe name of the feature to test (case-insensitive). The + * @param feature The name of the feature to test (case-insensitive). The * values used by DOM features are defined throughout the DOM Level 2 * specifications and listed in the section. The name must be an XML * name. To avoid possible conflicts, as a convention, names referring * to features defined outside the DOM specification should be made - * unique by reversing the name of the Internet domain name of the - * person (or the organization that the person belongs to) who defines - * the feature, component by component, and using this as a prefix. - * For instance, the W3C SVG Working Group defines the feature - * "org.w3c.dom.svg". - * @param versionThis is the version number of the feature to test. In + * unique. + * @param version This is the version number of the feature to test. In * Level 2, the string can be either "2.0" or "1.0". If the version is * not specified, supporting any version of the feature causes the * method to return true. @@ -47,11 +43,10 @@ public interface DOMImplementation { * default attribute additions do not occur. It is expected that a * future version of the DOM will provide a way for populating a * DocumentType. - *
HTML-only DOM implementations do not need to implement this method. - * @param qualifiedNameThe qualified name of the document type to be - * created. - * @param publicIdThe external subset public identifier. - * @param systemIdThe external subset system identifier. + * @param qualifiedName The qualified name of the document type to be + * created. + * @param publicId The external subset public identifier. + * @param systemId The external subset system identifier. * @return A new DocumentType node with * Node.ownerDocument set to null. * @exception DOMException @@ -59,6 +54,12 @@ public interface DOMImplementation { * contains an illegal character. *
NAMESPACE_ERR: Raised if the qualifiedName is * malformed. + *
NOT_SUPPORTED_ERR: May be raised by DOM implementations which do + * not support the "XML" feature, if they choose not to + * support this method. Other features introduced in the future, by + * the DOM WG or in extensions defined by other groups, may also + * demand support for this method; please consult the definition of + * the feature to see if it requires this method. * @since DOM Level 2 */ public DocumentType createDocumentType(String qualifiedName, @@ -67,13 +68,13 @@ public interface DOMImplementation { throws DOMException; /** - * Creates an XML Document object of the specified type with - * its document element. HTML-only DOM implementations do not need to - * implement this method. - * @param namespaceURIThe namespace URI of the document element to create. - * @param qualifiedNameThe qualified name of the document element to be + * Creates a DOM Document object of the specified type with its document + * element. + * @param namespaceURI The namespace URI of the document element to + * create. + * @param qualifiedName The qualified name of the document element to be * created. - * @param doctypeThe type of document to be created or null. + * @param doctype The type of document to be created or null. * When doctype is not null, its * Node.ownerDocument attribute is set to the document * being created. @@ -86,10 +87,19 @@ public interface DOMImplementation { * namespaceURI is null, or if the * qualifiedName has a prefix that is "xml" and the * namespaceURI is different from " - * http://www.w3.org/XML/1998/namespace" . + * http://www.w3.org/XML/1998/namespace" , or if the DOM + * implementation does not support the "XML" feature but + * a non-null namespace URI was provided, since namespaces were + * defined by XML. *
WRONG_DOCUMENT_ERR: Raised if doctype has already * been used with a different document or was created from a different * implementation. + *
NOT_SUPPORTED_ERR: May be raised by DOM implementations which do + * not support the "XML" feature, if they choose not to support this + * method. Other features introduced in the future, by the DOM WG or + * in extensions defined by other groups, may also demand support for + * this method; please consult the definition of the feature to see if + * it requires this method. * @since DOM Level 2 */ public Document createDocument(String namespaceURI, diff --git a/java/external/src/org/w3c/dom/Document.java b/java/external/src/org/w3c/dom/Document.java index 5eb2cee..79214e0 100644 --- a/java/external/src/org/w3c/dom/Document.java +++ b/java/external/src/org/w3c/dom/Document.java @@ -59,10 +59,10 @@ public interface Document extends Node { * and attached to the element. *
To create an element with a qualified name and namespace URI, use * the createElementNS method. - * @param tagNameThe name of the element type to instantiate. For XML, + * @param tagName The name of the element type to instantiate. For XML, * this is case-sensitive. For HTML, the tagName * parameter may be provided in any case, but it must be mapped to the - * canonical uppercase form by the DOM implementation. + * canonical uppercase form by the DOM implementation. * @return A new Element object with the * nodeName attribute set to tagName, and * localName, prefix, and @@ -75,21 +75,21 @@ public interface Document extends Node { throws DOMException; /** - * Creates an empty DocumentFragment object. + * Creates an empty DocumentFragment object. * @return A new DocumentFragment. */ public DocumentFragment createDocumentFragment(); /** * Creates a Text node given the specified string. - * @param dataThe data for the node. + * @param data The data for the node. * @return The new Text object. */ public Text createTextNode(String data); /** * Creates a Comment node given the specified string. - * @param dataThe data for the node. + * @param data The data for the node. * @return The new Comment object. */ public Comment createComment(String data); @@ -97,7 +97,7 @@ public interface Document extends Node { /** * Creates a CDATASection node whose value is the specified * string. - * @param dataThe data for the CDATASection contents. + * @param data The data for the CDATASection contents. * @return The new CDATASection object. * @exception DOMException * NOT_SUPPORTED_ERR: Raised if this document is an HTML document. @@ -108,8 +108,8 @@ public interface Document extends Node { /** * Creates a ProcessingInstruction node given the specified * name and data strings. - * @param targetThe target part of the processing instruction. - * @param dataThe data for the node. + * @param target The target part of the processing instruction. + * @param data The data for the node. * @return The new ProcessingInstruction object. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified target contains an @@ -126,7 +126,7 @@ public interface Document extends Node { * using the setAttributeNode method. *
To create an attribute with a qualified name and namespace URI, use * the createAttributeNS method. - * @param nameThe name of the attribute. + * @param name The name of the attribute. * @return A new Attr object with the nodeName * attribute set to name, and localName, * prefix, and namespaceURI set to @@ -148,7 +148,7 @@ public interface Document extends Node { * node is also unbound; (its namespaceURI is * null). The DOM Level 2 does not support any mechanism to * resolve namespace prefixes. - * @param nameThe name of the entity to reference. + * @param name The name of the entity to reference. * @return The new EntityReference object. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified name contains an @@ -161,8 +161,8 @@ public interface Document extends Node { /** * Returns a NodeList of all the Elements with a * given tag name in the order in which they are encountered in a - * preorder traversal of the Document tree. - * @param tagnameThe name of the tag to match on. The special value "*" + * preorder traversal of the Document tree. + * @param tagname The name of the tag to match on. The special value "*" * matches all tags. * @return A new NodeList object containing all the matched * Elements. @@ -255,9 +255,9 @@ public interface Document extends Node { * types of nodes inheriting from CharacterData copy their * data and length attributes from those of * the source node. - * - * @param importedNodeThe node to import. - * @param deepIf true, recursively import the subtree under + * + * @param importedNode The node to import. + * @param deep If true, recursively import the subtree under * the specified node; if false, import only the node * itself, as explained above. This has no effect on Attr * , EntityReference, and Notation nodes. @@ -272,28 +272,57 @@ public interface Document extends Node { throws DOMException; /** - * Creates an element of the given qualified name and namespace URI. - * HTML-only DOM implementations do not need to implement this method. - * @param namespaceURIThe namespace URI of the element to create. - * @param qualifiedNameThe qualified name of the element type to + * Creates an element of the given qualified name and namespace URI. + * @param namespaceURI The namespace URI of the element to create. + * @param qualifiedName The qualified name of the element type to * instantiate. * @return A new Element object with the following - * attributes:AttributeValueNode.nodeName - * qualifiedNameNode.namespaceURI - * namespaceURINode.prefixprefix, extracted + * attributes: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
AttributeValue
Node.nodeName + * qualifiedName
Node.namespaceURI + * namespaceURI
Node.prefixprefix, extracted * from qualifiedName, or null if there is - * no prefixNode.localNamelocal name, extracted from - * qualifiedNameElement.tagName - * qualifiedName + * no prefix
Node.localNamelocal name, extracted from + * qualifiedName
Element.tagName + * qualifiedName
* @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified qualified name - * contains an illegal character. + * contains an illegal character, per the XML 1.0 specification . *
NAMESPACE_ERR: Raised if the qualifiedName is - * malformed, if the qualifiedName has a prefix and the + * malformed per the Namespaces in XML specification, if the + * qualifiedName has a prefix and the * namespaceURI is null, or if the * qualifiedName has a prefix that is "xml" and the * namespaceURI is different from " * http://www.w3.org/XML/1998/namespace" . + *
NOT_SUPPORTED_ERR: Always thrown if the current document does not + * support the "XML" feature, since namespaces were + * defined by XML. * @since DOM Level 2 */ public Element createElementNS(String namespaceURI, @@ -301,31 +330,65 @@ public interface Document extends Node { throws DOMException; /** - * Creates an attribute of the given qualified name and namespace URI. - * HTML-only DOM implementations do not need to implement this method. - * @param namespaceURIThe namespace URI of the attribute to create. - * @param qualifiedNameThe qualified name of the attribute to instantiate. + * Creates an attribute of the given qualified name and namespace URI. + * @param namespaceURI The namespace URI of the attribute to create. + * @param qualifiedName The qualified name of the attribute to + * instantiate. * @return A new Attr object with the following attributes: - * AttributeValueNode.nodeNamequalifiedName - * Node.namespaceURInamespaceURI - * Node.prefixprefix, extracted from + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
+ * AttributeValue
Node.nodeNamequalifiedName
+ * Node.namespaceURInamespaceURI
+ * Node.prefixprefix, extracted from * qualifiedName, or null if there is no - * prefixNode.localNamelocal name, extracted from - * qualifiedNameAttr.name - * qualifiedNameNode.nodeValuethe empty - * string + * prefix
Node.localNamelocal name, extracted from + * qualifiedName
Attr.name + * qualifiedName
Node.nodeValuethe empty + * string
* @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified qualified name - * contains an illegal character. + * contains an illegal character, per the XML 1.0 specification . *
NAMESPACE_ERR: Raised if the qualifiedName is - * malformed, if the qualifiedName has a prefix and the + * malformed per the Namespaces in XML specification, if the + * qualifiedName has a prefix and the * namespaceURI is null, if the * qualifiedName has a prefix that is "xml" and the * namespaceURI is different from " * http://www.w3.org/XML/1998/namespace", or if the - * qualifiedName is "xmlns" and the + * qualifiedName, or its prefix, is "xmlns" and the * namespaceURI is different from " * http://www.w3.org/2000/xmlns/". + *
NOT_SUPPORTED_ERR: Always thrown if the current document does not + * support the "XML" feature, since namespaces were + * defined by XML. * @since DOM Level 2 */ public Attr createAttributeNS(String namespaceURI, @@ -336,9 +399,9 @@ public interface Document extends Node { * Returns a NodeList of all the Elements with a * given local name and namespace URI in the order in which they are * encountered in a preorder traversal of the Document tree. - * @param namespaceURIThe namespace URI of the elements to match on. The + * @param namespaceURI The namespace URI of the elements to match on. The * special value "*" matches all namespaces. - * @param localNameThe local name of the elements to match on. The + * @param localName The local name of the elements to match on. The * special value "*" matches all local names. * @return A new NodeList object containing all the matched * Elements. @@ -355,8 +418,8 @@ public interface Document extends Node { * information that says which attributes are of type ID. Attributes * with the name "ID" are not of type ID unless so defined. * Implementations that do not know whether attributes are of type ID or - * not are expected to return null. - * @param elementIdThe unique id value for an element. + * not are expected to return null. + * @param elementId The unique id value for an element. * @return The matching element. * @since DOM Level 2 */ diff --git a/java/external/src/org/w3c/dom/DocumentType.java b/java/external/src/org/w3c/dom/DocumentType.java index 4cdb723..86c312b 100644 --- a/java/external/src/org/w3c/dom/DocumentType.java +++ b/java/external/src/org/w3c/dom/DocumentType.java @@ -68,10 +68,11 @@ public interface DocumentType extends Node { public String getSystemId(); /** - * The internal subset as a string.The actual content returned depends on - * how much information is available to the implementation. This may - * vary depending on various parameters, including the XML processor - * used to build the document. + * The internal subset as a string, or null if there is none. + * This is does not contain the delimiting square brackets.The actual + * content returned depends on how much information is available to the + * implementation. This may vary depending on various parameters, + * including the XML processor used to build the document. * @since DOM Level 2 */ public String getInternalSubset(); diff --git a/java/external/src/org/w3c/dom/Element.java b/java/external/src/org/w3c/dom/Element.java index d0df6ce..614ca87 100644 --- a/java/external/src/org/w3c/dom/Element.java +++ b/java/external/src/org/w3c/dom/Element.java @@ -39,13 +39,13 @@ public interface Element extends Node { * case-preserving in XML, as are all of the operations of the DOM. The * HTML DOM returns the tagName of an HTML element in the * canonical uppercase form, regardless of the case in the source HTML - * document. + * document. */ public String getTagName(); /** * Retrieves an attribute value by name. - * @param nameThe name of the attribute to retrieve. + * @param name The name of the attribute to retrieve. * @return The Attr value as a string, or the empty string * if that attribute does not have a specified or default value. */ @@ -65,8 +65,8 @@ public interface Element extends Node { * it as the value of an attribute. *
To set an attribute with a qualified name and namespace URI, use * the setAttributeNS method. - * @param nameThe name of the attribute to create or alter. - * @param valueValue to set in string form. + * @param name The name of the attribute to create or alter. + * @param value Value to set in string form. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified name contains an * illegal character. @@ -83,7 +83,7 @@ public interface Element extends Node { * and prefix when applicable. *
To remove an attribute by local name and namespace URI, use the * removeAttributeNS method. - * @param nameThe name of the attribute to remove. + * @param name The name of the attribute to remove. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. */ @@ -94,7 +94,7 @@ public interface Element extends Node { * Retrieves an attribute node by name. *
To retrieve an attribute node by qualified name and namespace URI, * use the getAttributeNodeNS method. - * @param nameThe name (nodeName) of the attribute to + * @param name The name (nodeName) of the attribute to * retrieve. * @return The Attr node with the specified name ( * nodeName) or null if there is no such @@ -108,7 +108,7 @@ public interface Element extends Node { * replaced by the new one. *
To add a new attribute node with a qualified name and namespace * URI, use the setAttributeNodeNS method. - * @param newAttrThe Attr node to add to the attribute list. + * @param newAttr The Attr node to add to the attribute list. * @return If the newAttr attribute replaces an existing * attribute, the replaced Attr node is returned, * otherwise null is returned. @@ -129,7 +129,7 @@ public interface Element extends Node { * has a default value it is immediately replaced. The replacing * attribute has the same namespace URI and local name, as well as the * original prefix, when applicable. - * @param oldAttrThe Attr node to remove from the attribute + * @param oldAttr The Attr node to remove from the attribute * list. * @return The Attr node that was removed. * @exception DOMException @@ -144,17 +144,20 @@ public interface Element extends Node { * Returns a NodeList of all descendant Elements * with a given tag name, in the order in which they are encountered in * a preorder traversal of this Element tree. - * @param nameThe name of the tag to match on. The special value "*" + * @param name The name of the tag to match on. The special value "*" * matches all tags. * @return A list of matching Element nodes. */ public NodeList getElementsByTagName(String name); /** - * Retrieves an attribute value by local name and namespace URI. HTML-only - * DOM implementations do not need to implement this method. - * @param namespaceURIThe namespace URI of the attribute to retrieve. - * @param localNameThe local name of the attribute to retrieve. + * Retrieves an attribute value by local name and namespace URI. + *
Documents which do not support the "XML" feature will permit only + * the DOM Level 1 calls for creating/setting elements and attributes. + * Hence, if you specify a non-null namespace URI, these DOMs will never + * find a matching node. + * @param namespaceURI The namespace URI of the attribute to retrieve. + * @param localName The local name of the attribute to retrieve. * @return The Attr value as a string, or the empty string * if that attribute does not have a specified or default value. * @since DOM Level 2 @@ -177,25 +180,28 @@ public interface Element extends Node { * and use setAttributeNodeNS or * setAttributeNode to assign it as the value of an * attribute. - *
HTML-only DOM implementations do not need to implement this method. - * @param namespaceURIThe namespace URI of the attribute to create or + * @param namespaceURI The namespace URI of the attribute to create or * alter. - * @param qualifiedNameThe qualified name of the attribute to create or + * @param qualifiedName The qualified name of the attribute to create or * alter. - * @param valueThe value to set in string form. + * @param value The value to set in string form. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified qualified name - * contains an illegal character. + * contains an illegal character, per the XML 1.0 specification . *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. *
NAMESPACE_ERR: Raised if the qualifiedName is - * malformed, if the qualifiedName has a prefix and the + * malformed per the Namespaces in XML specification, if the + * qualifiedName has a prefix and the * namespaceURI is null, if the * qualifiedName has a prefix that is "xml" and the * namespaceURI is different from " * http://www.w3.org/XML/1998/namespace", or if the - * qualifiedName is "xmlns" and the + * qualifiedName, or its prefix, is "xmlns" and the * namespaceURI is different from " * http://www.w3.org/2000/xmlns/". + *
NOT_SUPPORTED_ERR: Always thrown if the current document does not + * support the "XML" feature, since namespaces were + * defined by XML. * @since DOM Level 2 */ public void setAttributeNS(String namespaceURI, @@ -208,9 +214,12 @@ public interface Element extends Node { * attribute has a default value it is immediately replaced. The * replacing attribute has the same namespace URI and local name, as * well as the original prefix. - *
HTML-only DOM implementations do not need to implement this method. - * @param namespaceURIThe namespace URI of the attribute to remove. - * @param localNameThe local name of the attribute to remove. + *
Documents which do not support the "XML" feature will permit only + * the DOM Level 1 calls for creating/setting elements and attributes. + * Hence, if you specify a non-null namespace URI, these DOMs will never + * find a matching node. + * @param namespaceURI The namespace URI of the attribute to remove. + * @param localName The local name of the attribute to remove. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. * @since DOM Level 2 @@ -220,10 +229,13 @@ public interface Element extends Node { throws DOMException; /** - * Retrieves an Attr node by local name and namespace URI. - * HTML-only DOM implementations do not need to implement this method. - * @param namespaceURIThe namespace URI of the attribute to retrieve. - * @param localNameThe local name of the attribute to retrieve. + * Retrieves an Attr node by local name and namespace URI. + *
Documents which do not support the "XML" feature will permit only + * the DOM Level 1 calls for creating/setting elements and attributes. + * Hence, if you specify a non-null namespace URI, these DOMs will never + * find a matching node. + * @param namespaceURI The namespace URI of the attribute to retrieve. + * @param localName The local name of the attribute to retrieve. * @return The Attr node with the specified attribute local * name and namespace URI or null if there is no such * attribute. @@ -236,8 +248,7 @@ public interface Element extends Node { * Adds a new attribute. If an attribute with that local name and that * namespace URI is already present in the element, it is replaced by * the new one. - *
HTML-only DOM implementations do not need to implement this method. - * @param newAttrThe Attr node to add to the attribute list. + * @param newAttr The Attr node to add to the attribute list. * @return If the newAttr attribute replaces an existing * attribute with the same local name and namespace URI, the replaced * Attr node is returned, otherwise null is @@ -250,6 +261,9 @@ public interface Element extends Node { * attribute of another Element object. The DOM user must * explicitly clone Attr nodes to re-use them in other * elements. + *
NOT_SUPPORTED_ERR: Always thrown if the current document does not + * support the "XML" feature, since namespaces were + * defined by XML. * @since DOM Level 2 */ public Attr setAttributeNodeNS(Attr newAttr) @@ -260,10 +274,13 @@ public interface Element extends Node { * Elements with a given local name and namespace URI in * the order in which they are encountered in a preorder traversal of * this Element tree. - *
HTML-only DOM implementations do not need to implement this method. - * @param namespaceURIThe namespace URI of the elements to match on. The + *
Documents which do not support the "XML" feature will permit only + * the DOM Level 1 calls for creating/setting elements and attributes. + * Hence, if you specify a non-null namespace URI, these DOMs will never + * find a matching node. + * @param namespaceURI The namespace URI of the elements to match on. The * special value "*" matches all namespaces. - * @param localNameThe local name of the elements to match on. The + * @param localName The local name of the elements to match on. The * special value "*" matches all local names. * @return A new NodeList object containing all the matched * Elements. @@ -276,7 +293,7 @@ public interface Element extends Node { * Returns true when an attribute with a given name is * specified on this element or has a default value, false * otherwise. - * @param nameThe name of the attribute to look for. + * @param name The name of the attribute to look for. * @return true if an attribute with the given name is * specified on this element or has a default value, false * otherwise. @@ -287,10 +304,13 @@ public interface Element extends Node { /** * Returns true when an attribute with a given local name and * namespace URI is specified on this element or has a default value, - * false otherwise. HTML-only DOM implementations do not - * need to implement this method. - * @param namespaceURIThe namespace URI of the attribute to look for. - * @param localNameThe local name of the attribute to look for. + * false otherwise. + *
Documents which do not support the "XML" feature will permit only + * the DOM Level 1 calls for creating/setting elements and attributes. + * Hence, if you specify a non-null namespace URI, these DOMs will never + * find a matching node. + * @param namespaceURI The namespace URI of the attribute to look for. + * @param localName The local name of the attribute to look for. * @return true if an attribute with the given local name * and namespace URI is specified or has a default value on this * element, false otherwise. diff --git a/java/external/src/org/w3c/dom/Entity.java b/java/external/src/org/w3c/dom/Entity.java index ecbf6a9..11bd0df 100644 --- a/java/external/src/org/w3c/dom/Entity.java +++ b/java/external/src/org/w3c/dom/Entity.java @@ -61,7 +61,7 @@ public interface Entity extends Node { /** * For unparsed entities, the name of the notation for the entity. For - * parsed entities, this is null. + * parsed entities, this is null. */ public String getNotationName(); diff --git a/java/external/src/org/w3c/dom/NamedNodeMap.java b/java/external/src/org/w3c/dom/NamedNodeMap.java index 6ab713c..8437366 100644 --- a/java/external/src/org/w3c/dom/NamedNodeMap.java +++ b/java/external/src/org/w3c/dom/NamedNodeMap.java @@ -27,7 +27,7 @@ package org.w3c.dom; public interface NamedNodeMap { /** * Retrieves a node specified by name. - * @param nameThe nodeName of a node to retrieve. + * @param name The nodeName of a node to retrieve. * @return A Node (of any type) with the specified * nodeName, or null if it does not identify * any node in this map. @@ -43,7 +43,7 @@ public interface NamedNodeMap { * (those that have a "special" string value) cannot be stored as the * names would clash. This is seen as preferable to allowing nodes to be * aliased. - * @param argA node to store in this map. The node will later be + * @param arg A node to store in this map. The node will later be * accessible using the value of its nodeName attribute. * @return If the new Node replaces an existing node the * replaced Node is returned, otherwise null @@ -56,6 +56,11 @@ public interface NamedNodeMap { * Attr that is already an attribute of another * Element object. The DOM user must explicitly clone * Attr nodes to re-use them in other elements. + *
HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node + * doesn't belong in this NamedNodeMap. Examples would include trying + * to insert something other than an Attr node into an Element's map + * of attributes, or a non-Entity node into the DocumentType's map of + * Entities. */ public Node setNamedItem(Node arg) throws DOMException; @@ -66,7 +71,7 @@ public interface NamedNodeMap { * default value, an attribute immediately appears containing the * default value as well as the corresponding namespace URI, local name, * and prefix when applicable. - * @param nameThe nodeName of the node to remove. + * @param name The nodeName of the node to remove. * @return The node removed from this map if a node with such a name * exists. * @exception DOMException @@ -81,7 +86,7 @@ public interface NamedNodeMap { * Returns the indexth item in the map. If index * is greater than or equal to the number of nodes in this map, this * returns null. - * @param indexIndex into this map. + * @param index Index into this map. * @return The node at the indexth position in the map, or * null if that is not a valid index. */ @@ -89,15 +94,18 @@ public interface NamedNodeMap { /** * The number of nodes in this map. The range of valid child node indices - * is 0 to length-1 inclusive. + * is 0 to length-1 inclusive. */ public int getLength(); /** - * Retrieves a node specified by local name and namespace URI. HTML-only - * DOM implementations do not need to implement this method. - * @param namespaceURIThe namespace URI of the node to retrieve. - * @param localNameThe local name of the node to retrieve. + * Retrieves a node specified by local name and namespace URI. + *
Documents which do not support the "XML" feature will permit only + * the DOM Level 1 calls for creating/setting elements and attributes. + * Hence, if you specify a non-null namespace URI, these DOMs will never + * find a matching node. + * @param namespaceURI The namespace URI of the node to retrieve. + * @param localName The local name of the node to retrieve. * @return A Node (of any type) with the specified local * name and namespace URI, or null if they do not * identify any node in this map. @@ -111,8 +119,7 @@ public interface NamedNodeMap { * localName. If a node with that namespace URI and that * local name is already present in this map, it is replaced by the new * one. - *
HTML-only DOM implementations do not need to implement this method. - * @param argA node to store in this map. The node will later be + * @param arg A node to store in this map. The node will later be * accessible using the value of its namespaceURI and * localName attributes. * @return If the new Node replaces an existing node the @@ -126,6 +133,14 @@ public interface NamedNodeMap { * Attr that is already an attribute of another * Element object. The DOM user must explicitly clone * Attr nodes to re-use them in other elements. + *
HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node + * doesn't belong in this NamedNodeMap. Examples would include trying + * to insert something other than an Attr node into an Element's map + * of attributes, or a non-Entity node into the DocumentType's map of + * Entities. + *
NOT_SUPPORTED_ERR: Always thrown if the current document does not + * support the "XML" feature, since namespaces were + * defined by XML. * @since DOM Level 2 */ public Node setNamedItemNS(Node arg) @@ -138,9 +153,12 @@ public interface NamedNodeMap { * attribute of the Node interface. If so, an attribute * immediately appears containing the default value as well as the * corresponding namespace URI, local name, and prefix when applicable. - *
HTML-only DOM implementations do not need to implement this method. - * @param namespaceURIThe namespace URI of the node to remove. - * @param localNameThe local name of the node to remove. + *
Documents which do not support the "XML" feature will permit only + * the DOM Level 1 calls for creating/setting elements and attributes. + * Hence, if you specify a non-null namespace URI, these DOMs will never + * find a matching node. + * @param namespaceURI The namespace URI of the node to remove. + * @param localName The local name of the node to remove. * @return The node removed from this map if a node with such a local * name and namespace URI exists. * @exception DOMException diff --git a/java/external/src/org/w3c/dom/Node.java b/java/external/src/org/w3c/dom/Node.java index 1567efa..56ed30a 100644 --- a/java/external/src/org/w3c/dom/Node.java +++ b/java/external/src/org/w3c/dom/Node.java @@ -29,6 +29,97 @@ package org.w3c.dom; * ), this returns null. Note that the specialized interfaces * may contain additional and more convenient mechanisms to get and set the * relevant information. + *

The values of nodeName, + * nodeValue, and attributes vary according to the + * node type as follows: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
InterfacenodeNamenodeValueattributes
Attrname of + * attributevalue of attributenull
CDATASection"#cdata-section" + * content of the CDATA Sectionnull
Comment"#comment"content of + * the commentnull
Document"#document"nullnull
DocumentFragment + * "#document-fragment"nullnull
DocumentTypedocument type name + * nullnull
Elementtag namenullNamedNodeMap
Entityentity namenullnull
+ * EntityReferencename of entity referencednullnull
Notationnotation namenull + * null
ProcessingInstructiontargetentire content excluding the targetnull
Text + * "#text"content of the text nodenull
*

See also the Document Object Model (DOM) Level 2 Core Specification. */ public interface Node { @@ -83,7 +174,7 @@ public interface Node { public static final short NOTATION_NODE = 12; /** - * The name of this node, depending on its type; see the table above. + * The name of this node, depending on its type; see the table above. */ public String getNodeName(); @@ -99,6 +190,16 @@ public interface Node { */ public String getNodeValue() throws DOMException; + /** + * The value of this node, depending on its type; see the table above. + * When it is defined to be null, setting it has no effect. + * @exception DOMException + * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly. + * @exception DOMException + * DOMSTRING_SIZE_ERR: Raised when it would return more characters than + * fit in a DOMString variable on the implementation + * platform. + */ public void setNodeValue(String nodeValue) throws DOMException; @@ -150,7 +251,7 @@ public interface Node { /** * A NamedNodeMap containing the attributes of this node (if - * it is an Element) or null otherwise. + * it is an Element) or null otherwise. */ public NamedNodeMap getAttributes(); @@ -172,14 +273,15 @@ public interface Node { * all of its children are inserted, in the same order, before * refChild. If the newChild is already in the * tree, it is first removed. - * @param newChildThe node to insert. - * @param refChildThe reference node, i.e., the node before which the new - * node must be inserted. + * @param newChild The node to insert. + * @param refChild The reference node, i.e., the node before which the + * new node must be inserted. * @return The node being inserted. * @exception DOMException * HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not * allow children of the type of the newChild node, or if - * the node to insert is one of this node's ancestors. + * the node to insert is one of this node's ancestors or this node + * itself. *
WRONG_DOCUMENT_ERR: Raised if newChild was created * from a different document than the one that created this node. *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or @@ -199,13 +301,14 @@ public interface Node { * DocumentFragment children, which are inserted in the * same order. If the newChild is already in the tree, it * is first removed. - * @param newChildThe new node to put in the child list. - * @param oldChildThe node being replaced in the list. + * @param newChild The new node to put in the child list. + * @param oldChild The node being replaced in the list. * @return The node replaced. * @exception DOMException * HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not * allow children of the type of the newChild node, or if - * the node to put in is one of this node's ancestors. + * the node to put in is one of this node's ancestors or this node + * itself. *
WRONG_DOCUMENT_ERR: Raised if newChild was created * from a different document than the one that created this node. *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of @@ -220,7 +323,7 @@ public interface Node { /** * Removes the child node indicated by oldChild from the list * of children, and returns it. - * @param oldChildThe node being removed. + * @param oldChild The node being removed. * @return The node removed. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. @@ -234,24 +337,26 @@ public interface Node { * Adds the node newChild to the end of the list of children * of this node. If the newChild is already in the tree, it * is first removed. - * @param newChildThe node to add.If it is a DocumentFragment - * object, the entire contents of the document fragment are moved - * into the child list of this node + * @param newChild The node to add.If it is a + * DocumentFragment object, the entire contents of the + * document fragment are moved into the child list of this node * @return The node added. * @exception DOMException * HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not * allow children of the type of the newChild node, or if - * the node to append is one of this node's ancestors. + * the node to append is one of this node's ancestors or this node + * itself. *
WRONG_DOCUMENT_ERR: Raised if newChild was created * from a different document than the one that created this node. - *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. + *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or + * if the previous parent of the node being inserted is readonly. */ public Node appendChild(Node newChild) throws DOMException; /** * Returns whether this node has any children. - * @return true if this node has any children, + * @return true if this node has any children, * false otherwise. */ public boolean hasChildNodes(); @@ -275,9 +380,9 @@ public interface Node { * specified. And, cloning Document, * DocumentType, Entity, and * Notation nodes is implementation dependent. - * @param deepIf true, recursively clone the subtree under + * @param deep If true, recursively clone the subtree under * the specified node; if false, clone only the node - * itself (and its attributes, if it is an Element). + * itself (and its attributes, if it is an Element). * @return The duplicate node. */ public Node cloneNode(boolean deep); @@ -303,10 +408,10 @@ public interface Node { /** * Tests whether the DOM implementation implements a specific feature and * that feature is supported by this node. - * @param featureThe name of the feature to test. This is the same name + * @param feature The name of the feature to test. This is the same name * which can be passed to the method hasFeature on * DOMImplementation. - * @param versionThis is the version number of the feature to test. In + * @param version This is the version number of the feature to test. In * Level 2, version 1, this is the string "2.0". If the version is not * specified, supporting any version of the feature will cause the * method to return true. @@ -352,20 +457,51 @@ public interface Node { * Document interface, this is always null. * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified prefix contains an - * illegal character. + * illegal character, per the XML 1.0 specification . *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. *
NAMESPACE_ERR: Raised if the specified prefix is - * malformed, if the namespaceURI of this node is - * null, if the specified prefix is "xml" and the - * namespaceURI of this node is different from " - * http://www.w3.org/XML/1998/namespace", if this node is an attribute - * and the specified prefix is "xmlns" and the - * namespaceURI of this node is different from " + * malformed per the Namespaces in XML specification, if the + * namespaceURI of this node is null, if the + * specified prefix is "xml" and the namespaceURI of this + * node is different from "http://www.w3.org/XML/1998/namespace", if + * this node is an attribute and the specified prefix is "xmlns" and + * the namespaceURI of this node is different from " * http://www.w3.org/2000/xmlns/", or if this node is an attribute and * the qualifiedName of this node is "xmlns" . * @since DOM Level 2 */ public String getPrefix(); + /** + * The namespace prefix of this node, or null if it is + * unspecified. + *
Note that setting this attribute, when permitted, changes the + * nodeName attribute, which holds the qualified name, as + * well as the tagName and name attributes of + * the Element and Attr interfaces, when + * applicable. + *
Note also that changing the prefix of an attribute that is known to + * have a default value, does not make a new attribute with the default + * value and the original prefix appear, since the + * namespaceURI and localName do not change. + *
For nodes of any type other than ELEMENT_NODE and + * ATTRIBUTE_NODE and nodes created with a DOM Level 1 + * method, such as createElement from the + * Document interface, this is always null. + * @exception DOMException + * INVALID_CHARACTER_ERR: Raised if the specified prefix contains an + * illegal character, per the XML 1.0 specification . + *
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. + *
NAMESPACE_ERR: Raised if the specified prefix is + * malformed per the Namespaces in XML specification, if the + * namespaceURI of this node is null, if the + * specified prefix is "xml" and the namespaceURI of this + * node is different from "http://www.w3.org/XML/1998/namespace", if + * this node is an attribute and the specified prefix is "xmlns" and + * the namespaceURI of this node is different from " + * http://www.w3.org/2000/xmlns/", or if this node is an attribute and + * the qualifiedName of this node is "xmlns" . + * @since DOM Level 2 + */ public void setPrefix(String prefix) throws DOMException; diff --git a/java/external/src/org/w3c/dom/NodeList.java b/java/external/src/org/w3c/dom/NodeList.java index 4f3ec9a..a90b4fd 100644 --- a/java/external/src/org/w3c/dom/NodeList.java +++ b/java/external/src/org/w3c/dom/NodeList.java @@ -25,7 +25,7 @@ public interface NodeList { * Returns the indexth item in the collection. If * index is greater than or equal to the number of nodes in * the list, this returns null. - * @param indexIndex into the collection. + * @param index Index into the collection. * @return The node at the indexth position in the * NodeList, or null if that is not a valid * index. @@ -34,7 +34,7 @@ public interface NodeList { /** * The number of nodes in the list. The range of valid child node indices - * is 0 to length-1 inclusive. + * is 0 to length-1 inclusive. */ public int getLength(); diff --git a/java/external/src/org/w3c/dom/ProcessingInstruction.java b/java/external/src/org/w3c/dom/ProcessingInstruction.java index f84fdf2..fe447b5 100644 --- a/java/external/src/org/w3c/dom/ProcessingInstruction.java +++ b/java/external/src/org/w3c/dom/ProcessingInstruction.java @@ -34,6 +34,13 @@ public interface ProcessingInstruction extends Node { * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly. */ public String getData(); + /** + * The content of this processing instruction. This is from the first non + * white space character after the target to the character immediately + * preceding the ?>. + * @exception DOMException + * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly. + */ public void setData(String data) throws DOMException; diff --git a/java/external/src/org/w3c/dom/Text.java b/java/external/src/org/w3c/dom/Text.java index e415e80..842a973 100644 --- a/java/external/src/org/w3c/dom/Text.java +++ b/java/external/src/org/w3c/dom/Text.java @@ -42,7 +42,7 @@ public interface Text extends CharacterData { * node had a parent node, the new node is inserted as the next sibling * of the original node. When the offset is equal to the * length of this node, the new node has no data. - * @param offsetThe 16-bit unit offset at which to split, starting from + * @param offset The 16-bit unit offset at which to split, starting from * 0. * @return The new node, of the same type as this node. * @exception DOMException