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

Constructors

Document

public Document();

Constructs a new empty document using the default element factory.

Document

public Document(ElementFactory f);

Constructs a new empty document using the given ElementFactory object when building the XML element hierarchy.

Parameter	Description
f	The ElementFactory to use.

Methods

addChild

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.

clear

public void clear();

Sets the Document back to its initial empty state retaining only the ElementFactory association.

Return Value:

No return value.

createElement

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.

createElement

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.

createElement

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.

createOutputStream

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.

elementDeclarations

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.

getCharset

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.

getDocType

public final String getDocType();

Retrieves the document type.

Return Value:

Returns the name specified in the <!DOCTYPE> tag.

getDTD

public DTD getDTD();

Retrieves the document's DTD.

Return Value:

Returns the DTD.

getDTDURL

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.

getEncoding

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.

getFileModifiedDate

public long getFileModifiedDate();

Retrieves the last modified date on the source of the URL.

Return Value:

Returns the modified date.

getId

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.

getOutputStyle

public int getOutputStyle();

Retrieves the current output style.

Return Value:

Returns the output style. The default style is XMLOutputStream.PRETTY.

getParent

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.

getRoot

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.

getText

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.

getType

public int getType();

Retrieves the document type.

Return Value:

Returns the value defined by Element.DOCUMENT.

Overrides:

getType() in ElementImpl.

getURL

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.

getVersion

public final String getVersion();

Retrieves the version information.

Return Value:

Returns the version number stored in the <?XML ...?> tag.

load

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.

load

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.

load

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.

parsed

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.

removeChild

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.

reportError

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.

save

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.

setCharset

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.

setEncoding

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.

setOutputStyle

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

setText

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.

setURL

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.

setVersion

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.

Fields

dtd

The Document Type Definition (DTD).

factory

The factory used to create the elements in the document.