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(Element parent, int type, Name
        tag, String text);
  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 Element findEntity( Name name );
  public final String getCharset();
  public final Name getDocType();
  public DTD getDTD();
  public final String getDTDURL();
  public Element getElementDecl( Name name );
  public final String getEncoding();
  public long getFileModifiedDate();
  public final String getId();
  public int getOutputStyle();
  public Element getParent();
  public final Element getRoot();
  public final String getStandalone();
  public String getText();
  public int getType();
  public final String getURL();
  public final String getVersion();
  public boolean isCaseInsensitive();
  public void load(String urlstr) throws ParseException;
  public void load(URL url) throws ParseException;
  public void load(InputStream in) throws ParseException;
  public boolean loadExternal();
  public void parsed(Element e);
  public void parsedAttribute(Element e, Name name, Object value);
  public void removeChild(Element elem);
  public void reportError(ParseException e, OutputStream out);
  public void save(XMLOutputStream o) throws IOException;
  public void setCaseInsensitive(boolean yes);
  public final void setCharset(String encoding);
  public final void setEncoding( String encoding );
  public void setLoadExternal(boolean yes);
  public void setOutputStyle(int style);
  public final void setStandalone( String value );
  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 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.

ParameterDescription
fThe 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.

ParameterDescription
elemThe child element to add.
afterThe element after which to add the elem element.

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(Element parent, int type, Name
        tag, String text);

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.

ParameterDescription
typeThe element type.
tagThe element tag.

createElement 

public final Element createElement(int type, String tag);

Creates a new element for the given element type and tag name. tag is case sensitive.

ParameterDescription
typeThe element type.
tagThe 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.

ParameterDescription
typeThe 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.

ParameterDescription
outThe 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.

findEntity 

public Element findEntity( Name name );

Returns the XML-DATA specification for the named entity. This is DTD information represented in an XML Object Model. See Specification for XML-Data for details.

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 Name getDocType();

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.

getElementDecl 

public Element getElementDecl( Name name );

Returns the XML-DATA specification for the named element. This is DTD information represented in an XML Object Model. See Specification for XML-Data for details.

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.

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.

getStandalone 

public final String getStandalone();

Retrieves the standalone information.

Return Value

Returns the standalone attribute stored in the <?XML ...?> tag.

getText 

public String getText();

Retrieves the document text.

Return Value

Returns a plain text (that is, not marked-up) representation of the entire document.

getType 

public int getType();

Retrieves the document type.

Return Value

Returns the value defined by Element.DOCUMENT.

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.

isCaseInsensitive 

public boolean isCaseInsensitive();

Return whether we're case insensitive.

load 

public void load(String urlstr) throws ParseException;

Loads the document from the given URL string.

Return Value

No return value.

ParameterDescription
urlstrThe 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.

ParameterDescription
urlThe 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.

ParameterDescription
inThe input stream.

Exceptions

ParseException when a syntax error is found.

loadExternal 

public boolean loadExternal();

Return whether to load external DTD's or entities.

parsed 

public void parsed(Element e);

Called when the given element is completely parsed.

Return Value

No return value.

ParameterDescription
eThe Element that has been parsed.

parsedAttribute 

public void parsedAttribute(Element e, Name name, Object value);

delegate to contained element factory

removeChild 

public void removeChild(Element elem);

Removes the specified child Element from the Document.

ParameterDescription
elemThe child element to remove.

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.

ParameterDescription
eThe exception to report on.
outThe 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.

ParameterDescription
oThe output stream.

Exceptions

>IOException if there is a problem saving the output.

setCaseInsensitive 

public void setCaseInsensitive(boolean yes);

Switch to determine whether next XML loaded will be treated as case sensitive or not. If not, names are folded to uppercase.

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.

ParameterDescription
encodingThe 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.

setLoadExternal 

public void setLoadExternal(boolean yes);

Switch to determine whether to load external DTD's or entities.

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.

ParameterDescription
intThe style to set.

See Also XMLOutputStream

setStandalone 

public final void setStandalone( String value );

Sets the RMD stored in the <?XML ...?> tag.

Return Value

No return value.

ParameterDescription
valueThe attribute value ('yes' or 'no').

setText 

public void setText(String text);

Passes the text through to the root node, if there is a root node.

ParameterDescription
textThe text to be set.

setURL 

public void setURL( String urlstr ) throws ParseException;

An alias for load and is here for compatibility reasons only.

Return Value

No return value.

ParameterDescription
urlstrThe 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.

ParameterDescription
versionThe version information to set.

Fields 

dtd
The Document Type Definition (DTD).
factory
The factory used to create the elements in the document.