ORG.oclc.xml.om
Class Document

java.lang.Object
  |
  +--ORG.oclc.xml.om.ElementImpl
        |
        +--ORG.oclc.xml.om.Document

public class Document

extends ElementImpl

implements ElementFactory

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.

See Also:

Element

Field Summary

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

Fields inherited from class ORG.oclc.xml.om.ElementImpl

attrlist

Constructor Summary

Document()
Constructs a new empty document using the default element factory.

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

Method Summary

void	addChild(Element elem, Element after) Adds a child Element to the document.
void	clear() Sets the Document back to its initial empty state retaining only the ElementFactory association.
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.
Element	createElement(int type) Creates a new element for a given element type with a null tag name.
Element	createElement(int type, String tag) Creates a new element for the given element type and tag name.
XMLOutputStream	createOutputStream(OutputStream out) Creates an XML output stream matching the format found on load().
Enumeration	elementDeclarations() Retrieves an enumeration of the element declarations from the DTD.
Element	findEntity(Name name) Returns the XML-DATA specification for the named entity.
String	getCharset() Retrieves the character set.
Name	getDocType() Returns the name specified in the <!DOCTYPE> tag.
DTD	getDTD() Retrieves the document's DTD.
String	getDTDURL() Retrieves the document type URL.
Element	getElementDecl(Name name) Returns the XML-DATA specification for the named element.
String	getEncoding() Retrieves the character encoding information.
long	getFileModifiedDate() Retrieves the last modified date on the source of the URL.
String	getId() Retrieves the external identifier.
int	getOutputStyle() Retrieves the current output style.
Element	getParent() Retrieves the parent element.
Element	getRoot() Retrieves the root node of the XML parse tree.
String	getStandalone() Retrieves the standalone information.
String	getText() Retrieves the document text.
int	getType() Retrieves the document type.
String	getURL() Retrieves the URL.
String	getVersion() Retrieves the version information.
boolean	isCaseInsensitive() Return whether we're case insensitive.
void	load(InputStream in) Loads the document using the given input stream.
void	load(String urlstr) Loads the document from the given URL string.
void	load(URL url) Loads the document from the given URL.
boolean	loadExternal() Return whether to load external DTD's or entities.
void	parsed(Element e) Called when the given element is completely parsed.
void	parsedAttribute(Element e, Name name, Object value) delegate to contained element factory
void	removeChild(Element elem) Removes the specified child Element from the Document.
void	reportError(ParseException e, OutputStream out) Returns information about the given parse exception that was generated during the load.
void	save(XMLOutputStream o) Saves the document to the given output stream.
void	setCaseInsensitive(boolean yes) Switch to determine whether next XML loaded will be treated as case sensitive or not.
void	setCharset(String encoding) Sets the character set.
void	setEncoding(String encoding) Sets the character encoding for output.
void	setLoadExternal(boolean yes) Switch to determine whether to load external DTD's or entities.
void	setOutputStyle(int style) Sets the style for writing to an output stream.
void	setStandalone(String value) Sets the RMD stored in the <?XML ...?> tag.
void	setText(String text) Passes the text through to the root node, if there is a root node.
void	setURL(String urlstr) An alias for load and is here for compatibility reasons only.
void	setVersion(String version) Sets the version number stored in the <?XML ...?> tag.

Methods inherited from class ORG.oclc.xml.om.ElementImpl

addChild, getAttribute, getAttribute, getAttributes, getChild, getChildren, getElements, getTagName, isAttributeQualified, numAttributes, numElements, qualifyName, removeAttribute, removeAttribute, saveAttributes, setAttribute, setAttribute, setParent, toSchema, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

dtd

protected DTD dtd

The Document Type Definition (DTD).

factory

protected ElementFactory factory

The factory used to create the elements in the document.

Constructor Detail

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.

Parameters:

f - The ElementFactory to use.

Method Detail

getType

public int getType()

Retrieves the document type.

Returns:

the value defined by Element.DOCUMENT.

Overrides:

getType in class ElementImpl

getText

public String getText()

Retrieves the document text.

Returns:

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

Overrides:

getText in class ElementImpl

setText

public void setText(String text)

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

Parameters:

text - The text to be set.

Overrides:

setText in class ElementImpl

getParent

public Element getParent()

Retrieves the parent element. There is no parent element for Document, so this method always returns null.

Returns:

null.

Overrides:

getParent in class ElementImpl

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.

Parameters:

elem - The child element to add.

after - The element after which to add the elem element.

Overrides:

addChild in class ElementImpl

removeChild

public void removeChild(Element elem)

Removes the specified child Element from the Document.

Parameters:

elem - The child element to remove.

Overrides:

removeChild in class ElementImpl

getRoot

public final Element getRoot()

Retrieves the root node of the XML parse tree. This is guaranteed to be of type Element.ELEMENT.

Returns:

the root node.

getVersion

public final String getVersion()

Retrieves the version information.

Returns:

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

setVersion

public final void setVersion(String version)

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

Parameters:

version - The version information to set.

Returns:

No return value.

getEncoding

public final String getEncoding()

Retrieves the character encoding information.

Returns:

the encoding information stored in the <?XML ...?> tag or the user-defined output encoding if it has been more recently set.

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.

Returns:

No return value.

getCharset

public final String getCharset()

Retrieves the character set. This is an alias for the setEncoding method and exists for compatibility reasons only.

Returns:

the character set.

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.

Parameters:

encoding - The encoding information.

Returns:

No return value.

getStandalone

public final String getStandalone()

Retrieves the standalone information.

Returns:

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

setStandalone

public final void setStandalone(String value)

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

Parameters:

value - The attribute value ('yes' or 'no').

Returns:

No return value.

getDocType

public final Name getDocType()

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

getDTDURL

public final String getDTDURL()

Retrieves the document type URL.

Returns:

the URL specified in the <!DOCTYPE> tag or null if an internal DTD was specified.

getURL

public final String getURL()

Retrieves the URL.

Returns:

the last URL sent to the load() method or null if an input stream was used.

getFileModifiedDate

public long getFileModifiedDate()

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

Returns:

the modified date.

getId

public final String getId()

Retrieves the external identifier.

Returns:

the external identifier specified in the <!DOCTYPE> tag or null if no <!DOCTYPE> tag was specified.

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.

Specified by:

createElement in interface ElementFactory

Parameters:

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. tag is case sensitive.

Parameters:

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.

Parameters:

type - The element type.

Returns:

the element created.

parsed

public void parsed(Element e)

Called when the given element is completely parsed.

Specified by:

parsed in interface ElementFactory

Parameters:

e - The Element that has been parsed.

Returns:

No return value.

parsedAttribute

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

delegate to contained element factory

Specified by:

parsedAttribute in interface ElementFactory

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.

isCaseInsensitive

public boolean isCaseInsensitive()

Return whether we're case insensitive.

setLoadExternal

public void setLoadExternal(boolean yes)

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

loadExternal

public boolean loadExternal()

Return whether to load external DTD's or entities.

load

public void load(String urlstr)
          throws ParseException

Loads the document from the given URL string.

Parameters:

urlstr - The URL specifying the address of the document.

Returns:

No return value.

Throws:

ParseException - if the file contains errors.

setURL

public void setURL(String urlstr)
            throws ParseException

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

Parameters:

urlstr - The URL string.

Returns:

No return value.

Throws:

ParseException - if an error occurs while parsing the URL string.

load

public void load(URL url)
          throws ParseException

Loads the document from the given URL.

Parameters:

url - The URL string.

Returns:

No return value.

Throws:

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.

Parameters:

in - The input stream.

Returns:

No return value.

Throws:

ParseException - when a syntax error is found.

reportError

public void reportError(ParseException e,
                        OutputStream out)

Returns information about the given parse exception that was generated during the load.

Parameters:

e - The exception to report on.

out - The output stream to report to.

Returns:

No return value.

setOutputStyle

public void setOutputStyle(int style)

Sets the style for writing to an output stream. Use XMLOutputStream.PRETTY or .COMPACT.

Parameters:

int - The style to set.

Returns:

No return value.

See Also:

XMLOutputStream

getOutputStyle

public int getOutputStyle()

Retrieves the current output style.

Returns:

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

createOutputStream

public XMLOutputStream createOutputStream(OutputStream out)
                                   throws IOException

Creates an XML output stream matching the format found on load().

Parameters:

out - The output stream.

Returns:

the XML output stream.

Throws:

IOException - if the output stream cannot be created.

save

public void save(XMLOutputStream o)
          throws IOException

Saves the document to the given output stream.

Parameters:

o - The output stream.

Returns:

No return value.

Throws:

IOException - if there is a problem saving the output.

Overrides:

save in class ElementImpl

elementDeclarations

public final Enumeration elementDeclarations()

Retrieves an enumeration of the element declarations from the DTD. These are returned as ElementDecl objects.

Returns:

the element declarations enumeration object.

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.

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.

clear

public void clear()

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

Returns:

No return value.

getDTD

public DTD getDTD()

Retrieves the document's DTD.

Returns:

the DTD.