diff --git a/src/org/apache/xerces/dom/CoreDocumentImpl.java b/src/org/apache/xerces/dom/CoreDocumentImpl.java index 870e1c5da..742ce011c 100644 --- a/src/org/apache/xerces/dom/CoreDocumentImpl.java +++ b/src/org/apache/xerces/dom/CoreDocumentImpl.java @@ -91,7 +91,7 @@ public class CoreDocumentImpl extends ParentNode implements Document { - /**TODO:: + /*TODO:: * 1. Change XML11Char method names similar to XMLChar. That will prevent lot * of dirty version checking code. * @@ -292,16 +292,32 @@ public CoreDocumentImpl(DocumentType doctype, boolean grammarAccess) { // even though ownerDocument refers to this in this implementation // the DOM Level 2 spec says it must be null, so make it appear so + /** + * Find the Document that this Node belongs to + * + * @return CoreDocumentImpl will always return null + */ + @Override final public Document getOwnerDocument() { return null; } - /** Returns the node type. */ + /** + * Returns the node type. + * + * @return CoreDocumentImpl will always return {@link Node#DOCUMENT_NODE} + */ + @Override public short getNodeType() { return Node.DOCUMENT_NODE; } - /** Returns the node name. */ + /** + * Returns the node name. + * + * @return CoreDocumentImpl will always return "#document" + */ + @Override public String getNodeName() { return "#document"; } @@ -315,6 +331,7 @@ public String getNodeName() { * @param deep boolean, iff true replicate children * @return a clone of this {@link org.w3c.dom.Node} */ + @Override public Node cloneNode(boolean deep) { CoreDocumentImpl newdoc = new CoreDocumentImpl(); @@ -327,8 +344,11 @@ public Node cloneNode(boolean deep) { /** - * internal method to share code with subclass - **/ + * internal method to share code with subclass. + * + * @param newdoc a new CoreDocumentImpl instance + * @param deep boolean, iff true replicate children + */ protected void cloneNode(CoreDocumentImpl newdoc, boolean deep) { // clone the children by importing them @@ -366,7 +386,7 @@ protected void cloneNode(CoreDocumentImpl newdoc, boolean deep) { /** * Since a Document may contain at most one top-level Element child, - * and at most one DocumentType declaraction, we need to subclass our + * and at most one DocumentType declaration, we need to subclass our * add-children methods to implement this constraint. * Since appendChild() is implemented as insertBefore(,null), * altering the latter fixes both. @@ -378,6 +398,7 @@ protected void cloneNode(CoreDocumentImpl newdoc, boolean deep) { * REVISIT: According to the spec it is not allowed to alter neither the * document element nor the document type in any way */ + @Override public Node insertBefore(Node newChild, Node refChild) throws DOMException { @@ -419,6 +440,7 @@ else if (type == Node.DOCUMENT_TYPE_NODE) { * REVISIT: According to the spec it is not allowed to alter neither the * document element nor the document type in any way */ + @Override public Node removeChild(Node oldChild) throws DOMException { super.removeChild(oldChild); @@ -443,6 +465,7 @@ else if (type == Node.DOCUMENT_TYPE_NODE) { * REVISIT: According to the spec it is not allowed to alter neither the * document element nor the document type in any way */ + @Override public Node replaceChild(Node newChild, Node oldChild) throws DOMException { @@ -479,6 +502,7 @@ else if (type == Node.DOCUMENT_TYPE_NODE) { * Get Node text content * @since DOM Level 3 */ + @Override public String getTextContent() throws DOMException { return null; } @@ -487,6 +511,7 @@ public String getTextContent() throws DOMException { * Set Node text content * @since DOM Level 3 */ + @Override public void setTextContent(String textContent) throws DOMException { // no-op @@ -495,6 +520,7 @@ public void setTextContent(String textContent) /** * @since DOM Level 3 */ + @Override public Object getFeature(String feature, String version) { boolean anyVersion = version == null || version.length() == 0; @@ -553,6 +579,7 @@ public Object getFeature(String feature, String version) { * * @throws DOMException INVALID_NAME_ERR if the attribute name is not acceptable. */ + @Override public Attr createAttribute(String name) throws DOMException { @@ -577,16 +604,18 @@ public Attr createAttribute(String name) * @throws DOMException NOT_SUPPORTED_ERR for HTML documents. * (HTML not yet implemented) */ + @Override public CDATASection createCDATASection(String data) throws DOMException { return new CDATASectionImpl(this, data); } /** - * Factory method; creates a Comment having this Document as its - * OwnerDoc. + * Factory method; creates a Comment having this Document as its OwnerDoc. * - * @param data The initial contents of the Comment. */ + * @param data the initial contents of the Comment + */ + @Override public Comment createComment(String data) { return new CommentImpl(this, data); } @@ -595,6 +624,7 @@ public Comment createComment(String data) { * Factory method; creates a DocumentFragment having this Document * as its OwnerDoc. */ + @Override public DocumentFragment createDocumentFragment() { return new DocumentFragmentImpl(this); } @@ -610,6 +640,7 @@ public DocumentFragment createDocumentFragment() { * * @throws DOMException INVALID_NAME_ERR if the tag name is not acceptable */ + @Override public Element createElement(String tagName) throws DOMException { @@ -631,6 +662,7 @@ public Element createElement(String tagName) * nonstandard entities are not permitted. (HTML not yet * implemented.) */ + @Override public EntityReference createEntityReference(String name) throws DOMException { @@ -654,8 +686,8 @@ public EntityReference createEntityReference(String name) * @throws DOMException NOT_SUPPORTED_ERR for HTML documents. * (HTML not yet implemented.) */ - public ProcessingInstruction createProcessingInstruction(String target, - String data) + @Override + public ProcessingInstruction createProcessingInstruction(String target, String data) throws DOMException { if (errorChecking && !isXMLName(target,xml11Version)) { @@ -672,6 +704,7 @@ public ProcessingInstruction createProcessingInstruction(String target, * * @param data The initial contents of the Text. */ + @Override public Text createTextNode(String data) { return new TextImpl(this, data); } @@ -683,6 +716,7 @@ public Text createTextNode(String data) { * For HTML documents, and XML documents which don't specify a DTD, * it will be null. */ + @Override public DocumentType getDoctype() { if (needsSyncChildren()) { synchronizeChildren(); @@ -702,6 +736,7 @@ public DocumentType getDoctype() { * * @return the root document element */ + @Override public Element getDocumentElement() { if (needsSyncChildren()) { synchronizeChildren(); @@ -718,6 +753,7 @@ public Element getDocumentElement() { * * @see DeepNodeListImpl */ + @Override public NodeList getElementsByTagName(String tagname) { return new DeepNodeListImpl(this,tagname); } @@ -728,6 +764,7 @@ public NodeList getElementsByTagName(String tagname) { * using DOMs retrieved from several different sources, potentially * with different underlying representations. */ + @Override public DOMImplementation getImplementation() { // Currently implemented as a singleton, since it's hardcoded // information anyway. @@ -745,20 +782,19 @@ public DOMImplementation getImplementation() { * upon operations. Turning off error checking only affects * the following DOM checks: * *

* Turning off error checking does not turn off the * following checks: *

+ * + * @param check set to true to enable error checking */ - public void setErrorChecking(boolean check) { errorChecking = check; } @@ -766,12 +802,15 @@ public void setErrorChecking(boolean check) { /* * DOM Level 3 WD - Experimental. */ + @Override public void setStrictErrorChecking(boolean check) { errorChecking = check; } /** * Returns true if the DOM implementation performs error checking. + * + * @return true if the DOM implementation performs error checking */ public boolean getErrorChecking() { return errorChecking; @@ -780,6 +819,7 @@ public boolean getErrorChecking() { /* * DOM Level 3 WD - Experimental. */ + @Override public boolean getStrictErrorChecking() { return errorChecking; } @@ -788,12 +828,15 @@ public boolean getStrictErrorChecking() { /** * DOM Level 3 CR - Experimental. (Was getActualEncoding) * - * An attribute specifying the encoding used for this document + *

An attribute specifying the encoding used for this document * at the time of the parsing. This is null when * it is not known, such as when the Document was - * created in memory. + * created in memory.

+ * + * @return the input encoding * @since DOM Level 3 */ + @Override public String getInputEncoding() { return actualEncoding; } @@ -802,10 +845,12 @@ public String getInputEncoding() { * DOM Internal * (Was a DOM L3 Core WD public interface method setActualEncoding ) * - * An attribute specifying the actual encoding of this document. This is - * null otherwise. - *
This attribute represents the property [character encoding scheme] - * defined in . + *

An attribute specifying the actual encoding of this document. This is + * null otherwise.

+ *

This attribute represents the property [character encoding scheme] + * defined in .

+ * + * @param value the input encoding */ public void setInputEncoding(String value) { actualEncoding = value; @@ -815,8 +860,10 @@ public void setInputEncoding(String value) { * DOM Internal * (Was a DOM L3 Core WD public interface method setXMLEncoding ) * - * An attribute specifying, as part of the XML declaration, - * the encoding of this document. This is null when unspecified. + *

An attribute specifying, as part of the XML declaration, + * the encoding of this document. This is null when unspecified.

+ * + * @param value the encoding of this document */ public void setXmlEncoding(String value) { encoding = value; @@ -825,7 +872,9 @@ public void setXmlEncoding(String value) { /** * @deprecated This method is internal and only exists for * compatibility with older applications. New applications - * should never call this method. + * should never call this method. Instead call {@link #setXmlEncoding(String)} + * + * @param value the encoding of this document */ @Deprecated public void setEncoding(String value) { @@ -835,7 +884,10 @@ public void setEncoding(String value) { /** * DOM Level 3 WD - Experimental. * The encoding of this document (part of XML Declaration) + * + * @return the encoding of this document */ + @Override public String getXmlEncoding() { return encoding; } @@ -843,7 +895,9 @@ public String getXmlEncoding() { /** * @deprecated This method is internal and only exists for * compatibility with older applications. New applications - * should never call this method. + * should never call this method. Instead call {@link #getXmlEncoding()} + * + * @return the encoding of this document */ @Deprecated public String getEncoding() { @@ -854,7 +908,11 @@ public String getEncoding() { * DOM Level 3 CR - Experimental. * version - An attribute specifying, as part of the XML declaration, * the version number of this document. + * + * @param value the version number of this document + * (should be either 1.0 or 1.1) */ + @Override public void setXmlVersion(String value) { if(value.equals("1.0") || value.equals("1.1")){ //we need to change the flag value only -- @@ -885,7 +943,9 @@ public void setXmlVersion(String value) { /** * @deprecated This method is internal and only exists for * compatibility with older applications. New applications - * should never call this method. + * should never call this method. Instead call {@link #setXmlVersion(String)} + * + * @param value the version number of this document */ @Deprecated public void setVersion(String value) { @@ -895,7 +955,10 @@ public void setVersion(String value) { /** * DOM Level 3 WD - Experimental. * The version of this document (part of XML Declaration) + * + * @return the version of this document, defaults to 1.0 */ + @Override public String getXmlVersion() { return (version == null)?"1.0":version; } @@ -903,7 +966,9 @@ public String getXmlVersion() { /** * @deprecated This method is internal and only exists for * compatibility with older applications. New applications - * should never call this method. + * should never call this method. Instead call {@link #getXmlVersion()} + * + * @return the version of this document, defaults to 1.0 */ @Deprecated public String getVersion() { @@ -913,13 +978,16 @@ public String getVersion() { /** * DOM Level 3 CR - Experimental. * - * Xmlstandalone - An attribute specifying, as part of the XML declaration, - * whether this document is standalone - * @exception DOMException - * NOT_SUPPORTED_ERR: Raised if this document does not support the - * "XML" feature. + *

Xml Standalone - An attribute specifying, as part of the XML declaration, + * whether this document is standalone

+ * + * @param value set to true to specify that this document is standalone + * @throws DOMException NOT_SUPPORTED_ERR: Raised if this document does not + * support the "XML" feature. + * * @since DOM Level 3 */ + @Override public void setXmlStandalone(boolean value) throws DOMException { standalone = value; @@ -928,7 +996,9 @@ public void setXmlStandalone(boolean value) /** * @deprecated This method is internal and only exists for * compatibility with older applications. New applications - * should never call this method. + * should never call this method. Instead call {@link #setXmlStandalone(boolean)} + * + * @param value set to true to specify that this document is standalone */ @Deprecated public void setStandalone(boolean value) { @@ -939,7 +1009,10 @@ public void setStandalone(boolean value) { * DOM Level 3 WD - Experimental. * standalone that specifies whether this document is standalone * (part of XML Declaration) + * + * @return true if this document is standalone */ + @Override public boolean getXmlStandalone() { return standalone; } @@ -947,7 +1020,9 @@ public boolean getXmlStandalone() { /** * @deprecated This method is internal and only exists for * compatibility with older applications. New applications - * should never call this method. + * should never call this method. Instead call {@link #getXmlStandalone()} + * + * @return true if this document is standalone */ @Deprecated public boolean getStandalone() { @@ -957,11 +1032,12 @@ public boolean getStandalone() { /** * DOM Level 3 WD - Experimental. * The location of the document or null if undefined. - *
Beware that when the Document supports the feature + *

Beware that when the Document supports the feature * "HTML" , the href attribute of the HTML BASE element takes precedence * over this attribute. * @since DOM Level 3 */ + @Override public String getDocumentURI(){ return fDocumentURI; } @@ -994,6 +1070,7 @@ protected boolean canRenameElements(String newNamespaceURI, String newNodeName, * @param name the new noe name * @return the renamed node. This is either the specified node or the new node that was created to replace the specified node. */ + @Override public Node renameNode(Node n,String namespaceURI,String name) throws DOMException{ @@ -1148,6 +1225,7 @@ private ElementImpl replaceRenameElement(ElementImpl el, String namespaceURI, St * DOM Level 3 WD - Experimental * Normalize document. */ + @Override public void normalizeDocument(){ // No need to normalize if already normalized. if (isNormalized() && !isNormalizeDocRequired()) { @@ -1179,10 +1257,11 @@ public void normalizeDocument(){ /** * DOM Level 3 CR - Experimental * - * The configuration used when Document.normalizeDocument is - * invoked. + *

The configuration used when {@link Document#normalizeDocument()} is invoked.

+ * * @since DOM Level 3 */ + @Override public DOMConfiguration getDomConfig(){ if (fConfiguration == null) { fConfiguration = new DOMConfigurationImpl(); @@ -1199,6 +1278,7 @@ public DOMConfiguration getDomConfig(){ * @return The absolute base URI of this node or null. * @since DOM Level 3 */ + @Override public String getBaseURI() { if (fDocumentURI != null && fDocumentURI.length() != 0 ) {// attribute value is always empty string try { @@ -1215,6 +1295,7 @@ public String getBaseURI() { /** * DOM Level 3 WD - Experimental. */ + @Override public void setDocumentURI(String documentURI){ fDocumentURI = documentURI; } @@ -1225,17 +1306,20 @@ public void setDocumentURI(String documentURI){ // /** * DOM Level 3 WD - Experimental. - * Indicates whether the method load should be synchronous or + *

Indicates whether the method load should be synchronous or * asynchronous. When the async attribute is set to true * the load method returns control to the caller before the document has * completed loading. The default value of this property is - * false. - *
Setting the value of this attribute might throw NOT_SUPPORTED_ERR + * false.

+ *

Setting the value of this attribute might throw NOT_SUPPORTED_ERR * if the implementation doesn't support the mode the attribute is being * set to. Should the DOM spec define the default value of this * property? What if implementing both async and sync IO is impractical * in some systems? 2001-09-14. default is false but we - * need to check with Mozilla and IE. + * need to check with Mozilla and IE.

+ * + * @return true if the {@link #load(String)} method should be asynchronous, defaults to false. Note that + * this implementation will always return false */ public boolean getAsync() { return false; @@ -1243,17 +1327,19 @@ public boolean getAsync() { /** * DOM Level 3 WD - Experimental. - * Indicates whether the method load should be synchronous or + *

Indicates whether the method load should be synchronous or * asynchronous. When the async attribute is set to true * the load method returns control to the caller before the document has * completed loading. The default value of this property is - * false. - *
Setting the value of this attribute might throw NOT_SUPPORTED_ERR + * false.

+ *

Setting the value of this attribute might throw NOT_SUPPORTED_ERR * if the implementation doesn't support the mode the attribute is being * set to. Should the DOM spec define the default value of this * property? What if implementing both async and sync IO is impractical * in some systems? 2001-09-14. default is false but we - * need to check with Mozilla and IE. + * need to check with Mozilla and IE.

+ * + * @param async set to true for {@link #load(String)} to be asynchronous, defaults to false */ public void setAsync(boolean async) { if (async) { @@ -1263,10 +1349,10 @@ public void setAsync(boolean async) { } /** * DOM Level 3 WD - Experimental. - * If the document is currently being loaded as a result of the method + *

If the document is currently being loaded as a result of the method * load being invoked the loading and parsing is * immediately aborted. The possibly partial result of parsing the - * document is discarded and the document is cleared. + * document is discarded and the document is cleared.

*/ public void abort() { } @@ -1274,7 +1360,7 @@ public void abort() { /** * DOM Level 3 WD - Experimental. * - * Replaces the content of the document with the result of parsing the + *

Replaces the content of the document with the result of parsing the * given URI. Invoking this method will either block the caller or * return to the caller immediately depending on the value of the async * attribute. Once the document is fully loaded a "load" event (as @@ -1284,20 +1370,22 @@ public void abort() { * occurs, an implementation dependent "error" event will be dispatched * on the document. If this method is called on a document that is * currently loading, the current load is interrupted and the new URI - * load is initiated. - *
When invoking this method the parameters used in the + * load is initiated.

+ *

When invoking this method the parameters used in the * DOMParser interface are assumed to have their default * values with the exception that the parameters "entities" * , "normalize-characters", * "check-character-normalization" are set to - * "false". - *
The result of a call to this method is the same the result of a + * "false".

+ *

The result of a call to this method is the same the result of a * call to DOMParser.parseWithContext with an input stream * referencing the URI that was passed to this call, the document as the - * context node, and the action ACTION_REPLACE_CHILDREN. - * @param uri The URI reference for the XML file to be loaded. If this is + * context node, and the action ACTION_REPLACE_CHILDREN.

+ * + * @param uri the URI reference for the XML file to be loaded. If this is * a relative URI, the base URI used by the implementation is * implementation dependent. + * * @return If async is set to true load returns * true if the document load was successfully initiated. * If an error occurred when initiating the document load, @@ -1325,21 +1413,21 @@ public boolean loadXML(String source) { /** * DOM Level 3 WD - Experimental. - * Save the document or the given node and all its descendants to a string - * (i.e. serialize the document or node). - *
The parameters used in the LSSerializer interface are - * assumed to have their default values when invoking this method. - *
The result of a call to this method is the same the result of a - * call to LSSerializer.writeToString with the document as - * the node to write. + *

Save the document or the given node and all its descendants to a string + * (i.e. serialize the document or node).

+ *

The parameters used in the {@link LSSerializer} interface are + * assumed to have their default values when invoking this method.

+ *

The result of a call to this method is the same the result of a + * call to {@link LSSerializer#writeToString(Node)} with the document as + * the node to write.

+ * * @param node Specifies what to serialize, if this parameter is * null the whole document is serialized, if it's * non-null the given node is serialized. - * @return The serialized document or null in case an error - * occurred. - * @exception DOMException - * WRONG_DOCUMENT_ERR: Raised if the node passed in as the node - * parameter is from an other document. + * + * @return the serialized document or null in case an error occurred + * @throws DOMException WRONG_DOCUMENT_ERR: Raised if the node passed in + * as the node parameter is from another document. */ public String saveXML(Node node) throws DOMException { @@ -1361,14 +1449,14 @@ public String saveXML(Node node) * upon operations. */ void setMutationEvents(boolean set) { - // does nothing by default - overidden in subclass + // does nothing by default - overridden in subclass } /** * Returns true if the DOM implementation generates mutation events. */ boolean getMutationEvents() { - // does nothing by default - overriden in subclass + // does nothing by default - overridden in subclass return false; } @@ -1382,10 +1470,11 @@ boolean getMutationEvents() { * as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building * DTD information unspecified.) * - * @param qualifiedName - * @param publicID - * @param systemID + * @param qualifiedName the qualified name of the document type + * @param publicID the document type public identifier + * @param systemID the document type system identifier * + * @return a new DocumentType which belongs to this document with the given qualifiedName, publicID, and systemID * @throws DOMException NOT_SUPPORTED_ERR for HTML documents, where * DTDs are not permitted. (HTML not yet implemented.) */ @@ -1404,8 +1493,9 @@ public DocumentType createDocumentType(String qualifiedName, * as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building * DTD information unspecified.) * - * @param name The name of the Entity we wish to provide a value for. + * @param name the name of the Entity we wish to provide a value for * + * @return a new Entity which belongs to this document with the given name * @throws DOMException NOT_SUPPORTED_ERR for HTML documents, where * nonstandard entities are not permitted. (HTML not yet implemented.) */ @@ -1427,8 +1517,9 @@ public Entity createEntity(String name) * as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building * DTD information unspecified.) * - * @param name The name of the Notation we wish to describe + * @param name the name of the Notation we wish to describe * + * @return a new notation which belongs to this document with the given name * @throws DOMException NOT_SUPPORTED_ERR for HTML documents, where * notations are not permitted. (HTML not yet implemented.) */ @@ -1446,6 +1537,11 @@ public Notation createNotation(String name) /** * NON-DOM Factory method: creates an element definition. Element * definitions hold default attribute values. + * + * @param name the name for the new element definition + * + * @return a new element definition which belongs to this document with the given name + * @throws DOMException INVALID_CHARACTER_ERR if the name is not an acceptable xml name */ public ElementDefinitionImpl createElementDefinition(String name) throws DOMException { @@ -1460,9 +1556,12 @@ public ElementDefinitionImpl createElementDefinition(String name) // other non-DOM methods - /** NON-DOM: Get the number associated with this document. Used to - * order documents in the implementation. + /** + * NON-DOM: Get the number associated with this document. Used to order documents in the implementation. + * + * @return the node number for this node */ + @Override protected int getNodeNumber() { if (documentNumber==0) { @@ -1473,9 +1572,12 @@ protected int getNodeNumber() { } - /** NON-DOM: Get a number associated with a node created with respect - * to this document. Needed for compareDocumentPosition when nodes - * are disconnected. This is only used on demand. + /** + * NON-DOM: Get a number associated with a node created with respect to this document. + * Needed for compareDocumentPosition when nodes are disconnected. This is only used on demand. + * + * @param node the Node to check + * @return number associated with the node */ protected int getNodeNumber(Node node) { @@ -1510,6 +1612,7 @@ protected int getNodeNumber(Node node) { * According to the DOM specifications, document nodes cannot be imported * and a NOT_SUPPORTED_ERR exception is thrown if attempted. */ + @Override public Node importNode(Node source, boolean deep) throws DOMException { return importNode(source, deep, false, null); @@ -1775,6 +1878,7 @@ private Node importNode(Node source, boolean deep, boolean cloningDoc, * @param source The node to adopt. * @see #importNode **/ + @Override public Node adoptNode(Node source) { NodeImpl node; Hashtable userData = null; @@ -1922,9 +2026,9 @@ else if (otherImpl instanceof org.apache.xerces.dom.DeferredDOMImplementationImp } /** - * Traverses the DOM Tree and expands deferred nodes and their - * children. - * + * Traverses the DOM Tree and expands deferred nodes and their children. + * + * @param node the node from which to traverse the DOM */ protected void undeferChildren(Node node) { @@ -1981,6 +2085,7 @@ protected void undeferChildren(Node node) { * attributes are of type ID or not are expected to return null. * @see #getIdentifier */ + @Override public Element getElementById(String elementId) { return getIdentifier(elementId); } @@ -2000,6 +2105,9 @@ protected final void clearIdentifiers(){ * node replaces the previous node. If the specified element * node is null, removeIdentifier() is called. * + * @param idName the name for the identifier that should be registered + * @param element the identifier that should be registered + * * @see #getIdentifier * @see #removeIdentifier */ @@ -2026,6 +2134,9 @@ public void putIdentifier(String idName, Element element) { * Returns a previously registered element with the specified * identifier name, or null if no element is registered. * + * @param idName the name for the identifier that should be retrieved + * @return an element with the specified identifier name, or null + * * @see #putIdentifier * @see #removeIdentifier */ @@ -2056,6 +2167,8 @@ public Element getIdentifier(String idName) { * Removes a previously registered element with the specified * identifier name. * + * @param idName the name for the identifier that should be removed + * * @see #putIdentifier * @see #getIdentifier */