com.sun.xml.tree
Class XmlDocument

java.lang.Object
  |
  +--com.sun.xml.tree.NodeBase
        |
        +--com.sun.xml.tree.ParentNode
              |
              +--com.sun.xml.tree.XmlDocument

public class XmlDocument
extends com.sun.xml.tree.ParentNode
implements DocumentEx, DOMImplementation

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.

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.

See Also:
XmlDocumentBuilder

Constructor Summary
XmlDocument()
          Constructs an empty document object.
 
Method Summary
 Node appendChild(Node n)
          DOM: Appends the specified child node to the document.
 void changeNodeOwner(Node node)
          Changes the "owner document" of the given node, and all child and associated attribute nodes, to be this document.
 java.util.Locale chooseLocale(java.lang.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.
 Node cloneNode(boolean deep)
          DOM: Returns a copy of this document.
 Attr createAttribute(java.lang.String name)
          DOM: Returns a valueless attribute node with no default value.
 CDATASection createCDATASection(java.lang.String text)
          DOM: Returns a CDATA section initialized with the given text.
 Comment createComment(java.lang.String data)
          DOM: creates a comment node.
 DocumentFragment createDocumentFragment()
          DOM: Creates a new document fragment.
 Element createElement(java.lang.String tagName)
          DOM: Create a new element, associated with this document, with no children, attributes, or parent, by calling createElementEx.
 ElementEx createElementEx(java.lang.String tagName)
          Create a new element, associated with this document, with no children, attributes, or parent.
 ElementEx createElementEx(java.lang.String uri, java.lang.String tagName)
          Create a new element, associated with this document, with no children, attributes, or parent.
 EntityReference createEntityReference(java.lang.String name)
          DOM: Creates an entity reference to the named entity.
 ProcessingInstruction createProcessingInstruction(java.lang.String target, java.lang.String instructions)
          DOM: Returns a Processing Instruction node for the specified processing target, with the given instructions.
 Text createTextNode(java.lang.String text)
          DOM: returns a Text node initialized with the given text.
 XmlWriteContext createWriteContext(java.io.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(java.io.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(InputSource in, boolean doValidate)
          Construct an XML document from the data in the specified input source, optionally validating.
static XmlDocument createXmlDocument(java.io.InputStream in, boolean doValidate)
          Construct an XML document from input stream, optionally validating.
static XmlDocument createXmlDocument(java.lang.String documentURI)
          Construct an XML document from the data at the specified URI, using Sun's nonvalidating parser.
static XmlDocument createXmlDocument(java.lang.String documentURI, boolean doValidate)
          Construct an XML document from the data at the specified URI, optionally validating.
 DocumentType getDoctype()
          DOM: returns the document type (DTD)
 Element getDocumentElement()
          DOM: Returns the content root element.
 ElementEx getElementExById(java.lang.String id)
          Returns the element whose ID is given by the parameter; or null if no such element exists.
 ElementFactory getElementFactory()
          Returns the element factory to be used by this document.
 DOMImplementation getImplementation()
          DOM: Returns an object describing the features of the DOM implementation used by this document: it supports the XML 1.0 feature set.
 java.util.Locale getLocale()
          Returns the locale to be used for diagnostic messages.
 java.lang.String getNodeName()
          DOM: Returns the string "#document".
 short getNodeType()
          DOM: Returns the DOCUMENT_NODE node type constant.
 Document getOwnerDoc()
          DOM: returns null.
 java.lang.String getSystemId()
          Returns system ID associated with the document, or null if this is unknown.
 boolean hasFeature(java.lang.String feature, java.lang.String version)
          DOM: Reports that this document supports XML version 1.0 (only).
 Node insertBefore(Node n, Node refNode)
          DOM: Inserts the specified child node into the document.
 DocumentType setDoctype(java.lang.String dtdPublicId, java.lang.String dtdSystemId, java.lang.String internalSubset)
          Establishes how the document prints its document type.
 void setElementFactory(ElementFactory factory)
          Assigns the element factory to be used by this document.
 void setLocale(java.util.Locale locale)
          Assigns the locale to be used for diagnostic messages.
 void setSystemId(java.lang.String uri)
          Assigns the URI associated with the document, which is its system ID.
 void write(java.io.OutputStream out)
          Writes the document in UTF-8 character encoding, as a well formed XML construct.
 void write(java.io.Writer out)
          Writes the document as a well formed XML construct.
 void write(java.io.Writer out, java.lang.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 com.sun.xml.tree.ParentNode
doneChild, doneParse, getElementsByTagName, getFirstChild, getIndexOf, getLastChild, getLength, hasChildNodes, item, removeChild, replaceChild, startParse, trimToSize
 
Methods inherited from class com.sun.xml.tree.NodeBase
getAttributes, getChildNodes, getInheritedAttribute, getInheritedAttribute, getLanguage, getNextSibling, getNodeValue, getOwnerDocument, getParentNode, getPreviousSibling, setNodeValue
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlDocument

public XmlDocument()
Constructs an empty document object.
Method Detail

createXmlDocument

public static XmlDocument createXmlDocument(java.lang.String documentURI,
                                            boolean doValidate)
                                     throws java.io.IOException,
                                            SAXException
Construct an XML document from the data at the specified URI, optionally validating. This uses Sun's validating parser if validation is requested, otherwise uses Sun's 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:
java.io.IOException - as appropriate
SAXException - as appropriate
SAXParseException - (with line number information) for parsing errors
IllegalStateException - at least when the parser is configured incorrectly

createXmlDocument

public static XmlDocument createXmlDocument(java.lang.String documentURI)
                                     throws java.io.IOException,
                                            SAXException
Construct an XML document from the data at the specified URI, using Sun's nonvalidating parser. XML Namespace conformance is not tested when parsing.
Parameters:
documentURI - The URI (normally URL) of the document
Throws:
java.io.IOException - as appropriate
SAXException - as appropriate
SAXParseException - (with line number information) for parsing errors
IllegalStateException - at least when the parser is configured incorrectly

createXmlDocument

public static XmlDocument createXmlDocument(java.io.InputStream in,
                                            boolean doValidate)
                                     throws java.io.IOException,
                                            SAXException
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 Sun's validating parser if validation is requested, otherwise uses Sun's 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:
java.io.IOException - as appropriate
SAXException - as appropriate
SAXParseException - (with line number information) for parsing errors
IllegalStateException - at least when the parser is configured incorrectly

createXmlDocument

public static XmlDocument createXmlDocument(InputSource in,
                                            boolean doValidate)
                                     throws java.io.IOException,
                                            SAXException
Construct an XML document from the data in the specified input source, optionally validating. This uses Sun's validating parser if validation is requested, otherwise uses Sun's 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:
java.io.IOException - as appropriate
SAXException - as appropriate
SAXParseException - (with line number information) for parsing errors
IllegalStateException - at least when the parser is configured incorrectly

getLocale

public java.util.Locale getLocale()
Returns the locale to be used for diagnostic messages.
Specified by:
getLocale in interface DocumentEx

setLocale

public void setLocale(java.util.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 java.util.Locale chooseLocale(java.lang.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(java.io.OutputStream out)
           throws java.io.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

write

public void write(java.io.Writer out)
           throws java.io.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
See Also:
write(java.io.Writer,java.lang.String)

write

public void write(java.io.Writer out,
                  java.lang.String encoding)
           throws java.io.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").
See Also:
setDoctype(java.lang.String, java.lang.String, java.lang.String), writeXml(com.sun.xml.tree.XmlWriteContext)

createWriteContext

public XmlWriteContext createWriteContext(java.io.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(java.io.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 java.io.IOException
Writes the document out using the specified context, using an encoding name derived from the stream in the context where that is possible.
Parameters:
context - describes how to write the document
See Also:
createWriteContext(java.io.Writer), createWriteContext(java.io.Writer,int)

writeChildrenXml

public void writeChildrenXml(XmlWriteContext context)
                      throws java.io.IOException
Writes all the child nodes of the document, following each one with the end-of-line string in use in this environment.
Overrides:
writeChildrenXml in class com.sun.xml.tree.ParentNode

setSystemId

public final void setSystemId(java.lang.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 java.lang.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 Node appendChild(Node n)
                 throws DOMException
DOM: Appends the specified child node to the document. Only one element or document type node may be a child of a document.
Parameters:
node - the node to be appended.
Overrides:
appendChild in class com.sun.xml.tree.ParentNode

insertBefore

public Node insertBefore(Node n,
                         Node refNode)
                  throws DOMException
DOM: Inserts the specified child node into the document. Only one element or document type node may be a child of a document.
Parameters:
n - the node to be inserted.
refNode - the node before which this is to be inserted
Overrides:
insertBefore in class com.sun.xml.tree.ParentNode

getNodeType

public final short getNodeType()
DOM: Returns the DOCUMENT_NODE node type constant.

getDoctype

public final DocumentType getDoctype()
DOM: returns the document type (DTD)

setDoctype

public DocumentType setDoctype(java.lang.String dtdPublicId,
                               java.lang.String dtdSystemId,
                               java.lang.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 Element getDocumentElement()
DOM: Returns the content root element.

setElementFactory

public final void setElementFactory(ElementFactory factory)
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()
Returns the element factory to be used by this document.
Specified by:
getElementFactory in interface DocumentEx

createElement

public final Element createElement(java.lang.String tagName)
                            throws DOMException
DOM: Create a new element, associated with this document, with no children, attributes, or parent, by calling createElementEx.
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:
java.lang.IllegalArgumentException - if a mapping is defined, but is invalid because the element can't be instantiated or does not subclass ElementNode.

createElementEx

public final ElementEx createElementEx(java.lang.String tagName)
                                throws DOMException
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.
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:
java.lang.IllegalArgumentException - if a mapping is defined, but is invalid because the element can't be instantiated or does not subclass ElementNode.

createElementEx

public final ElementEx createElementEx(java.lang.String uri,
                                       java.lang.String tagName)
                                throws DOMException
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.
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:
java.lang.IllegalArgumentException - When a mapping is defined, but is invalid because the element can't be instantiated or does not subclass ElementNode.

createTextNode

public Text createTextNode(java.lang.String text)
DOM: returns a Text node initialized with the given text.
Parameters:
text - The contents of the text node being created, which should never contain "]]>".

createCDATASection

public CDATASection createCDATASection(java.lang.String text)
DOM: Returns a CDATA section initialized with the given text.
Parameters:
text - the text which the CDATA section will hold, which should never contain "]]>".

createProcessingInstruction

public ProcessingInstruction createProcessingInstruction(java.lang.String target,
                                                         java.lang.String instructions)
                                                  throws DOMException
DOM: Returns a Processing Instruction node for the specified processing target, with the given instructions.
Parameters:
target - the target of the processing instruction
instructions - the processing instruction, which should never contain "?>".

createAttribute

public Attr createAttribute(java.lang.String name)
                     throws DOMException
DOM: Returns a valueless attribute node with no default value.
Parameters:
name - the name of the attribute.

createComment

public Comment createComment(java.lang.String data)
DOM: creates a comment node.
Parameters:
data - The characters which will be in the comment. This should not include the "--" characters.

getOwnerDoc

public Document getOwnerDoc()
DOM: returns null.

getImplementation

public DOMImplementation getImplementation()
DOM: Returns an object describing the features of the DOM implementation used by this document: it supports the XML 1.0 feature set.

createDocumentFragment

public DocumentFragment createDocumentFragment()
DOM: Creates a new document fragment.

createEntityReference

public EntityReference createEntityReference(java.lang.String name)
                                      throws 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.
Parameters:
name - the name of the the parsed entity

getNodeName

public final java.lang.String getNodeName()
DOM: Returns the string "#document".

cloneNode

public 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.

Parameters:
deep - if true, child nodes are also cloned.

changeNodeOwner

public final void changeNodeOwner(Node node)
                           throws 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.
Parameters:
node -  
Throws:
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.


hasFeature

public boolean hasFeature(java.lang.String feature,
                          java.lang.String version)
DOM: Reports that this document supports XML version 1.0 (only).
Specified by:
hasFeature in interface DOMImplementation
Parameters:
feature - identifies a feature of this DOM implementation; case is ignored
version - optionally identifies the version of the feature

getElementExById

public ElementEx getElementExById(java.lang.String id)
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.


Submit Feedback to xml-feedback@java.sun.com
Copyright © 1998-1999 Sun Microsystems, Inc. All Rights Reserved.

Sun Microsystems, Inc.
901 San Antonio Road
Palo Alto, California, 94303, U.S.A.