org.jdom

Class Document

public class Document extends Object implements Parent

An XML document. Methods allow access to the root element as well as the DocType and other document-level information.

Version: $Revision: 1.84 $, $Date: 2004/08/31 21:47:51 $

Author: Brett McLaughlin Jason Hunter Jools Enticknap Bradley S. Huffman

Field Summary
protected StringbaseURI
See http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030226/core.html#baseURIs-Considerations
Constructor Summary
Document()
Creates a new empty document.
Document(Element rootElement, DocType docType, String baseURI)
This will create a new Document, with the supplied Element as the root element, the supplied DocType declaration, and the specified base URI.
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(Element rootElement)
This will create a new Document, with the supplied Element as the root element, and no DocType declaration.
Document(List content)
This will create a new Document, with the supplied list of content, and a DocType declaration only if the content contains a DocType instance.
Method Summary
DocumentaddContent(Content child)
Appends the child to the end of the content list.
DocumentaddContent(Collection c)
Appends all children in the given collection to the end of the content list.
DocumentaddContent(int index, Content child)
Inserts the child into the content list at the given index.
DocumentaddContent(int index, Collection c)
Inserts the content in a collection into the content list at the given index.
Objectclone()
This will return a deep clone of this Document.
ListcloneContent()
ElementdetachRootElement()
Detach the root Element from this document.
booleanequals(Object ob)
This tests for equality of this Document to the supplied Object.
StringgetBaseURI()

Returns the URI from which this document was loaded, or null if this is not known.

ContentgetContent(int index)
ListgetContent()
This will return all content for the Document.
ListgetContent(Filter filter)
Return a filtered view of this Document's content.
intgetContentSize()
IteratorgetDescendants()
Returns an iterator that walks over all descendants in document order.
IteratorgetDescendants(Filter filter)
Returns an iterator that walks over all descendants in document order applying the Filter to return only elements that match the filter rule.
DocTypegetDocType()
This will return the DocType declaration for this Document, or null if none exists.
DocumentgetDocument()
ParentgetParent()
ObjectgetProperty(String id)
Returns the object associated with this document under the given "id" string, or null if there is no binding or if the binding explicitly stored a null value.
ElementgetRootElement()
This will return the root Element for this Document
inthashCode()
This returns the hash code for this Document.
booleanhasRootElement()
This will return true if this document has a root element, false otherwise.
intindexOf(Content child)
ListremoveContent()
Removes all child content from this parent.
ListremoveContent(Filter filter)
Remove all child content from this parent matching the supplied filter.
booleanremoveContent(Content child)
ContentremoveContent(int index)
voidsetBaseURI(String uri)

Sets the effective URI from which this document was loaded, and against which relative URLs in this document will be resolved.

DocumentsetContent(Collection newContent)
This sets the content of the Document.
DocumentsetContent(int index, Content child)
DocumentsetContent(int index, Collection collection)
Replace the child at the given index whith the supplied collection.
DocumentsetContent(Content child)
Set this document's content to be the supplied child.
DocumentsetDocType(DocType docType)
This will set the DocType declaration for this Document.
voidsetProperty(String id, Object value)
Assigns an arbitrary object to be associated with this document under the given "id" string.
DocumentsetRootElement(Element rootElement)
This sets the root Element for the Document.
StringtoString()
This returns a String representation of the Document, suitable for debugging.

Field Detail

baseURI

protected String baseURI
See http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030226/core.html#baseURIs-Considerations

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, String baseURI)
This will create a new Document, with the supplied Element as the root element, the supplied DocType declaration, and the specified base URI.

Parameters: rootElement Element for document root. docType DocType declaration. baseURI the URI from which this doucment was loaded.

Throws: IllegalAddException if the given docType object is already attached to a document or the given rootElement already has a parent

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.

Throws: IllegalAddException if the given DocType object is already attached to a document or the given rootElement already has a parent

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

Throws: IllegalAddException if the given rootElement already has a parent.

Document

public Document(List content)
This will create a new Document, with the supplied list of content, and a DocType declaration only if the content contains a DocType instance. A null list is treated the same as the no-arg constructor.

Parameters: content List of starter content

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

Method Detail

addContent

public Document addContent(Content child)
Appends the child to the end of the content list.

Parameters: child child to append to end of content list

Returns: the document on which the method was called

Throws: IllegalAddException if the given child already has a parent.

addContent

public Document addContent(Collection c)
Appends all children in the given collection to the end of the content list. In event of an exception during add the original content will be unchanged and the objects in the supplied collection will be unaltered.

Parameters: c collection to append

Returns: the document on which the method was called

Throws: IllegalAddException if any item in the collection already has a parent or is of an illegal type.

addContent

public Document addContent(int index, Content child)
Inserts the child into the content list at the given index.

Parameters: index location for adding the collection child child to insert

Returns: the parent on which the method was called

Throws: IndexOutOfBoundsException if index is negative or beyond the current number of children IllegalAddException if the given child already has a parent.

addContent

public Document addContent(int index, Collection c)
Inserts the content in a collection into the content list at the given index. In event of an exception the original content will be unchanged and the objects in the supplied collection will be unaltered.

Parameters: index location for adding the collection c collection to insert

Returns: the parent on which the method was called

Throws: IndexOutOfBoundsException if index is negative or beyond the current number of children IllegalAddException if any item in the collection already has a parent or is of an illegal type.

clone

public Object clone()
This will return a deep clone of this Document.

Returns: Object clone of this Document

cloneContent

public List cloneContent()

detachRootElement

public Element detachRootElement()
Detach the root Element from this document.

Returns: removed root Element

equals

public final boolean equals(Object ob)
This tests for equality of this Document to the supplied Object.

Parameters: ob Object to compare to

Returns: boolean whether the Document is equal to the supplied Object

getBaseURI

public final String getBaseURI()

Returns the URI from which this document was loaded, or null if this is not known.

Returns: the base URI of this document

getContent

public Content getContent(int index)

getContent

public 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 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

getContentSize

public int getContentSize()

getDescendants

public Iterator getDescendants()
Returns an iterator that walks over all descendants in document order.

Returns: an iterator to walk descendants

getDescendants

public Iterator getDescendants(Filter filter)
Returns an iterator that walks over all descendants in document order applying the Filter to return only elements that match the filter rule. With filters you can match only Elements, only Comments, Elements or Comments, only Elements with a given name and/or prefix, and so on.

Parameters: filter filter to select which descendants to see

Returns: an iterator to walk descendants within a filter

getDocType

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

Returns: DocType - the DOCTYPE declaration.

getDocument

public Document getDocument()

See Also: getDocument

getParent

public Parent getParent()

getProperty

public Object getProperty(String id)
Returns the object associated with this document under the given "id" string, or null if there is no binding or if the binding explicitly stored a null value.

Parameters: id the id of the stored object to return

Returns: the object associated with the given id

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

hashCode

public final int hashCode()
This returns the hash code for this Document.

Returns: int hash code

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.

indexOf

public int indexOf(Content child)

removeContent

public List removeContent()
Removes all child content from this parent.

Returns: list of the old children detached from this parent

removeContent

public List removeContent(Filter filter)
Remove all child content from this parent matching the supplied filter.

Parameters: filter filter to select which content to remove

Returns: list of the old children detached from this parent

removeContent

public boolean removeContent(Content child)

removeContent

public Content removeContent(int index)

setBaseURI

public final void setBaseURI(String uri)

Sets the effective URI from which this document was loaded, and against which relative URLs in this document will be resolved.

Parameters: uri the base URI of this document

setContent

public Document setContent(Collection 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 Document) 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 Document 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 or with existing parentage.

setContent

public Document setContent(int index, Content child)

setContent

public Document setContent(int index, Collection collection)
Replace the child at the given index whith the supplied collection.

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

Parameters: index - index of child to replace. collection - collection of content to add.

Returns: object on which the method was invoked

Throws: IllegalAddException if the collection contains objects of illegal types. IndexOutOfBoundsException if index is negative or greater than the current number of children.

setContent

public Document setContent(Content child)
Set this document's content to be the supplied child.

If the supplied child is legal content for a Document and before it is added, all content in the current content list will be cleared and all current children will have their parentage set to null.

This has the effect that any active list (previously obtained with a call to one of the Document methods will also change to reflect the new content. In addition, all content in the supplied collection will have their parentage set to this Document. If the user wants to continue working with a "live" list of this Document's child, then a call to setContent should be followed by a call to one of the Document methods to obtain a "live" version of the children.

Passing a null child clears the existing content.

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

Parameters: child new content to replace existing content

Returns: the parent on which the method was called

Throws: IllegalAddException if the supplied child is already attached or not legal content for this parent

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.

Returns: object on which the method was invoked

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

setProperty

public void setProperty(String id, Object value)
Assigns an arbitrary object to be associated with this document under the given "id" string. Null values are permitted. Strings beginning with "http://www.jdom.org/ are reserved for JDOM use.

Parameters: id the id of the stored object value the object to store

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.

toString

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

Returns: String - information about the Document

Copyright B) 2004 Jason Hunter, Brett McLaughlin. All Rights Reserved.