|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.sun.xml.tree.NodeBase | +--com.sun.xml.tree.ParentNode | +--com.sun.xml.tree.XmlDocument
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.
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. |
Node |
replaceChild(Node newChild,
Node refChild)
DOM: Replaces the specified child with the new node, returning the original child or throwing an exception. |
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,
startParse,
trimToSize |
Methods inherited from class com.sun.xml.tree.NodeBase |
getAttributes,
getChildNodes,
getInheritedAttribute,
getInheritedAttribute,
getLanguage,
getNextSibling,
getNodeValue,
getOwnerDocument,
getParentNode,
getPreviousSibling,
isReadonly,
setNodeValue,
setReadonly |
Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Constructor Detail |
public XmlDocument()
Method Detail |
public static XmlDocument createXmlDocument(java.lang.String documentURI, boolean doValidate) throws java.io.IOException, SAXException
documentURI
- The URI (normally URL) of the documentdoValidate
- If true, validity errors are treated as fatalpublic static XmlDocument createXmlDocument(java.lang.String documentURI) throws java.io.IOException, SAXException
documentURI
- The URI (normally URL) of the documentpublic static XmlDocument createXmlDocument(java.io.InputStream in, boolean doValidate) throws java.io.IOException, SAXException
in
- Holds xml documentdoValidate
- If true, validity errors are treated as fatalpublic static XmlDocument createXmlDocument(InputSource in, boolean doValidate) throws java.io.IOException, SAXException
in
- The input source of the documentdoValidate
- If true, validity errors are treated as fatalpublic java.util.Locale getLocale()
public void setLocale(java.util.Locale locale)
chooseLocale(java.lang.String[])
public java.util.Locale chooseLocale(java.lang.String[] languages)
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.MessageCatalog
public void write(java.io.OutputStream out) throws java.io.IOException
out
- stream on which the document will be writtenpublic void write(java.io.Writer out) throws java.io.IOException
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.
out
- stream on which the document will be writtenwrite(java.io.Writer,java.lang.String)
public void write(java.io.Writer out, java.lang.String encoding) throws java.io.IOException
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.
out
- the writer to use when writing the documentencoding
- 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").setDoctype(java.lang.String, java.lang.String, java.lang.String)
,
writeXml(com.sun.xml.tree.XmlWriteContext)
public XmlWriteContext createWriteContext(java.io.Writer out)
out
- stream on which the document will be writtenpublic XmlWriteContext createWriteContext(java.io.Writer out, int level)
out
- stream on which the document will be writtenlevel
- initial indent level for pretty-printingpublic void writeXml(XmlWriteContext context) throws java.io.IOException
context
- describes how to write the documentcreateWriteContext(java.io.Writer)
,
createWriteContext(java.io.Writer,int)
public void writeChildrenXml(XmlWriteContext context) throws java.io.IOException
public final void setSystemId(java.lang.String uri)
uri
- The document's system ID, as used when storing
the document.public final java.lang.String getSystemId()
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.
public Node appendChild(Node n) throws DOMException
node
- the node to be appended.public Node insertBefore(Node n, Node refNode) throws DOMException
n
- the node to be inserted.refNode
- the node before which this is to be insertedpublic Node replaceChild(Node newChild, Node refChild) throws DOMException
newChild
- the new child to be insertedrefChild
- node which is to be replacedpublic final short getNodeType()
public final DocumentType getDoctype()
public DocumentType setDoctype(java.lang.String dtdPublicId, java.lang.String dtdSystemId, java.lang.String internalSubset)
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.public Element getDocumentElement()
public final void setElementFactory(ElementFactory factory)
factory
- the element factory to be used; if this is null,
all elements will be implemented by ElementNode.public final ElementFactory getElementFactory()
public final Element createElement(java.lang.String tagName) throws DOMException
tagName
- the tag of the element, used to determine what
type element to create as well as what tag to assign the new node.public final ElementEx createElementEx(java.lang.String tagName) throws DOMException
tagName
- the tag of the element, used to determine what
type element to create as well as what tag to assign the new node.public final ElementEx createElementEx(java.lang.String uri, java.lang.String tagName) throws DOMException
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.public Text createTextNode(java.lang.String text)
text
- The contents of the text node being created, which
should never contain "]]>".public CDATASection createCDATASection(java.lang.String text)
text
- the text which the CDATA section will hold, which
should never contain "]]>".public ProcessingInstruction createProcessingInstruction(java.lang.String target, java.lang.String instructions) throws DOMException
target
- the target of the processing instructioninstructions
- the processing instruction, which should
never contain "?>".public Attr createAttribute(java.lang.String name) throws DOMException
name
- the name of the attribute.public Comment createComment(java.lang.String data)
data
- The characters which will be in the comment.
This should not include the "--" characters.public Document getOwnerDoc()
public DOMImplementation getImplementation()
public DocumentFragment createDocumentFragment()
public EntityReference createEntityReference(java.lang.String name) throws DOMException
name
- the name of the the parsed entitypublic final java.lang.String getNodeName()
public Node cloneNode(boolean deep)
Note: At this time, any element factory or document type associated with this document will not be cloned.
deep
- if true, child nodes are also cloned.public final void changeNodeOwner(Node node) throws DOMException
node
- 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.
public boolean hasFeature(java.lang.String feature, java.lang.String version)
feature
- identifies a feature of this DOM implementation;
case is ignoredversion
- optionally identifies the version of the featurepublic ElementEx getElementExById(java.lang.String id)
This may be used to implement internal IDREF linkage, as well as some kinds of XPointer linkage as used in current drafts of XLink.
id
- The value of the ID attribute which will be matched
by any element which is returned.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |