Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JDOM 1.0beta10
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.jdom
Interface Parent

All Superinterfaces:
  java.lang.Cloneable, java.io.Serializable

All Known Implementing Classes:
  Document, Element

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

Superclass for JDOM objects which are allowed to contain `Content` content.

Version:
  $Revision: 1.9 $, $Date: 2004/02/06 09:28:30 $
Author:
  Bradley S. Huffman, Jason Hunter
See Also:
  `Content`, `Document`, `Element`

Method Summary
`Parent` | `addContent(java.util.Collection collection)` Appends all children in the given collection to the end of the content list.
`Parent` | `addContent(Content child)` Appends the child to the end of the content list.
`Parent` | `addContent(int index, java.util.Collection collection)` 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()` Obtain a deep, unattached copy of this parent and it's children.
`java.util.List` | `cloneContent()` Returns a list containing detached clones of this parent's content list.
`java.util.List` | `getContent()` Returns the full content of this parent as a `List` which contains objects of type `Content`.
`java.util.List` | `getContent(Filter 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.
`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.
`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` | `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.
`java.util.List` | `removeContent(Filter 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.
`Parent` | `setContent(java.util.Collection collection)` Sets this parent's content to the supplied content list.
`Parent` | `setContent(Content child)` Set this parent's content to the supplied child.
`Parent` | `setContent(int index, java.util.Collection collection)` Replaces 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.

Method Detail

### getContentSize

    public int getContentSize()

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

  Returns:
    number of children

### indexOf

    public 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

### addContent

    public Parent 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 parent on which the method was called

### addContent

    public Parent addContent(java.util.Collection collection)

  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:
    `collection` - collection to append
  Returns:
    the parent on which the method was called

### addContent

    public Parent addContent(int index,
                             Content child)

  Inserts the child into the content list at the given index.

  Parameters:
    `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

### addContent

    public Parent addContent(int index,
                             java.util.Collection collection)

  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:
    `collection` - 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

### cloneContent

    public java.util.List cloneContent()

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

  Returns:
    list of cloned child content

### getContent

    public 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

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

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

  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

    public java.util.List removeContent()

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

  Returns:
    list of the old content detached from this parent

### removeContent

    public java.util.List removeContent(Filter filter)

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

  Parameters:
    `filter` - filter to apply
  Returns:
    list of the detached children matching the filter

### removeContent

    public boolean removeContent(Content child)

  Removes a single child node from the content list.

  Parameters:
    `child` - child to remove
  Returns:
    whether the removal occurred

### removeContent

    public 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

### setContent

    public Parent setContent(Content child)

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

### setContent

    public Parent setContent(java.util.Collection collection)

  Sets this parent's content to the supplied content list. The supplied collection must contain only objects of type `Content`.

  If the supplied content 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 `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 `getContent(int)` methods to obtain a "live" version of the children.

  Passing a null or empty Collection clears the existing content.

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

  Parameters:
    `collection` - new collection of content to replace existing content
  Returns:
    the parent on which the method was called
  Throws:
    `IllegalAddException` - if any object in the supplied content is already attached or not legal content for this parent

### setContent

    public Parent setContent(int index,
                             Content child)

  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.

  Parameters:
    `index` - index of child to replace
    `child` - new content to replace the 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
    `java.lang.IndexOutOfBoundsException` - if index is negative or beyond the current number of children

### setContent

    public Parent setContent(int index,
                             java.util.Collection collection)

  Replaces 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:
    the parent on which the method was called
  Throws:
    `IllegalAddException` - if any object in the supplied content is already attached or not legal content for this parent
    `java.lang.IndexOutOfBoundsException` - if index is negative or beyond the current number of children

### clone

    public 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

    public java.util.Iterator getDescendants()

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

  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.

  Returns:
    an iterator to walk descendants that match a filter

### getParent

    public 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

    public 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

### canContain

    public void canContain(Content child,
                           int index)
                    throws IllegalAddException

  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.

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JDOM 1.0beta10
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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