org.jdom
Class Document

java.lang.Object
  |
  +--org.jdom.Document

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

public class Document

extends java.lang.Object

implements java.io.Serializable, java.lang.Cloneable

Document defines behavior for an XML Document, modeled in Java. Methods allow access to the root element as well as processing instructions and other document-level information.

Version:

$Revision: 1.57 $, $Date: 2002/04/18 13:12:35 $

Author:

Brett McLaughlin, Jason Hunter, Jools Enticknap, Bradley S. Huffman

See Also:

Serialized Form

Field Summary

protected org.jdom.ContentList	content This Document's Comments, ProcessingInstructions and the root Element.
protected DocType	docType The DocType declaration.

Constructor Summary

Document()
Creates a new empty document.

Document(Element rootElement)
This will create a new Document, with the supplied Element as the root element, and no DocType declaration.

Document(Element rootElement, DocType docType)
This will create a new Document, with the supplied Element as the root element and the supplied DocType declaration.

Document(java.util.List content)
This will create a new Document, with the supplied list of content, and no DocType declaration.

Document(java.util.List newContent, DocType docType)
This will create a new Document, with the supplied list of content, and the supplied DocType declaration.

Method Summary

Document	addContent(Comment comment) This will add a comment to the Document.
Document	addContent(ProcessingInstruction pi) Adds the specified PI to the document.
java.lang.Object	clone() This will return a deep clone of this Document.
Element	detachRootElement() Detach the root Element from this document.
boolean	equals(java.lang.Object ob) This tests for equality of this Document to the supplied Object.
java.util.List	getContent() This will return all content for the Document.
java.util.List	getContent(Filter filter) Return a filtered view of this Document's content.
DocType	getDocType() This will return the DocType declaration for this Document, or null if none exists.
Element	getRootElement() This will return the root Element for this Document
int	hashCode() This returns the hash code for this Document.
boolean	hasRootElement() This will return true if this document has a root element, false otherwise.
boolean	removeContent(Comment comment) This removes the specified Comment.
boolean	removeContent(ProcessingInstruction pi) This removes the specified ProcessingInstruction.
Document	setContent(java.util.List newContent) This sets the content of the Document.
Document	setDocType(DocType docType) This will set the DocType declaration for this Document.
Document	setRootElement(Element rootElement) This sets the root Element for the Document.
java.lang.String	toString() This returns a String representation of the Document, suitable for debugging.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

content

protected org.jdom.ContentList content

This Document's Comments, ProcessingInstructions and the root Element.

docType

protected DocType docType

The DocType declaration.

Constructor Detail

Document

public Document()

Creates a new empty document. A document must have a root element, so this document will not be well-formed and accessor methods will throw an IllegalStateException if this document is accessed before a root element is added. This method is most useful for build tools.

Document

public Document(Element rootElement,
                DocType docType)

This will create a new Document, with the supplied Element as the root element and the supplied DocType declaration.

Parameters:

rootElement - Element for document root.

docType - DocType declaration.

Document

public Document(Element rootElement)

This will create a new Document, with the supplied Element as the root element, and no DocType declaration.

Parameters:

rootElement - Element for document root

Document

public Document(java.util.List newContent,
                DocType docType)

This will create a new Document, with the supplied list of content, and the supplied DocType declaration.

Parameters:

content - List of starter content

docType - DocType declaration.

Throws:

IllegalAddException - if (1) the List contains more than one Element or objects of illegal types, or (2) if the given docType object is already attached to a document.

Document

public Document(java.util.List content)

This will create a new Document, with the supplied list of content, and no DocType declaration.

Parameters:

content - List of starter content

Throws:

IllegalAddException - if the List contains more than one Element or objects of illegal types.

Method Detail

hasRootElement

public boolean hasRootElement()

This will return true if this document has a root element, false otherwise.

Returns:

true if this document has a root element, false otherwise.

getRootElement

public Element getRootElement()

This will return the root Element for this Document

Returns:

Element - the document's root element

Throws:

IllegalStateException - if the root element hasn't been set

setRootElement

public Document setRootElement(Element rootElement)

This sets the root Element for the Document. If the document already has a root element, it is replaced.

Parameters:

rootElement - Element to be new root.

Returns:

Document - modified Document.

Throws:

IllegalAddException - if the given rootElement already has a parent.

detachRootElement

public Element detachRootElement()

Detach the root Element from this document.

Returns:

removed root Element

getDocType

public DocType getDocType()

This will return the DocType declaration for this Document, or null if none exists.

Returns:

DocType - the DOCTYPE declaration.

setDocType

public Document setDocType(DocType docType)

This will set the DocType declaration for this Document. Note that a DocType can only be attached to one Document. Attempting to set the DocType to a DocType object that already belongs to a Document will result in an IllegalAddException being thrown.

Parameters:

docType - DocType declaration.

Throws:

IllegalAddException - if the given docType is already attached to a Document.

addContent

public Document addContent(ProcessingInstruction pi)

Adds the specified PI to the document.

Parameters:

pi - the ProcessingInstruction to add.

Returns:

Document this document modified.

Throws:

IllegalAddException - if the given processing instruction already has a parent element.

addContent

public Document addContent(Comment comment)

This will add a comment to the Document.

Parameters:

comment - Comment to add.

Returns:

Document - this object modified.

Throws:

IllegalAddException - if the given comment already has a parent element.

getContent

public java.util.List getContent()

This will return all content for the Document. The returned list is "live" in document order and changes to it affect the document's actual content.

Sequential traversal through the List is best done with a Iterator since the underlying implement of List.size() may require walking the entire list.

Returns:

List - all Document content

Throws:

IllegalStateException - if the root element hasn't been set

getContent

public java.util.List getContent(Filter filter)

Return a filtered view of this Document's content.

Sequential traversal through the List is best done with a Iterator since the underlying implement of List.size() may require walking the entire list.

Parameters:

filter - Filter to apply

Returns:

List - filtered Document content

Throws:

IllegalStateException - if the root element hasn't been set

setContent

public Document setContent(java.util.List newContent)

This sets the content of the Document. The supplied List should contain only objects of type Element, Comment, and ProcessingInstruction.

When all objects in the supplied List are legal and before the new content is added, all objects in the old content will have their parentage set to null (no parent) and the old content list will be cleared. This has the effect that any active list (previously obtained with a call to getContent()) will also change to reflect the new content. In addition, all objects in the supplied List will have their parentage set to this document, but the List itself will not be "live" and further removals and additions will have no effect on this document content. If the user wants to continue working with a "live" list, then a call to setContent should be followed by a call to getContent() to obtain a "live" version of the content.

Passing a null or empty List clears the existing content.

In event of an exception the original content will be unchanged and the objects in the supplied content will be unaltered.

Parameters:

newContent - List of content to set

Returns:

this document modified

Throws:

IllegalAddException - if the List contains objects of illegal types.

removeContent

public boolean removeContent(ProcessingInstruction pi)

This removes the specified ProcessingInstruction. If the specified ProcessingInstruction is not a child of this Document, this method does nothing.

Parameters:

child - ProcessingInstruction to delete

Returns:

whether deletion occurred

removeContent

public boolean removeContent(Comment comment)

This removes the specified Comment. If the specified Comment is not a child of this Document, this method does nothing.

Parameters:

comment - Comment to delete

Returns:

whether deletion occurred

toString

public java.lang.String toString()

This returns a String representation of the Document, suitable for debugging. If the XML representation of the Document is desired, XMLOutputter.outputString(Document) should be used.

Overrides:

toString in class java.lang.Object

Returns:

String - information about the Document

equals

public final boolean equals(java.lang.Object ob)

This tests for equality of this Document to the supplied Object.

Overrides:

equals in class java.lang.Object

Parameters:

ob - Object to compare to.

Returns:

boolean - whether the Document is equal to the supplied Object.

hashCode

public final int hashCode()

This returns the hash code for this Document.

Overrides:

hashCode in class java.lang.Object

Returns:

int - hash code.

clone

public java.lang.Object clone()

This will return a deep clone of this Document.

Overrides:

clone in class java.lang.Object

Returns:

Object - clone of this Document.