JDOM
1.0beta10

org.jdom
Class Document

java.lang.Object
  extended byorg.jdom.Document
All Implemented Interfaces:
java.lang.Cloneable, Parent, java.io.Serializable

public class Document
extends java.lang.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.79 $, $Date: 2004/02/06 09:28:30 $
Author:
Brett McLaughlin, Jason Hunter, Jools Enticknap, Bradley S. Huffman
See Also:
Serialized Form

Field Summary
protected  java.lang.String baseURI
           
 
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(Element rootElement, DocType docType, java.lang.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(java.util.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.
Document(java.util.List newContent, DocType docType)
          Deprecated. Deprecated in beta10 because the DocType is now part of the content list itself
 
Method Summary
 Parent addContent(java.util.Collection c)
          Appends all children in the given collection to the end of the content list.
 Parent addContent(Content child)
          Adds the specified PI to the document.
 Parent addContent(int index, java.util.Collection c)
          Inserts the content in a collection into the content list at the given index.
 Parent addContent(int index, Content child)
          Inserts the child into the content list at the given index.
 void canContain(Content child, int index)
          Checks if this parent can contain the given child at the specified position, throwing a descriptive IllegalAddException if not and simply returning if it's allowed.
 java.lang.Object clone()
          This will return a deep clone of this Document.
 java.util.List cloneContent()
          Returns a list containing detached clones of this parent's content list.
 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.lang.String getBaseURI()
           Returns the URI from which this document was loaded, or null if this is not known.
 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.
 Content getContent(int index)
          Returns the child at the given index.
 int getContentSize()
          Returns the number of children in this parent's content list.
 java.util.Iterator getDescendants()
          Returns an iterator that walks over all descendants in document order.
 java.util.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.
 DocType getDocType()
          This will return the DocType declaration for this Document, or null if none exists.
 Document getDocument()
          Return this parent's owning document or null if the branch containing this parent is currently not attached to a document.
 Parent getParent()
          Return this parent's parent, or null if this parent is currently not attached to another parent.
 java.lang.Object getProperty(java.lang.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.
 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.
 int indexOf(Content child)
          Returns the index of the supplied child in the content list, or -1 if not a child of this parent.
 java.util.List removeContent()
          Removes all child content from this parent.
 boolean removeContent(Content child)
          Removes a single child node from the content list.
 java.util.List removeContent(Filter filter)
          Remove all child content from this parent matching the supplied filter.
 Content removeContent(int index)
          Removes and returns the child at the given index, or returns null if there's no such child.
 void setBaseURI(java.lang.String uri)
           Sets the effective URI from which this document was loaded, and against which relative URLs in this document will be resolved.
 Parent setContent(java.util.Collection newContent)
          This sets the content of the Document.
 Parent setContent(Content child)
          Set this parent's content to the supplied child.
 Parent setContent(int index, java.util.Collection collection)
          Replace the child at the given index whith the supplied collection.
 Parent setContent(int index, Content child)
          Replaces the current child the given index with the supplied child.
 Document setDocType(DocType docType)
          This will set the DocType declaration for this Document.
 void setProperty(java.lang.String id, java.lang.Object value)
          Assigns an arbitrary object to be associated with this document under the given "id" string.
 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

baseURI

protected java.lang.String baseURI
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,
                java.lang.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(java.util.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.

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

Document

public Document(java.util.List newContent,
                DocType docType)
Deprecated. Deprecated in beta10 because the DocType is now part of the content list itself

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

Parameters:
newContent - 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.
Method Detail

getContentSize

public int getContentSize()
Description copied from interface: Parent
Returns the number of children in this parent's content list. Children may be any Content type.

Specified by:
getContentSize in interface Parent
Returns:
number of children

indexOf

public int indexOf(Content child)
Description copied from interface: Parent
Returns the index of the supplied child in the content list, or -1 if not a child of this parent.

Specified by:
indexOf in interface Parent
Parameters:
child - child to search for
Returns:
index of child, or -1 if not found

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:
java.lang.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 Parent addContent(Content child)
Adds the specified PI to the document.

Specified by:
addContent in interface Parent
Parameters:
child - the Content to add
Returns:
Document this document modified.
Throws:
IllegalAddException - if the given processing instruction already has a parent element.

addContent

public Parent addContent(java.util.Collection c)
Description copied from interface: Parent
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.

Specified by:
addContent in interface Parent
Parameters:
c - collection to append
Returns:
the parent on which the method was called

addContent

public Parent addContent(int index,
                         Content child)
Description copied from interface: Parent
Inserts the child into the content list at the given index.

Specified by:
addContent in interface Parent
Parameters:
child - child to insert
Returns:
the parent on which the method was called

addContent

public Parent addContent(int index,
                         java.util.Collection c)
Description copied from interface: Parent
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.

Specified by:
addContent in interface Parent
Parameters:
c - collection to insert
Returns:
the parent on which the method was called

cloneContent

public java.util.List cloneContent()
Description copied from interface: Parent
Returns a list containing detached clones of this parent's content list.

Specified by:
cloneContent in interface Parent
Returns:
list of cloned child content

getContent

public Content getContent(int index)
Description copied from interface: Parent
Returns the child at the given index.

Specified by:
getContent in interface Parent
Parameters:
index - location of desired child
Returns:
child at the given index

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.

Specified by:
getContent in interface Parent
Returns:
List - all Document content
Throws:
java.lang.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.

Specified by:
getContent in interface Parent
Parameters:
filter - Filter to apply
Returns:
List - filtered Document content
Throws:
java.lang.IllegalStateException - if the root element hasn't been set

removeContent

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

Specified by:
removeContent in interface Parent
Returns:
list of the old children detached from this parent

removeContent

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

Specified by:
removeContent in interface Parent
Parameters:
filter - filter to apply
Returns:
list of the old children detached from this parent

setContent

public Parent setContent(java.util.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 getContent(int)) 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(int) 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.

Specified by:
setContent in interface Parent
Parameters:
newContent - List of content to set
Returns:
this document modified
Throws:
IllegalAddException - if the List contains objects of illegal types.

setBaseURI

public final void setBaseURI(java.lang.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

getBaseURI

public final java.lang.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

setContent

public Parent setContent(int index,
                         Content child)
Description copied from interface: Parent
Replaces the current child the given index with the supplied child.

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

Specified by:
setContent in interface Parent
Parameters:
index - index of child to replace
child - new content to replace the existing content
Returns:
the parent on which the method was called

setContent

public Parent setContent(int index,
                         java.util.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.

Specified by:
setContent in interface Parent
Parameters:
index - - index of child to replace.
collection - - collection of content to add.
Returns:
the parent on which the method was called
Throws:
IllegalAddException - if the collection contains objects of illegal types.
java.lang.IndexOutOfBoundsException - if index is negative or greater than the current number of children.

removeContent

public boolean removeContent(Content child)
Description copied from interface: Parent
Removes a single child node from the content list.

Specified by:
removeContent in interface Parent
Parameters:
child - child to remove
Returns:
whether the removal occurred

removeContent

public Content removeContent(int index)
Description copied from interface: Parent
Removes and returns the child at the given index, or returns null if there's no such child.

Specified by:
removeContent in interface Parent
Parameters:
index - index of child to remove
Returns:
detached child at given index or null if no

setContent

public Parent setContent(Content child)
Description copied from interface: Parent
Set this parent's content to the supplied child.

If the supplied child is legal content for this parent 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 Parent.getContent(int) methods will also change to reflect the new content. In addition, all content in the supplied collection will have their parentage set to this parent. If the user wants to continue working with a "live" list of this parent's child, then a call to setContent should be followed by a call to one of the Parent.getContent(int) 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.

Specified by:
setContent in interface Parent
Parameters:
child - new content to replace existing content
Returns:
the parent on which the method was called

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.

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.

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.

Returns:
int hash code

clone

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

Specified by:
clone in interface Parent
Returns:
Object clone of this Document

getDescendants

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

Specified by:
getDescendants in interface Parent
Returns:
an iterator to walk descendants

getDescendants

public java.util.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.

Specified by:
getDescendants in interface Parent
Returns:
an iterator to walk descendants within a filter

getParent

public Parent getParent()
Description copied from interface: Parent
Return this parent's parent, or null if this parent is currently not attached to another parent. This is the same method as in Content but also added to Parent to allow more easy up-the-tree walking.

Specified by:
getParent in interface Parent
Returns:
this parent's parent or null if none

getDocument

public Document getDocument()
Description copied from interface: Parent
Return this parent's owning document or null if the branch containing this parent is currently not attached to a document.

Specified by:
getDocument in interface Parent
Returns:
this child's owning document or null if none
See Also:
Parent.getDocument()

canContain

public void canContain(Content child,
                       int index)
                throws IllegalAddException
Description copied from interface: Parent
Checks if this parent can contain the given child at the specified position, throwing a descriptive IllegalAddException if not and simply returning if it's allowed.

Specified by:
canContain in interface Parent
Parameters:
child - the potential child to be added to this parent
index - the location for the potential child
Throws:
IllegalAddException - if the child add isn't allowed
See Also:
org.jdom.ContentList#add(int, org.jdom.Content)

setProperty

public void setProperty(java.lang.String id,
                        java.lang.Object value)
Assigns an arbitrary object to be associated with this document under the given "id" string. Null values are permitted.

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

getProperty

public java.lang.Object getProperty(java.lang.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

JDOM
1.0beta10

Copyright © 2004 Jason Hunter, Brett McLaughlin. All Rights Reserved.