org.apache.crimson.tree
Class XmlDocument

java.lang.Object
  org.apache.crimson.tree.NodeBase
      org.apache.crimson.tree.ParentNode
          org.apache.crimson.tree.XmlDocument

All Implemented Interfaces:

org.w3c.dom.Document, DocumentEx, ElementFactory, org.w3c.dom.Node, NodeEx, org.w3c.dom.NodeList, XmlWritable

public class XmlDocument

extends ParentNode

implements DocumentEx

This class implements the DOM Document interface, and also provides static factory methods to create document instances. Instances represent the top level of an XML 1.0 document, typically consisting of processing instructions followed by one tree of XML data. These documents may be written out for transfer or storage using a variety of text encodings.

The static factory methods do not offer any customization options. in particular, they do not enforce XML Namespaces when parsing, do not offer customizable element factories, and discard certain information which is not intended to be significant to applications. If your application requires more sophisticated use of DOM, you may need to use SAX directly with an XmlDocumentBuilder.

Note: element factories are deprecated because they are non-standard. They are only provided in this version for backwards compatibility. Instances are factories for their subsidiary nodes, but applications may provide their own element factory to bind element tags to particular DOM implementation classes (which must subclass ElementNode). For example, a factory may use a set of classes which support the HTML DOM methods, or which support methods associated with XML vocabularies for specialized problem domains as found within Internet Commerce systems. For example, an element tag <PurchaseOrder> could be mapped to a com.startup.commerce.PurchaseOrder class. The factory can also use XML Namespace information, if desired.

Since DOM requires nodes to be owned exclusively by one document, they can't be moved from one document to another using DOM APIs. This class provides an changeNodeOwner functionality which may be used to change the document associated with a node, and with any of its children.

Only the core DOM model is supported here, not the HTML support. Such support basically adds a set of convenience element types, and so can be implemented through element factories and document subclasses.

Author:

David Brownell, Rajiv Mordani

See Also:

XmlDocumentBuilder

Nested Class Summary

(package private) class	ParentNode.TagList
(package private) class	ParentNode.TagListNS
(package private) static class	XmlDocument.Catalog
(package private) static class	XmlDocument.DocFragNode
(package private) static class	XmlDocument.EntityRefNode
(package private) class	XmlDocument.ExtWriteContext

Field Summary

(package private) static MessageCatalog	catalog
(package private) static String	eol
private ElementFactory	factory
private Locale	locale
(package private) int	mutationCount
(package private) XmlDocument	ownerDocument
(package private) boolean	readonly
(package private) boolean	replaceRootElement
private String	systemId

Fields inherited from interface org.w3c.dom.Node

ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE

Constructor Summary

XmlDocument()
Constructs an empty document object.

Method Summary

org.w3c.dom.Node	appendChild(org.w3c.dom.Node n) DOM: Appends the specified child node to the document.
void	changeNodeOwner(org.w3c.dom.Node node) Changes the "owner document" of the given node, and all child and associated attribute nodes, to be this document.
(package private) void	checkChildType(int type)
Locale	chooseLocale(String[] languages) Chooses a client locale to use for diagnostics, using the first language specified in the list that is supported by this DOM implementation.
org.w3c.dom.Node	cloneNode(boolean deep) DOM: Returns a copy of this document.
org.w3c.dom.Attr	createAttribute(String name) DOM: Returns a valueless attribute node with no default value.
org.w3c.dom.Attr	createAttributeNS(String namespaceURI, String qualifiedName) DOM2:
org.w3c.dom.CDATASection	createCDATASection(String text) DOM: Returns a CDATA section initialized with the given text.
org.w3c.dom.Comment	createComment(String data) DOM: creates a comment node.
org.w3c.dom.DocumentFragment	createDocumentFragment() DOM: Creates a new document fragment.
org.w3c.dom.Element	createElement(String tagName) DOM: Create a new element, associated with this document, with no children, attributes, or parent, by calling createElementEx.
ElementEx	createElementEx(String tagName) Deprecated. Use the standard method createElement instead
ElementEx	createElementEx(String uri, String tagName) Deprecated. Use the standard method createElementNS instead
org.w3c.dom.Element	createElementNS(String namespaceURI, String qualifiedName) DOM2:
org.w3c.dom.EntityReference	createEntityReference(String name) DOM: Creates an entity reference to the named entity.
org.w3c.dom.ProcessingInstruction	createProcessingInstruction(String target, String instructions) DOM: Returns a Processing Instruction node for the specified processing target, with the given instructions.
org.w3c.dom.Text	createTextNode(String text) DOM: returns a Text node initialized with the given text.
XmlWriteContext	createWriteContext(Writer out) Returns an XML write context set up not to pretty-print, and which knows about the entities defined for this document.
XmlWriteContext	createWriteContext(Writer out, int level) Returns an XML write context which pretty-prints output starting at a specified indent level, and which knows about the entities defined for this document.
static XmlDocument	createXmlDocument(org.xml.sax.InputSource in, boolean doValidate) Deprecated. Use JAXP javax.xml.parsers package instead
static XmlDocument	createXmlDocument(InputStream in, boolean doValidate) Deprecated. Use JAXP javax.xml.parsers package instead
static XmlDocument	createXmlDocument(String documentURI) Deprecated. Use JAXP javax.xml.parsers package instead
static XmlDocument	createXmlDocument(String documentURI, boolean doValidate) Deprecated. Use JAXP javax.xml.parsers package instead
org.w3c.dom.NamedNodeMap	getAttributes() DOM: returns null.
org.w3c.dom.NodeList	getChildNodes() DOM: Returns an object which permits "live" access to all this node's children.
org.w3c.dom.DocumentType	getDoctype() DOM: returns the document type (DTD)
org.w3c.dom.Element	getDocumentElement() DOM: Returns the content root element.
org.w3c.dom.Element	getElementById(String elementId) Returns the Element whose ID is given by elementId.
ElementEx	getElementExById(String id) Deprecated. As of DOM level 2, replaced by the method Document.getElementById
ElementFactory	getElementFactory() Deprecated.
org.w3c.dom.NodeList	getElementsByTagName(String tagname) DOM: Returns a "live" list view of the elements below this one which have the specified tag name.
org.w3c.dom.NodeList	getElementsByTagNameNS(String namespaceURI, String localName)
org.w3c.dom.Node	getFirstChild() DOM: Returns the first child of this node, else null if there are no children.
org.w3c.dom.DOMImplementation	getImplementation() The DOMImplementation object that handles this document.
int	getIndexOf(org.w3c.dom.Node maybeChild) Returns the index of the node in the list of children, such that item() will return that child.
String	getInheritedAttribute(String name) Returns the value of a given attribute, tracing up through ancestors if needed.
String	getLanguage() Returns the language id (value of xml:lang attribute) applicable to this node, if known.
org.w3c.dom.Node	getLastChild() DOM: Returns the last child of this node, else null if there are no children.
int	getLength() DOM: Returns the number of children
Locale	getLocale() Returns the locale to be used for diagnostic messages.
String	getLocalName() DOM2: returns null.
(package private) String	getMessage(String messageId)
(package private) String	getMessage(String messageId, Object[] parameters)
String	getNamespaceURI() DOM2: returns null.
org.w3c.dom.Node	getNextSibling() DOM: Returns the node immediately following this node in a breadth first traversal of the tree, or null if there is no such sibling.
String	getNodeName() DOM: Returns the string "#document".
short	getNodeType() DOM: Returns the DOCUMENT_NODE node type constant.
String	getNodeValue() DOM: Returns null; overridden by subclasses as needed.
org.w3c.dom.Document	getOwnerDoc() DOM: returns null.
org.w3c.dom.Document	getOwnerDocument() DOM: Returns the document to which this node belongs.
(package private) ParentNode	getParentImpl()
org.w3c.dom.Node	getParentNode() DOM: Returns the node's parent.
String	getPrefix() DOM2: returns null.
org.w3c.dom.Node	getPreviousSibling() DOM: Returns the node immediately preceding this node in a breadth first traversal of the tree, or null if there is no such sibling.
String	getSystemId() Returns system ID associated with the document, or null if this is unknown.
boolean	hasAttributes() Returns whether this node (if it is an element) has any attributes.
boolean	hasChildNodes() DOM: Returns true if there are children to this node.
org.w3c.dom.Node	importNode(org.w3c.dom.Node importedNode, boolean deep)
org.w3c.dom.Node	insertBefore(org.w3c.dom.Node n, org.w3c.dom.Node refNode) DOM: Inserts the specified child node into the document.
boolean	isReadonly() Method to allow easy determination of whether a node is read only.
boolean	isSupported(String feature, String version) DOM2:
org.w3c.dom.Node	item(int i) DOM: Returns the Nth child, or null
(package private) static String	java2std(String encodingName)
(package private) TextNode	newText(char[] buf, int offset, int len)
void	normalize() DOM2: noop.
(package private) void	reduceWaste()
org.w3c.dom.Node	removeChild(org.w3c.dom.Node oldChild) DOM: removes child if present, returning argument.
int	removeWhiteSpaces(char[] buf)
org.w3c.dom.Node	replaceChild(org.w3c.dom.Node newChild, org.w3c.dom.Node refChild) DOM: Replaces the specified child with the new node, returning the original child or throwing an exception.
org.w3c.dom.DocumentType	setDoctype(String dtdPublicId, String dtdSystemId, String internalSubset) Establishes how the document prints its document type.
void	setElementFactory(ElementFactory factory) Deprecated.
void	setLocale(Locale locale) Assigns the locale to be used for diagnostic messages.
void	setNodeValue(String value) DOM: does nothing; overridden by subclasses as needed.
protected void	setOwnerDocument(XmlDocument doc)
(package private) void	setParentNode(ParentNode arg, int index)
void	setPrefix(String prefix) DOM2: throws DOMException.NAMESPACE_ERR Overridden by subclasses that support namespaces.
void	setReadonly(boolean deep) Sets the node to be readonly; applies recursively to the children of this node if the parameter is true.
void	setSystemId(String uri) Assigns the URI associated with the document, which is its system ID.
void	trimToSize() Called to minimize space utilization.
void	write(OutputStream out) Writes the document in UTF-8 character encoding, as a well formed XML construct.
void	write(Writer out) Writes the document as a well formed XML construct.
void	write(Writer out, String encoding) Writes the document in the specified encoding, and listing that encoding in the XML declaration.
void	writeChildrenXml(XmlWriteContext context) Writes all the child nodes of the document, following each one with the end-of-line string in use in this environment.
void	writeXml(XmlWriteContext context) Writes the document out using the specified context, using an encoding name derived from the stream in the context where that is possible.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.w3c.dom.Document

getElementsByTagName, getElementsByTagNameNS

Methods inherited from interface org.w3c.dom.Node

getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, isSupported, normalize, removeChild, setNodeValue, setPrefix

Field Detail

eol

static String eol

catalog

static final MessageCatalog catalog

locale

private Locale locale

systemId

private String systemId

factory

private ElementFactory factory

mutationCount

int mutationCount

replaceRootElement

boolean replaceRootElement

ownerDocument

XmlDocument ownerDocument

readonly

boolean readonly

Constructor Detail

XmlDocument

public XmlDocument()

Constructs an empty document object.

Method Detail

createXmlDocument

public static XmlDocument createXmlDocument(String documentURI,
                                            boolean doValidate)
                                     throws IOException,
                                            org.xml.sax.SAXException

Deprecated. Use JAXP javax.xml.parsers package instead

Construct an XML document from the data at the specified URI, optionally validating. This uses validating parser if validation is requested, otherwise uses non-validating parser. XML Namespace conformance is not tested when parsing.

Parameters:

documentURI - The URI (normally URL) of the document

doValidate - If true, validity errors are treated as fatal

Throws:

IOException - as appropriate

org.xml.sax.SAXException - as appropriate

org.xml.sax.SAXParseException - (with line number information) for parsing errors

IllegalStateException - at least when the parser is configured incorrectly

createXmlDocument

public static XmlDocument createXmlDocument(String documentURI)
                                     throws IOException,
                                            org.xml.sax.SAXException

Deprecated. Use JAXP javax.xml.parsers package instead

Construct an XML document from the data at the specified URI, using the nonvalidating parser. XML Namespace conformance is not tested when parsing.

Parameters:

documentURI - The URI (normally URL) of the document

Throws:

IOException - as appropriate

org.xml.sax.SAXException - as appropriate

org.xml.sax.SAXParseException - (with line number information) for parsing errors

IllegalStateException - at least when the parser is configured incorrectly

createXmlDocument

public static XmlDocument createXmlDocument(InputStream in,
                                            boolean doValidate)
                                     throws IOException,
                                            org.xml.sax.SAXException

Deprecated. Use JAXP javax.xml.parsers package instead

Construct an XML document from input stream, optionally validating. This document must not require interpretation of relative URLs, since the base URL is not known. This uses the validating parser if validation is requested, otherwise uses the non-validating parser. XML Namespace conformance is not tested when parsing.

Parameters:

in - Holds xml document

doValidate - If true, validity errors are treated as fatal

Throws:

IOException - as appropriate

org.xml.sax.SAXException - as appropriate

org.xml.sax.SAXParseException - (with line number information) for parsing errors

IllegalStateException - at least when the parser is configured incorrectly

createXmlDocument

public static XmlDocument createXmlDocument(org.xml.sax.InputSource in,
                                            boolean doValidate)
                                     throws IOException,
                                            org.xml.sax.SAXException

Deprecated. Use JAXP javax.xml.parsers package instead

Construct an XML document from the data in the specified input source, optionally validating. This uses the validating parser if validation is requested, otherwise uses the non-validating parser. XML Namespace conformance is not tested when parsing.

Parameters:

in - The input source of the document

doValidate - If true, validity errors are treated as fatal

Throws:

IOException - as appropriate

org.xml.sax.SAXException - as appropriate

org.xml.sax.SAXParseException - (with line number information) for parsing errors

IllegalStateException - at least when the parser is configured incorrectly

getLocale

public Locale getLocale()

Returns the locale to be used for diagnostic messages.

Specified by:

getLocale in interface DocumentEx

setLocale

public void setLocale(Locale locale)

Assigns the locale to be used for diagnostic messages. Multi-language applications, such as web servers dealing with clients from different locales, need the ability to interact with clients in languages other than the server's default. When an XmlDocument is created, its locale is the default locale for the virtual machine.

Specified by:

setLocale in interface DocumentEx

See Also:

chooseLocale(java.lang.String[])

chooseLocale

public Locale chooseLocale(String[] languages)

Chooses a client locale to use for diagnostics, using the first language specified in the list that is supported by this DOM implementation. That locale is then automatically assigned using setLocale(). Such a list could be provided by a variety of user preference mechanisms, including the HTTP Accept-Language header field.

Specified by:

chooseLocale in interface DocumentEx

Parameters:

languages - Array of language specifiers, ordered with the most preferable one at the front. For example, "en-ca" then "fr-ca", followed by "zh_CN". Both RFC 1766 and Java styles are supported.

Returns:

The chosen locale, or null.

See Also:

MessageCatalog

write

public void write(OutputStream out)
           throws IOException

Writes the document in UTF-8 character encoding, as a well formed XML construct.

Parameters:

out - stream on which the document will be written

Throws:

IOException

write

public void write(Writer out)
           throws IOException

Writes the document as a well formed XML construct. If the encoding can be determined from the writer, that is used in the document's XML declaration. The encoding name may first be transformed from a Java-internal form to a standard one; for example, Java's "UTF8" is the standard "UTF-8".

Use of UTF-8 (or UTF-16) OutputStreamWriters is strongly encouraged. All other encodings may lose critical data, since the standard Java output writers substitute characters such as the question mark for data which they can't encode in the current output encoding. The IETF and other organizations strongly encourage the use of UTF-8; also, all XML processors are guaranteed to support it.

Parameters:

out - stream on which the document will be written

Throws:

IOException

See Also:

write(java.io.Writer,java.lang.String)

java2std

static String java2std(String encodingName)

write

public void write(Writer out,
                  String encoding)
           throws IOException

Writes the document in the specified encoding, and listing that encoding in the XML declaration. The document will be well formed XML; at this time, it will not additionally be valid XML or standalone, since it includes no document type declaration.

Note that the document will by default be "pretty printed". Extra whitespace is added to indent children of elements according to their level of nesting, unless those elements have (or inherit) the xml:space='preserve' attribute value. This space will be removed if, when the document is read back with DOM, a call to ElementNode.normalize is made. To avoid this pretty printing, use a write context configured to disable it, or explicitly assign an xml:space='preserve' attribute to the root node of your document.

Also, if a SAX parser was used to construct this tree, data will have been discarded. Most of that will be insignificant in terms of a "logical" view of document data: comments, whitespace outside of the top level element, the exact content of the XML directive, and entity references were expanded. However, if a DOCTYPE declaration was provided, it was also discarded. Such declarations will often be logically significant, due to the attribute value defaulting and normalization they can provide.

In general, DOM does not support "round tripping" data from XML to DOM and back without losing data about physical structures and DTD information. "Logical structure" will be preserved.

Parameters:

out - the writer to use when writing the document

encoding - the encoding name to use; this should be a standard encoding name registered with the IANA (like "UTF-8") not a Java-internal name (like "UTF8").

Throws:

IOException

See Also:

setDoctype(java.lang.String, java.lang.String, java.lang.String), writeXml(org.apache.crimson.tree.XmlWriteContext)

createWriteContext

public XmlWriteContext createWriteContext(Writer out)

Returns an XML write context set up not to pretty-print, and which knows about the entities defined for this document.

Parameters:

out - stream on which the document will be written

createWriteContext

public XmlWriteContext createWriteContext(Writer out,
                                          int level)

Returns an XML write context which pretty-prints output starting at a specified indent level, and which knows about the entities defined for this document.

Parameters:

out - stream on which the document will be written

level - initial indent level for pretty-printing

writeXml

public void writeXml(XmlWriteContext context)
              throws IOException

Writes the document out using the specified context, using an encoding name derived from the stream in the context where that is possible.

Specified by:

writeXml in interface XmlWritable

Parameters:

context - describes how to write the document

Throws:

IOException

See Also:

createWriteContext(java.io.Writer), createWriteContext(java.io.Writer,int)

writeChildrenXml

public void writeChildrenXml(XmlWriteContext context)
                      throws IOException

Writes all the child nodes of the document, following each one with the end-of-line string in use in this environment.

Specified by:

writeChildrenXml in interface XmlWritable

Overrides:

writeChildrenXml in class ParentNode

Parameters:

context - describes how the children should be printed

Throws:

IOException

checkChildType

void checkChildType(int type)
              throws org.w3c.dom.DOMException

Specified by:

checkChildType in class ParentNode

Throws:

org.w3c.dom.DOMException

setSystemId

public final void setSystemId(String uri)

Assigns the URI associated with the document, which is its system ID.

Parameters:

uri - The document's system ID, as used when storing the document.

getSystemId

public final String getSystemId()

Returns system ID associated with the document, or null if this is unknown.

This URI should not be used when interpreting relative URIs, since the document may be partially stored in external parsed entities with different base URIs. Instead, use methods in the XmlReadable interface as the document is being parsed, so that the correct base URI is available.

Specified by:

getSystemId in interface DocumentEx

appendChild

public org.w3c.dom.Node appendChild(org.w3c.dom.Node n)
                             throws org.w3c.dom.DOMException

DOM: Appends the specified child node to the document. Only one element or document type node may be a child of a document.

Specified by:

appendChild in interface org.w3c.dom.Node

Overrides:

appendChild in class ParentNode

Parameters:

n - the new child to be appended

Throws:

org.w3c.dom.DOMException

insertBefore

public org.w3c.dom.Node insertBefore(org.w3c.dom.Node n,
                                     org.w3c.dom.Node refNode)
                              throws org.w3c.dom.DOMException

DOM: Inserts the specified child node into the document. Only one element or document type node may be a child of a document.

Specified by:

insertBefore in interface org.w3c.dom.Node

Overrides:

insertBefore in class ParentNode

Parameters:

n - the node to be inserted.

refNode - the node before which this is to be inserted

Throws:

org.w3c.dom.DOMException

replaceChild

public org.w3c.dom.Node replaceChild(org.w3c.dom.Node newChild,
                                     org.w3c.dom.Node refChild)
                              throws org.w3c.dom.DOMException

DOM: Replaces the specified child with the new node, returning the original child or throwing an exception. The new child must belong to this particular document.

Specified by:

replaceChild in interface org.w3c.dom.Node

Overrides:

replaceChild in class ParentNode

Parameters:

newChild - the new child to be inserted

refChild - node which is to be replaced

Throws:

org.w3c.dom.DOMException

getNodeType

public final short getNodeType()

DOM: Returns the DOCUMENT_NODE node type constant.

Specified by:

getNodeType in interface org.w3c.dom.Node

getDoctype

public final org.w3c.dom.DocumentType getDoctype()

DOM: returns the document type (DTD)

Specified by:

getDoctype in interface org.w3c.dom.Document

setDoctype

public org.w3c.dom.DocumentType setDoctype(String dtdPublicId,
                                           String dtdSystemId,
                                           String internalSubset)

Establishes how the document prints its document type. If a system ID (URI) is provided, that is used in a SYSTEM (or PUBLIC, if a public ID is also provided) declaration. If an internal subset is provided, that will be printed. The root element in the DTD will be what the document itself provides.

Parameters:

dtdPublicId - Holds a "public identifier" used to identify the last part of the external DTD subset that is read into the DTD. This may be omitted, and in any case is ignored unless a system ID is provided.

dtdSystemId - Holds a "system identifier" (a URI) used to identify the last part of the external DTD subset that is read into the DTD. This may be omitted, in which case the document type will contain at most an internal subset. This URI should not be a relative URI unless the document will be accessed in a context from which that relative URI makes sense.

internalSubset - Optional; this holds XML text which will be put into the internal subset. This must be legal syntax, and it is not tested by this document.

getDocumentElement

public org.w3c.dom.Element getDocumentElement()

DOM: Returns the content root element.

Specified by:

getDocumentElement in interface org.w3c.dom.Document

setElementFactory

public final void setElementFactory(ElementFactory factory)

Deprecated.

Assigns the element factory to be used by this document.

Specified by:

setElementFactory in interface DocumentEx

Parameters:

factory - the element factory to be used; if this is null, all elements will be implemented by ElementNode.

getElementFactory

public final ElementFactory getElementFactory()

Deprecated.

Returns the element factory to be used by this document.

Specified by:

getElementFactory in interface DocumentEx

createElement

public org.w3c.dom.Element createElement(String tagName)
                                  throws org.w3c.dom.DOMException

DOM: Create a new element, associated with this document, with no children, attributes, or parent, by calling createElementEx.

Specified by:

createElement in interface org.w3c.dom.Document

Parameters:

tagName - the tag of the element, used to determine what type element to create as well as what tag to assign the new node.

Throws:

IllegalArgumentException - if a mapping is defined, but is invalid because the element can't be instantiated or does not subclass ElementNode.

org.w3c.dom.DOMException

createElementNS

public org.w3c.dom.Element createElementNS(String namespaceURI,
                                           String qualifiedName)
                                    throws org.w3c.dom.DOMException

DOM2:

Specified by:

createElementNS in interface org.w3c.dom.Document

Throws:

org.w3c.dom.DOMException

Since:

DOM Level 2 Warning: Does not work with the deprecated ElementFactory

createElementEx

public final ElementEx createElementEx(String tagName)
                                throws org.w3c.dom.DOMException

Deprecated. Use the standard method createElement instead

Create a new element, associated with this document, with no children, attributes, or parent. This uses the element factory, or else directly constructs an ElementNode.

Specified by:

createElementEx in interface ElementFactory

Parameters:

tagName - the tag of the element, used to determine what type element to create as well as what tag to assign the new node.

Throws:

IllegalArgumentException - if a mapping is defined, but is invalid because the element can't be instantiated or does not subclass ElementNode.

org.w3c.dom.DOMException

createElementEx

public final ElementEx createElementEx(String uri,
                                       String tagName)
                                throws org.w3c.dom.DOMException

Deprecated. Use the standard method createElementNS instead

Create a new element, associated with this document, with no children, attributes, or parent. This uses the element factory, or else directly constructs an ElementNode.

Specified by:

createElementEx in interface ElementFactory

Parameters:

uri - The namespace used to determine what type of element to create. This is not stored with the element; the element must be inserted into a DOM tree in a location where namespace declarations cause its tag to be interpreted correctly.

tagName - The tag of the element, which should not contain any namespace prefix.

Throws:

IllegalArgumentException - When a mapping is defined, but is invalid because the element can't be instantiated or does not subclass ElementNode.

org.w3c.dom.DOMException

createTextNode

public org.w3c.dom.Text createTextNode(String text)

DOM: returns a Text node initialized with the given text.

Specified by:

createTextNode in interface org.w3c.dom.Document

Parameters:

text - The contents of the text node being created, which should never contain "]]>".

createCDATASection

public org.w3c.dom.CDATASection createCDATASection(String text)

DOM: Returns a CDATA section initialized with the given text.

Specified by:

createCDATASection in interface org.w3c.dom.Document

Parameters:

text - the text which the CDATA section will hold, which should never contain "]]>".

newText

TextNode newText(char[] buf,
                 int offset,
                 int len)
           throws org.xml.sax.SAXException

Throws:

org.xml.sax.SAXException

createProcessingInstruction

public org.w3c.dom.ProcessingInstruction createProcessingInstruction(String target,
                                                                     String instructions)
                                                              throws org.w3c.dom.DOMException

DOM: Returns a Processing Instruction node for the specified processing target, with the given instructions.

Specified by:

createProcessingInstruction in interface org.w3c.dom.Document

Parameters:

target - the target of the processing instruction

instructions - the processing instruction, which should never contain "?>".

Throws:

org.w3c.dom.DOMException

createAttribute

public org.w3c.dom.Attr createAttribute(String name)
                                 throws org.w3c.dom.DOMException

DOM: Returns a valueless attribute node with no default value.

Specified by:

createAttribute in interface org.w3c.dom.Document

Parameters:

name - the name of the attribute.

Throws:

org.w3c.dom.DOMException

createAttributeNS

public org.w3c.dom.Attr createAttributeNS(String namespaceURI,
                                          String qualifiedName)
                                   throws org.w3c.dom.DOMException

DOM2:

Specified by:

createAttributeNS in interface org.w3c.dom.Document

Throws:

org.w3c.dom.DOMException

Since:

DOM Level 2

createComment

public org.w3c.dom.Comment createComment(String data)

DOM: creates a comment node.

Specified by:

createComment in interface org.w3c.dom.Document

Parameters:

data - The characters which will be in the comment. This should not include the "--" characters.

getOwnerDoc

public org.w3c.dom.Document getOwnerDoc()

DOM: returns null.

getImplementation

public org.w3c.dom.DOMImplementation getImplementation()

The DOMImplementation object that handles this document.

Specified by:

getImplementation in interface org.w3c.dom.Document

createDocumentFragment

public org.w3c.dom.DocumentFragment createDocumentFragment()

DOM: Creates a new document fragment.

Specified by:

createDocumentFragment in interface org.w3c.dom.Document

createEntityReference

public org.w3c.dom.EntityReference createEntityReference(String name)
                                                  throws org.w3c.dom.DOMException

DOM: Creates an entity reference to the named entity. Note that the entity must already be defined in the document type, and that the name must be a legal entity name.

Specified by:

createEntityReference in interface org.w3c.dom.Document

Parameters:

name - the name of the the parsed entity

Throws:

org.w3c.dom.DOMException

getNodeName

public final String getNodeName()

DOM: Returns the string "#document".

Specified by:

getNodeName in interface org.w3c.dom.Node

cloneNode

public org.w3c.dom.Node cloneNode(boolean deep)

DOM: Returns a copy of this document.

Note: At this time, any element factory or document type associated with this document will not be cloned.

Specified by:

cloneNode in interface org.w3c.dom.Node

Parameters:

deep - if true, child nodes are also cloned.

changeNodeOwner

public final void changeNodeOwner(org.w3c.dom.Node node)
                           throws org.w3c.dom.DOMException

Changes the "owner document" of the given node, and all child and associated attribute nodes, to be this document. If the node has a parent, it is first removed from that parent. Obsolete Use importNode method instead. Still useful for internal implementation.

Specified by:

changeNodeOwner in interface DocumentEx

Parameters:

node -

Throws:

org.w3c.dom.DOMException - WRONG_DOCUMENT_ERROR when attempting to change the owner for some other DOM implementation

HIERARCHY_REQUEST_ERROR when the node is a document, document type, entity, or notation; or when it is an attribute associated with an element whose owner is not being (recursively) changed.

getElementById

public org.w3c.dom.Element getElementById(String elementId)

Returns the Element whose ID is given by elementId.

Specified by:

getElementById in interface org.w3c.dom.Document

Since:

DOM Level 2

getElementExById

public ElementEx getElementExById(String id)

Deprecated. As of DOM level 2, replaced by the method Document.getElementById

Returns the element whose ID is given by the parameter; or null if no such element exists. This relies on elements to know the name of their ID attribute, as will be currently be true only if the document has been parsed from XML text with a DTD using the XmlDocumentBuilder class, or if it has been constructed using specialized DOM implementation classes which know the name of their ID attribute. (XML allows only one ID attribute per element, and different elements may use different names for their ID attributes.)

This may be used to implement internal IDREF linkage, as well as some kinds of XPointer linkage as used in current drafts of XLink.

Specified by:

getElementExById in interface DocumentEx

Parameters:

id - The value of the ID attribute which will be matched by any element which is returned.

importNode

public org.w3c.dom.Node importNode(org.w3c.dom.Node importedNode,
                                   boolean deep)
                            throws org.w3c.dom.DOMException

Specified by:

importNode in interface org.w3c.dom.Document

Throws:

org.w3c.dom.DOMException

Since:

DOM Level 2

trimToSize

public void trimToSize()

Called to minimize space utilization. Affects only this node; children must be individually trimmed.

reduceWaste

void reduceWaste()

hasChildNodes

public final boolean hasChildNodes()

DOM: Returns true if there are children to this node.

Specified by:

hasChildNodes in interface org.w3c.dom.Node

Overrides:

hasChildNodes in class NodeBase

getFirstChild

public final org.w3c.dom.Node getFirstChild()

DOM: Returns the first child of this node, else null if there are no children.

Specified by:

getFirstChild in interface org.w3c.dom.Node

Overrides:

getFirstChild in class NodeBase

getLastChild

public final org.w3c.dom.Node getLastChild()

DOM: Returns the last child of this node, else null if there are no children.

Specified by:

getLastChild in interface org.w3c.dom.Node

Overrides:

getLastChild in class NodeBase

getLength

public final int getLength()

DOM: Returns the number of children

Specified by:

getLength in interface org.w3c.dom.NodeList

Overrides:

getLength in class NodeBase

item

public final org.w3c.dom.Node item(int i)

DOM: Returns the Nth child, or null

Specified by:

item in interface org.w3c.dom.NodeList

Overrides:

item in class NodeBase

removeChild

public org.w3c.dom.Node removeChild(org.w3c.dom.Node oldChild)
                             throws org.w3c.dom.DOMException

DOM: removes child if present, returning argument.

Specified by:

removeChild in interface org.w3c.dom.Node

Overrides:

removeChild in class NodeBase

Parameters:

oldChild - the node which is to be removed

Throws:

org.w3c.dom.DOMException - thrown always.

getElementsByTagName

public org.w3c.dom.NodeList getElementsByTagName(String tagname)

DOM: Returns a "live" list view of the elements below this one which have the specified tag name. Because this is "live", this API is dangerous -- indices are not stable in the face of most tree updates. Use a TreeWalker instead.

Parameters:

tagname - the tag name to show; or "*" for all elements.

Returns:

list of such elements

getElementsByTagNameNS

public org.w3c.dom.NodeList getElementsByTagNameNS(String namespaceURI,
                                                   String localName)

Since:

DOM Level 2

getIndexOf

public final int getIndexOf(org.w3c.dom.Node maybeChild)

Returns the index of the node in the list of children, such that item() will return that child.

Specified by:

getIndexOf in interface NodeEx

Overrides:

getIndexOf in class NodeBase

Parameters:

maybeChild - the node which may be a child of this one

Returns:

the index of the node in the set of children, or else -1 if that node is not a child

normalize

public void normalize()

Description copied from class: NodeBase

DOM2: noop.

Specified by:

normalize in interface org.w3c.dom.Node

Overrides:

normalize in class NodeBase

Since:

DOM Level 2 In DOM2, normalize() was generalized and got moved to Node. XXX Comments below are old: DOM2: Merges all adjacent Text nodes in the tree rooted by this element. Avoid using this on large blocks of text not separated by markup such as elements or processing instructions, since it can require arbitrarily large blocks of contiguous memory. XXX The following extension breaks a DOM conformance test so the code has been modified to not behave as described:

As a compatible extension to DOM, this normalizes treatment of whitespace except when the xml:space='preserve' attribute value applies to a node. All whitespace is normalized to one space. This ensures that text which is pretty-printed and then reread (and normalized) retains the same content.

removeWhiteSpaces

public int removeWhiteSpaces(char[] buf)

getParentImpl

ParentNode getParentImpl()

isReadonly

public boolean isReadonly()

Description copied from interface: NodeEx

Method to allow easy determination of whether a node is read only.

Specified by:

isReadonly in interface NodeEx

Returns:

true if the node is read only

setReadonly

public void setReadonly(boolean deep)

Description copied from interface: NodeEx

Sets the node to be readonly; applies recursively to the children of this node if the parameter is true.

Specified by:

setReadonly in interface NodeEx

Parameters:

deep - If true recursively set the nodes in the subtree under the current node to be read only. If false then set only the current node to be readonly

getLanguage

public String getLanguage()

Returns the language id (value of xml:lang attribute) applicable to this node, if known. Traces up through ancestors as needed.

Specified by:

getLanguage in interface NodeEx

Returns:

the value of the xml:lang attribute, or null if no such attribute is found.

getInheritedAttribute

public String getInheritedAttribute(String name)

Returns the value of a given attribute, tracing up through ancestors if needed. In the XML standard, two attributes are inherited: xml:lang and xml:space. This mechanism can also be involved with Cascading Style Sheets (CSS). The current version of XML Namespaces also uses inheritance.

Specified by:

getInheritedAttribute in interface NodeEx

Parameters:

name - identifies the attribute; colons may be included, but namespace prefixes are not interpreted

Returns:

the value of the inherited attribute, or null if no value was inherited.

getParentNode

public org.w3c.dom.Node getParentNode()

DOM: Returns the node's parent. This will be null in cases such as newly created or removed nodes, and for attributes, fragments, and documents.

Specified by:

getParentNode in interface org.w3c.dom.Node

setParentNode

void setParentNode(ParentNode arg,
                   int index)
             throws org.w3c.dom.DOMException

Throws:

org.w3c.dom.DOMException

setOwnerDocument

protected void setOwnerDocument(XmlDocument doc)

getOwnerDocument

public org.w3c.dom.Document getOwnerDocument()

DOM: Returns the document to which this node belongs.

Specified by:

getOwnerDocument in interface org.w3c.dom.Node

setNodeValue

public void setNodeValue(String value)

DOM: does nothing; overridden by subclasses as needed.

Specified by:

setNodeValue in interface org.w3c.dom.Node

getNodeValue

public String getNodeValue()

DOM: Returns null; overridden by subclasses as needed.

Specified by:

getNodeValue in interface org.w3c.dom.Node

getChildNodes

public org.w3c.dom.NodeList getChildNodes()

DOM: Returns an object which permits "live" access to all this node's children.

In this implementation, nodes provide such access without needing another node as an intermediary; "this" is returned.

Specified by:

getChildNodes in interface org.w3c.dom.Node

getNextSibling

public org.w3c.dom.Node getNextSibling()

DOM: Returns the node immediately following this node in a breadth first traversal of the tree, or null if there is no such sibling. In this implementation, sibling access from a node is slower than indexed access from its parent.

Specified by:

getNextSibling in interface org.w3c.dom.Node

getPreviousSibling

public org.w3c.dom.Node getPreviousSibling()

DOM: Returns the node immediately preceding this node in a breadth first traversal of the tree, or null if there is no such sibling. In this implementation, sibling access from a node is slower than indexed access from its parent.

Specified by:

getPreviousSibling in interface org.w3c.dom.Node

getAttributes

public org.w3c.dom.NamedNodeMap getAttributes()

DOM: returns null. Overridden by the ElementNode2 subclass.

Specified by:

getAttributes in interface org.w3c.dom.Node

isSupported

public boolean isSupported(String feature,
                           String version)

DOM2:

Specified by:

isSupported in interface org.w3c.dom.Node

Since:

DOM Level 2

getNamespaceURI

public String getNamespaceURI()

DOM2: returns null. Overridden by subclasses that support namespaces, ie. ElementNode2 and AttributeNode.

Specified by:

getNamespaceURI in interface org.w3c.dom.Node

getPrefix

public String getPrefix()

DOM2: returns null. Overridden by subclasses that support namespaces.

Specified by:

getPrefix in interface org.w3c.dom.Node

setPrefix

public void setPrefix(String prefix)
               throws org.w3c.dom.DOMException

DOM2: throws DOMException.NAMESPACE_ERR Overridden by subclasses that support namespaces.

Specified by:

setPrefix in interface org.w3c.dom.Node

Throws:

org.w3c.dom.DOMException

getLocalName

public String getLocalName()

DOM2: returns null. Overridden by subclasses that support namespaces.

Specified by:

getLocalName in interface org.w3c.dom.Node

hasAttributes

public boolean hasAttributes()

Returns whether this node (if it is an element) has any attributes. Overridden by Element implementations

Specified by:

hasAttributes in interface org.w3c.dom.Node

Since:

DOM Level 2

getMessage

String getMessage(String messageId)

getMessage

String getMessage(String messageId,
                  Object[] parameters)