Class Document
- All Implemented Interfaces:
Serializable
,Cloneable
,NamespaceAware
,Parent
DocType
and other document-level information.- Author:
- Brett McLaughlin, Jason Hunter, Jools Enticknap, Bradley S. Huffman, Rolf Lear
- See Also:
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionaddContent
(int index, Collection<? extends Content> c) Inserts the content in a collection into the content list at the given index.addContent
(int index, Content child) Inserts the child into the content list at the given index.addContent
(Collection<? extends Content> c) Appends all children in the given collection to the end of the content list.addContent
(Content child) Appends the child to the end of the content list.void
canContainContent
(Content child, int index, boolean replace) Test whether this Parent instance can contain the specified content at the specified position.clone()
This will return a deep clone of thisDocument
.Returns a list containing detached clones of this parent's content list.Detach the root
from this document.Element
final boolean
This tests for equality of thisDocument
to the suppliedObject
.final String
Returns the URI from which this document was loaded, or null if this is not known.This will return all content for theDocument
.getContent
(int index) Returns the child at the given index.getContent
(Filter<F> filter) Return a filtered view of thisDocument
's content.int
Returns the number of children in this parent's content list.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.Always returns this Document InstanceObtain a list of all namespaces that are in scope for this content, but were not introduced by this content.Get the Namespaces that are in-scope on this Document.Obtain a list of all namespaces that are introduced to the XML tree by this node.Always returns null, Document cannot have a parent.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.This will return the rootElement
for thisDocument
final int
hashCode()
This returns the hash code for thisDocument
.boolean
This will returntrue
if this document has a root element,false
otherwise.int
Returns the index of the supplied child in the content list, or -1 if not a child of this parent.Removes all child content from this parent.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.removeContent
(Filter<F> filter) Remove all child content from this parent matching the supplied filter.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.setContent
(int index, Collection<? extends Content> collection) Replace the child at the given index with the supplied collection.setContent
(int index, Content child) Replace the current child the given index with the supplied child.setContent
(Collection<? extends Content> newContent) This sets the content of theDocument
.setContent
(Content child) Set this document's content to be the supplied child.setDocType
(DocType docType) This will set the
declaration for thisDocType
Document
.void
setProperty
(String id, Object value) Assigns an arbitrary object to be associated with this document under the given "id" string.setRootElement
(Element rootElement) This sets the root
for theElement
Document
.toString()
This returns aString
representation of theDocument
, suitable for debugging.
-
Field Details
-
baseURI
See http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030226/core.html#baseURIs-Considerations
-
-
Constructor Details
-
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
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 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
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
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
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 Details
-
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
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
This will return the rootElement
for thisDocument
- Returns:
Element
- the document's root element- Throws:
IllegalStateException
- if the root element hasn't been set
-
setRootElement
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
Detach the root
from this document.Element
- Returns:
- removed root
Element
-
getDocType
- Returns:
DocType
- the DOCTYPE declaration.
-
setDocType
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
Appends the child to the end of the content list.- Specified by:
addContent
in interfaceParent
- 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
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 interfaceParent
- 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
Inserts the child into the content list at the given index.- Specified by:
addContent
in interfaceParent
- Parameters:
index
- location for adding the collectionchild
- child to insert- Returns:
- the parent on which the method was called
- Throws:
IndexOutOfBoundsException
- if index is negative or beyond the current number of childrenIllegalAddException
- if the given child already has a parent.
-
addContent
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 interfaceParent
- Parameters:
index
- location for adding the collectionc
- collection to insert- Returns:
- the parent on which the method was called
- Throws:
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
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
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
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:
IllegalStateException
- if the root element hasn't been set
-
getContent
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
- Type Parameters:
F
- The Generic type of the returned content (the Filter's type)- Parameters:
filter
-Filter
to apply Note that theFilters
class has a number of predefined, useful filters.- Returns:
List
- filtered Document content- Throws:
IllegalStateException
- if the root element hasn't been set
-
removeContent
Removes all child content from this parent.- Specified by:
removeContent
in interfaceParent
- Returns:
- list of the old children detached from this parent
-
removeContent
Remove all child content from this parent matching the supplied filter.- Specified by:
removeContent
in interfaceParent
- Type Parameters:
F
- The Generic type of the content to remove.- Parameters:
filter
- filter to select which content to remove Note that theFilters
class has a number of predefined, useful filters.- Returns:
- list of the old children detached from this parent
-
setContent
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
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
Returns the URI from which this document was loaded, or null if this is not known.
- Returns:
- the base URI of this document
-
setContent
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.IndexOutOfBoundsException
- if index is negative or greater than the current number of children.
-
setContent
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.IndexOutOfBoundsException
- if index is negative or greater than the current number of children.
-
removeContent
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
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
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
This returns aString
representation of theDocument
, suitable for debugging. If the XML representation of theDocument
is desired,XMLOutputter.outputString(Document)
should be used. -
equals
This tests for equality of thisDocument
to the suppliedObject
. -
hashCode
public final int hashCode()This returns the hash code for thisDocument
. -
clone
This will return a deep clone of thisDocument
. -
getDescendants
Returns an iterator that walks over all descendants in document order.- Specified by:
getDescendants
in interfaceParent
- Returns:
- an iterator to walk descendants
-
getDescendants
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
- Type Parameters:
F
- The generic type of the returned descendant data- Parameters:
filter
- filter to select which descendants to see Note that theFilters
class has a number of predefined, useful filters.- Returns:
- an iterator to walk descendants within a filter
-
getParent
Always returns null, Document cannot have a parent. -
getDocument
Always returns this Document Instance- Specified by:
getDocument
in interfaceParent
- Returns:
- 'this' because this Document is its own Document
-
setProperty
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 storedObject
value
- theObject
to store
-
getProperty
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 storedObject
to return- Returns:
- the
Object
associated with the given id
-
canContainContent
Description copied from interface:Parent
Test whether this Parent instance can contain the specified content at the specified position.- Specified by:
canContainContent
in interfaceParent
- Parameters:
child
- The content to be checkedindex
- The location where the content would be put.replace
- true if the intention is to replace the content already at the index.
-
getNamespacesInScope
Get the Namespaces that are in-scope on this Document.Document always has exactly two Namespaces in-scope:
Namespace.NO_NAMESPACE
andNamespace.XML_NAMESPACE
.These namespaces are always introduced by the Document, and thus they are both returned by
getNamespacesIntroduced()
, and additionallygetNamespacesInherited()
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 interfaceNamespaceAware
- Returns:
- a read-only list of Namespaces.
-
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 interfaceNamespaceAware
- Returns:
- a read-only list of Namespaces.
-
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 interfaceNamespaceAware
- Returns:
- a read-only list of Namespaces.
-