org.jdom2

Class Document

java.lang.Object

org.jdom2.Document

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, NamespaceAware, Parent

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.

Author:

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

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	baseURI See http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030226/core.html#baseURIs-Considerations

Constructor Summary

Constructors

Constructor and Description
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<? extends Content> 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

Modifier and Type	Method and Description
Document	addContent(java.util.Collection<? extends Content> c) Appends all children in the given collection to the end of the content list.
Document	addContent(Content child) Appends the child to the end of the content list.
Document	addContent(int index, java.util.Collection<? extends Content> c) Inserts the content in a collection into the content list at the given index.
Document	addContent(int index, Content child) Inserts the child into the content list at the given index.
void	canContainContent(Content child, int index, boolean replace) Test whether this Parent instance can contain the specified content at the specified position.
Document	clone() This will return a deep clone of this Document.
java.util.List<Content>	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<Content>	getContent() This will return all content for the Document.
<F extends Content> java.util.List<F>	getContent(Filter<F> 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.
IteratorIterable<Content>	getDescendants() Returns an iterator that walks over all descendants in document order.
<F extends Content> IteratorIterable<F>	getDescendants(Filter<F> 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() Always returns this Document Instance
java.util.List<Namespace>	getNamespacesInherited() Obtain a list of all namespaces that are in scope for this content, but were not introduced by this content.
java.util.List<Namespace>	getNamespacesInScope() Get the Namespaces that are in-scope on this Document.
java.util.List<Namespace>	getNamespacesIntroduced() Obtain a list of all namespaces that are introduced to the XML tree by this node.
Parent	getParent() Always returns null, Document cannot have a 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<Content>	removeContent() Removes all child content from this parent.
boolean	removeContent(Content child) Removes a single child node from the content list.
<F extends Content> java.util.List<F>	removeContent(Filter<F> 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.
Document	setContent(java.util.Collection<? extends Content> newContent) This sets the content of the Document.
Document	setContent(Content child) Set this document's content to be the supplied child.
Document	setContent(int index, java.util.Collection<? extends Content> collection) Replace the child at the given index with the supplied collection.
Document	setContent(int index, Content child) Replace 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

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,
                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 document 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<? extends Content> 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

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.

Returns:

object on which the method was invoked

Throws:

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

addContent

public Document addContent(Content child)

Appends the child to the end of the content list.

Specified by:

addContent in interface Parent

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(java.util.Collection<? extends Content> 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.

Specified by:

addContent in interface Parent

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.

Specified by:

addContent in interface Parent

Parameters:

index - location for adding the collection

child - child to insert

Returns:

the parent on which the method was called

Throws:

java.lang.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,
                           java.util.Collection<? extends Content> 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.

Specified by:

addContent in interface Parent

Parameters:

index - location for adding the collection

c - collection to insert

Returns:

the parent on which the method was called

Throws:

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

cloneContent

public java.util.List<Content> 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<Content> 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 <F extends Content> java.util.List<F> getContent(Filter<F> 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

Type Parameters:

F - The Generic type of the returned content (the Filter's type)

Parameters:

filter - Filter to apply Note that the Filters class has a number of predefined, useful filters.

Returns:

List - filtered Document content

Throws:

java.lang.IllegalStateException - if the root element hasn't been set

removeContent

public java.util.List<Content> 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 <F extends Content> java.util.List<F> removeContent(Filter<F> filter)

Remove all child content from this parent matching the supplied filter.

Specified by:

removeContent in interface Parent

Type Parameters:

F - The Generic type of the content to remove.

Parameters:

filter - filter to select which content to remove Note that the Filters class has a number of predefined, useful filters.

Returns:

list of the old children detached from this parent

setContent

public Document setContent(java.util.Collection<? extends Content> 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.

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.

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 Document setContent(int index,
                           Content child)

Replace 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.

Parameters:

index - - index of child to replace.

child - - child to add.

Returns:

this document instance

Throws:

IllegalAddException - if the supplied child is already attached or not legal content for this parent.

java.lang.IndexOutOfBoundsException - if index is negative or greater than the current number of children.

setContent

public Document setContent(int index,
                           java.util.Collection<? extends Content> collection)

Replace the child at the given index with 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.

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

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

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 Document clone()

This will return a deep clone of this Document.

Specified by:

clone in interface Parent

Returns:

Object clone of this Document

getDescendants

public IteratorIterable<Content> 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 <F extends Content> IteratorIterable<F> getDescendants(Filter<F> 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

Type Parameters:

F - The generic type of the returned descendant data

Parameters:

filter - filter to select which descendants to see Note that the Filters class has a number of predefined, useful filters.

Returns:

an iterator to walk descendants within a filter

getParent

public Parent getParent()

Always returns null, Document cannot have a parent.

Specified by:

getParent in interface Parent

Returns:

null

getDocument

public Document getDocument()

Always returns this Document Instance

Specified by:

getDocument in interface Parent

Returns:

'this' because this Document is its own Document

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. 'id' Strings beginning with "http://www.jdom.org/ are reserved for JDOM use. Properties set with this method will not be serialized with the rest of this Document, should serialization need to be done.

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

canContainContent

public void canContainContent(Content child,
                              int index,
                              boolean replace)

Description copied from interface: Parent

Test whether this Parent instance can contain the specified content at the specified position.

Specified by:

canContainContent in interface Parent

Parameters:

child - The content to be checked

index - The location where the content would be put.

replace - true if the intention is to replace the content already at the index.

getNamespacesInScope

public java.util.List<Namespace> getNamespacesInScope()

Get the Namespaces that are in-scope on this Document.

Document always has exactly two Namespaces in-scope: Namespace.NO_NAMESPACE and Namespace.XML_NAMESPACE.

These namespaces are always introduced by the Document, and thus they are both returned by getNamespacesIntroduced(), and additionally getNamespacesInherited() will always be empty.

Description copied from NamespaceAware.getNamespacesInScope():

Obtain a list of all namespaces that are in scope for the current content.

The contents of this list will always be the combination of getNamespacesIntroduced() and getNamespacesInherited().

See NamespaceAware documentation for details on what the order of the Namespaces will be in the returned list.

Specified by:

getNamespacesInScope in interface NamespaceAware

Returns:

a read-only list of Namespaces.

getNamespacesIntroduced

public java.util.List<Namespace> getNamespacesIntroduced()

Description copied from interface: NamespaceAware

Obtain a list of all namespaces that are introduced to the XML tree by this node. Only Elements and Attributes can introduce namespaces, so all other Content types will return an empty list.

The contents of this list will always be a subset (but in the same order) of getNamespacesInScope(), and will never intersect getNamspacesInherited()

Specified by:

getNamespacesIntroduced in interface NamespaceAware

Returns:

a read-only list of Namespaces.

getNamespacesInherited

public java.util.List<Namespace> getNamespacesInherited()

Description copied from interface: NamespaceAware

Obtain a list of all namespaces that are in scope for this content, but were not introduced by this content.

The contents of this list will always be a subset (but in the same order) of getNamespacesInScope(), and will never intersect getNamspacesIntroduced()

Specified by:

getNamespacesInherited in interface NamespaceAware

Returns:

a read-only list of Namespaces.