Class Document
public class Document extends ElementImpl implements
ElementFactory
{
// Fields
protected DTD dtd;
protected ElementFactory factory;
// Constructors
public Document();
public Document(ElementFactory f);
// Methods
public void addChild(Element elem, Element after);
public void clear();
public final Element createElement(int type, Name tag);
public final Element createElement(int type, String tag);
public final Element createElement(int type);
public XMLOutputStream createOutputStream(
OutputStream out) throws IOException;
public final Enumeration elementDeclarations();
public final String getCharset();
public final String getDocType();
public DTD getDTD();
public final String getDTDURL();
public final String getEncoding();
public long getFileModifiedDate();
public final String getId();
public int getOutputStyle();
public Element getParent();
public final Element getRoot();
public String getText();
public int getType();
public final String getURL();
public final String getVersion();
public void load(String urlstr) throws ParseException;
public void load(URL url) throws ParseException;
public void load(InputStream in) throws ParseException;
public void parsed(Element e);
public void removeChild(Element elem);
public void reportError(ParseException e, OutputStream out);
public void save(XMLOutputStream o) throws IOException;
public final void setCharset(String encoding);
public final void setEncoding( String encoding );
public void setOutputStyle(int style);
public void setText(String text);
public void setURL( String urlstr ) throws ParseException;
public final void setVersion( String version );
}
This class implements an XML document, which can be thought of as the root of a tree. Each XML tag can either represent a node or a leaf of this tree. The Document class allows you to load an XML document, manipulate it, and then save it back out again. The document can be loaded by specifying a URL or an input stream.
According to the XML specification, the root of the tree consists of any combination of comments and processing instructions, but only one root element. A helper method getRoot is provided as a short cut to finding the root element.
Also see com.ms.xml.om.Element
ElementImpl
|
+--Document
public Document();
Constructs a new empty document using the default element factory.
public Document(ElementFactory f);
Constructs a new empty document using the given ElementFactory object when building the XML element hierarchy.
public void addChild(Element elem, Element after);
Adds a child Element to the document. This is an override of the Element.addChild method that stores the new child and stores the last element of type Element.ELEMENT, so that getRoot can be used as a short cut to find a particular element.
Parameter | Description |
elem
| The child element to add.
|
after
| The element after which to add the elem element.
|
Overrides:
addChild(Element,Element) in ElementImpl.
public void clear();
Sets the Document back to its initial empty state retaining only the ElementFactory association.
Return Value:
No return value.
public final Element createElement(int type, Name tag);
Creates a new element for the given element type and tag name using the ElementFactory for this Document. This method allows the Document class to be used as an ElementFactory itself.
Parameter | Description |
type
| The element type.
|
tag
| The element tag.
|
public final Element createElement(int type, String tag);
Creates a new element for the given element type and tag name.
Parameter | Description |
type
| The element type.
|
tag
| The element tag name.
|
public final Element createElement(int type);
Creates a new element for a given element type with a null tag name.
Return Value:
Returns the element created.
Parameter | Description |
type
| The element type.
|
public XMLOutputStream createOutputStream(OutputStream out)
throws IOException;
Creates an XML output stream matching the format found on load().
Return Value:
Returns the XML output stream.
Parameter | Description |
out
| The output stream.
|
Exceptions:
IOException
if the output stream cannot be created.
public final Enumeration elementDeclarations();
Retrieves an enumeration of the element declarations from the DTD. These are returned as ElementDecl objects.
Return Value:
Returns the element declarations enumeration object.
public final String getCharset();
Retrieves the character set. This is an alias for the setEncoding method and exists for compatibility reasons only.
Return Value:
Returns the character set.
public final String getDocType();
Retrieves the document type.
Return Value:
Returns the name specified in the <!DOCTYPE> tag.
public DTD getDTD();
Retrieves the document's DTD.
Return Value:
Returns the DTD.
public final String getDTDURL();
Retrieves the document type URL.
Return Value:
Returns the URL specified in the <!DOCTYPE> tag or null if an internal DTD was specified.
public final String getEncoding();
Retrieves the character encoding information.
Return Value:
Returns the encoding information stored in the <?XML ...?> tag or the user-defined output encoding if it has been more recently set.
public long getFileModifiedDate();
Retrieves the last modified date on the source of the URL.
Return Value:
Returns the modified date.
public final String getId();
Retrieves the external identifier.
Return Value:
Returns the external identifier specified in the <!DOCTYPE> tag or null if no <!DOCTYPE> tag was specified.
public int getOutputStyle();
Retrieves the current output style.
Return Value:
Returns the output style. The default style is XMLOutputStream.PRETTY.
public Element getParent();
Retrieves the parent element. There is no parent element for Document, so this method always returns null.
Return Value:
Returns null.
Overrides:
getParent() in ElementImpl.
public final Element getRoot();
Retrieves the root node of the XML parse tree. This is guaranteed to be of type Element.ELEMENT.
Return Value:
Returns the root node.
public String getText();
Retrieves the document text.
Return Value:
Returns a plain text (that is, not marked-up) representation of the entire document.
Overrides:
getText() in ElementImpl.
public int getType();
Retrieves the document type.
Return Value:
Returns the value defined by Element.DOCUMENT.
Overrides:
getType() in ElementImpl.
public final String getURL();
Retrieves the URL.
Return Value:
Returns the last URL sent to the load() method or null if an input stream was used.
public final String getVersion();
Retrieves the version information.
Return Value:
Returns the version number stored in the <?XML ...?> tag.
public void load(String urlstr) throws ParseException;
Loads the document from the given URL string.
Return Value:
No return value.
Parameter | Description |
urlstr
| The URL specifying the address of the document.
|
Exceptions:
ParseException
if the file contains errors.
public void load(URL url) throws ParseException;
Loads the document from the given URL.
Return Value:
No return value.
Parameter | Description |
url
| The URL string.
|
Exceptions:
ParseException
if a syntax error is found.
public void load(InputStream in) throws ParseException;
Loads the document using the given input stream. This is useful if you have the XML data already in memory.
Return Value:
No return value.
Parameter | Description |
in
| The input stream.
|
Exceptions:
ParseException
when a syntax error is found.
public void parsed(Element e);
Called when the given element is completely parsed.
Return Value:
No return value.
Parameter | Description |
e
| The Element that has been parsed.
|
public void removeChild(Element elem);
Removes the specified child Element from the Document.
Parameter | Description |
elem
| The child element to remove.
|
Overrides:
removeChild(Element) in ElementImpl.
public void reportError(ParseException e, OutputStream out);
Returns information about the given parse exception that was generated during the load.
Return Value:
No return value.
Parameter | Description |
e
| The exception to report on.
|
out
| The output stream to report to.
|
public void save(XMLOutputStream o) throws IOException;
Saves the document to the given output stream.
Return Value:
No return value.
Parameter | Description |
o
| The output stream.
|
Overrides:
save(XMLOutputStream) in ElementImpl.
Exceptions:
IOException
if there is a problem saving the output.
public final void setCharset(String encoding);
Sets the character set. This is an alias for the getEncoding method and exists for compatibility reasons only.
Return Value:
No return value.
Parameter | Description |
encoding
| The encoding information.
|
public final void setEncoding( String encoding );
Sets the character encoding for output. Eventually it sets the ENCODING stored in the <?XML ...?> tag, but not until the document is saved. You should not call this method until the Document has been loaded.
Return Value:
No return value.
public void setOutputStyle(int style);
Sets the style for writing to an output stream. Use XMLOutputStream.PRETTY or .COMPACT.
Return Value:
No return value.
Parameter | Description |
int
| The style to set.
|
See Also: XMLOutputStream
public void setText(String text);
Passes the text through to the root node, if there is a root node.
Parameter | Description |
text
| The text to be set.
|
Overrides:
setText(String) in ElementImpl.
public void setURL( String urlstr ) throws ParseException;
An alias for load and is here for compatibility reasons only.
Return Value:
No return value.
Parameter | Description |
urlstr
| The URL string.
|
Exceptions:
ParseException
if an error occurs while parsing the URL string.
public final void setVersion( String version );
Sets the version number stored in the <?XML ...?> tag.
Return Value:
No return value.
Parameter | Description |
version
| The version information to set.
|
- dtd
- The Document Type Definition (DTD).
- factory
- The factory used to create the elements in the document.