Class Document
- java.lang.Object
-
- org.jdom.Document
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Cloneable
,Parent
public class Document extends java.lang.Object implements Parent
An XML document. Methods allow access to the root element as well as theDocType
and other document-level information.- Version:
- $Revision: 1.85 $, $Date: 2007/11/10 05:28:58 $
- Author:
- Brett McLaughlin, Jason Hunter, Jools Enticknap, Bradley S. Huffman
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field 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 Description Document()
Creates a new empty document.Document(java.util.List content)
This will create a newDocument
, with the supplied list of content, and a
declaration only if the content contains a DocType instance.DocType
Document(Element rootElement)
Document(Element rootElement, DocType docType)
Document(Element rootElement, DocType docType, java.lang.String baseURI)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Document
addContent(int index, java.util.Collection 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.Document
addContent(java.util.Collection 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.java.lang.Object
clone()
This will return a deep clone of thisDocument
.java.util.List
cloneContent()
Returns a list containing detached clones of this parent's content list.Element
detachRootElement()
Detach the root
from this document.Element
boolean
equals(java.lang.Object ob)
This tests for equality of thisDocument
to the suppliedObject
.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 theDocument
.Content
getContent(int index)
Returns the child at the given index.java.util.List
getContent(Filter filter)
Return a filtered view of thisDocument
's content.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()
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 rootElement
for thisDocument
int
hashCode()
This returns the hash code for thisDocument
.boolean
hasRootElement()
This will returntrue
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.Content
removeContent(int index)
Removes and returns the child at the given index, or returns null if there's no such child.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.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(int index, java.util.Collection collection)
Replace the child at the given index whith the supplied collection.Document
setContent(int index, Content child)
Document
setContent(java.util.Collection newContent)
This sets the content of theDocument
.Document
setContent(Content child)
Set this document's content to be the supplied child.Document
setDocType(DocType docType)
This will set the
declaration for thisDocType
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
for theElement
Document
.java.lang.String
toString()
This returns aString
representation of theDocument
, suitable for debugging.
-
-
-
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 newDocument
, with the supplied
as the root element, the suppliedElement
declaration, and the specified base URI.DocType
- 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 newDocument
, with the supplied
as the root element and the suppliedElement
declaration.DocType
- 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 newDocument
, with the supplied
as the root element, and noElement
declaration.DocType
- 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 newDocument
, with the supplied list of content, and a
declaration only if the content contains a DocType instance. A null list is treated the same as the no-arg constructor.DocType
- 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 anyContent
type.- Specified by:
getContentSize
in interfaceParent
- 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.
-
hasRootElement
public boolean hasRootElement()
This will returntrue
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 rootElement
for thisDocument
- 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
for theElement
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
from this document.Element
- Returns:
- removed root
Element
-
getDocType
public DocType getDocType()
- Returns:
DocType
- the DOCTYPE declaration.
-
setDocType
public Document setDocType(DocType docType)
This will set the
declaration for thisDocType
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.- 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 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 collectionchild
- 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 childrenIllegalAddException
- if the given child already has a parent.
-
addContent
public Document addContent(int index, java.util.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 collectionc
- 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 childrenIllegalAddException
- if any item in the collection already has a parent or is of an illegal type.
-
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 interfaceParent
- 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 interfaceParent
- Parameters:
index
- location of desired child- Returns:
- child at the given index
-
getContent
public java.util.List getContent()
This will return all content for theDocument
. 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 interfaceParent
- 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 thisDocument
'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 interfaceParent
- 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 interfaceParent
- 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 interfaceParent
- Parameters:
filter
- filter to select which content to remove- Returns:
- list of the old children detached from this parent
-
setContent
public Document setContent(java.util.Collection newContent)
This sets the content of theDocument
. The supplied List should contain only objects of typeElement
,Comment
, andProcessingInstruction
.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 togetContent(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, 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.
- 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 interfaceParent
- 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 interfaceParent
- 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 thegetContent(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 aString
representation of theDocument
, suitable for debugging. If the XML representation of theDocument
is desired,XMLOutputter.outputString(Document)
should be used.- Overrides:
toString
in classjava.lang.Object
- Returns:
String
- information about theDocument
-
equals
public final boolean equals(java.lang.Object ob)
This tests for equality of thisDocument
to the suppliedObject
.- Overrides:
equals
in classjava.lang.Object
- Parameters:
ob
-Object
to compare to- Returns:
boolean
whether theDocument
is equal to the suppliedObject
-
hashCode
public final int hashCode()
This returns the hash code for thisDocument
.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
int
hash code
-
clone
public java.lang.Object clone()
This will return a deep clone of thisDocument
.
-
getDescendants
public java.util.Iterator getDescendants()
Returns an iterator that walks over all descendants in document order.- Specified by:
getDescendants
in interfaceParent
- 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 interfaceParent
- Parameters:
filter
- filter to select which descendants to see- 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.
-
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 interfaceParent
- Returns:
- this child's owning document or null if none
- See Also:
Parent.getDocument()
-
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. Strings beginning with "http://www.jdom.org/ are reserved for JDOM use.- Parameters:
id
- the id of the stored objectvalue
- 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
-
-