org.jdom2
Interface Parent

All Superinterfaces:

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

All Known Implementing Classes:

Document, Element, LocatedElement

public interface Parent
extends java.lang.Cloneable, NamespaceAware, java.io.Serializable

Interface for JDOM objects which are allowed to contain Content content - Element and Document.

Author:

Bradley S. Huffman, Jason Hunter, Rolf Lear

See Also:

Content, Document, Element

Method Summary

void	canContainContent(Content content, int index, boolean replace) Test whether this Parent instance can contain the specified content at the specified position.
java.lang.Object	clone() Obtain a deep, unattached copy of this parent and it's children.
java.util.List<Content>	cloneContent() Returns a list containing detached clones of this parent's content list.
java.util.List<Content>	getContent() Returns the full content of this parent as a List which contains objects of type Content.
<E extends Content> java.util.List<E>	getContent(Filter<E> filter) Returns as a List the content of this parent that matches the supplied filter.
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.
<E extends Content> IteratorIterable<E>	getDescendants(Filter<E> filter) Returns an Iterator that walks over all descendants in document order applying the Filter to return only content that match the filter rule.
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.
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 content from this parent and returns the detached children.
boolean	removeContent(Content child) Removes a single child node from the content list.
<E extends Content> java.util.List<E>	removeContent(Filter<E> filter) Removes from this parent all child content matching the given filter and returns a list of the detached children.
Content	removeContent(int index) Removes and returns the child at the given index, or returns null if there's no such child.

Methods inherited from interface org.jdom2.NamespaceAware

getNamespacesInherited, getNamespacesInScope, getNamespacesIntroduced

Method Detail

getContentSize

int getContentSize()

Returns the number of children in this parent's content list. Children may be any Content type.

Returns:

number of children

indexOf

int indexOf(Content child)

Returns the index of the supplied child in the content list, or -1 if not a child of this parent.

Parameters:

child - child to search for

Returns:

index of child, or -1 if not found

cloneContent

java.util.List<Content> cloneContent()

Returns a list containing detached clones of this parent's content list.

Returns:

list of cloned child content

getContent

Content getContent(int index)

Returns the child at the given index.

Parameters:

index - location of desired child

Returns:

child at the given index

Throws:

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

java.lang.IllegalStateException - if parent is a Document and the root element is not set

getContent

java.util.List<Content> getContent()

Returns the full content of this parent as a List which contains objects of type Content. The returned list is "live" and in document order. Any modifications to it affect the element's actual contents. Modifications are checked for conformance to XML 1.0 rules.

Sequential traversal through the List is best done with an Iterator since the underlying implement of List.size() may require walking the entire list and indexed lookups may require starting at the beginning each time.

Returns:

a list of the content of the parent

Throws:

java.lang.IllegalStateException - if parent is a Document and the root element is not set

getContent

<E extends Content> java.util.List<E> getContent(Filter<E> filter)

Returns as a List the content of this parent that matches the supplied filter. The returned list is "live" and in document order. Any modifications to it affect the element's actual contents. Modifications are checked for conformance to XML 1.0 rules.

Sequential traversal through the List is best done with an Iterator since the underlying implement of List.size() may require walking the entire list and indexed lookups may require starting at the beginning each time.

Type Parameters:

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

Parameters:

filter - filter to apply

Returns:

a list of the content of the parent matching the filter

Throws:

java.lang.IllegalStateException - if parent is a Document and the root element is not set

removeContent

java.util.List<Content> removeContent()

Removes all content from this parent and returns the detached children.

Returns:

list of the old content detached from this parent

removeContent

<E extends Content> java.util.List<E> removeContent(Filter<E> filter)

Removes from this parent all child content matching the given filter and returns a list of the detached children.

Type Parameters:

E - The Generic type of the content to remove.

Parameters:

filter - filter to apply

Returns:

list of the detached children matching the filter

removeContent

boolean removeContent(Content child)

Removes a single child node from the content list.

Parameters:

child - child to remove

Returns:

whether the removal occurred

removeContent

Content removeContent(int index)

Removes and returns the child at the given index, or returns null if there's no such child.

Parameters:

index - index of child to remove

Returns:

detached child at given index or null if no

Throws:

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

clone

java.lang.Object clone()

Obtain a deep, unattached copy of this parent and it's children.

Returns:

a deep copy of this parent and it's children.

getDescendants

IteratorIterable<Content> getDescendants()

Returns an Iterator that walks over all descendants in document order.

Note that this method returns an IteratorIterable instance, which means that you can use it either as an Iterator, or an Iterable, allowing both:

   for (Iterator it = parent.getDescendants();
           it.hasNext();) {
       Content c = it.next();
       ....
   }
 

and

   for (Content c : parent.getDescendants()) {
       ....
   }
 

The Iterator version is most useful if you need to do list modification on the iterator (using remove()), and for compatibility with JDOM 1.x

Returns:

an iterator to walk descendants

getDescendants

<E extends Content> IteratorIterable<E> getDescendants(Filter<E> filter)

Returns an Iterator that walks over all descendants in document order applying the Filter to return only content 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.

Note that this method returns an IteratorIterable instance, which means that you can use it either as an Iterator, or an Iterable, allowing both:

   for (Iterator it = parent.getDescendants(Filters.element());
           it.hasNext();) {
       Element e = it.next();
       ....
   }
 

and

   for (Element e : parent.getDescendants(Filters.element())) {
       ....
   }
 

The Iterator version is most useful if you need to do list modification on the iterator (using remove()), and for compatibility with JDOM 1.x

Type Parameters:

E - The generic type of the returned descendant data

Parameters:

filter - filter to select which descendants to see

Returns:

an iterator to walk descendants that match a filter

getParent

Parent getParent()

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.

Returns:

this parent's parent or null if none

getDocument

Document getDocument()

Return this parent's owning document or null if the branch containing this parent is currently not attached to a document.

Returns:

this child's owning document or null if none

canContainContent

void canContainContent(Content content,
                       int index,
                       boolean replace)
                       throws IllegalAddException

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

Parameters:

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

Throws:

IllegalAddException - if there is a problem with the content