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
Class Document

    java.lang.Object
      |
      +--org.jdom.Document

All Implemented Interfaces:
  java.lang.Cloneable, Parent, java.io.Serializable

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.

Version:
  $Revision: 1.79 $, $Date: 2004/02/06 09:28:30 $
Author:
  Brett McLaughlin, Jason Hunter, Jools Enticknap, Bradley S. Huffman
See Also:
  Serialized Form

Field Summary
`protected java.lang.String` | `baseURI`

Constructor Summary
`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 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.
`Document(java.util.List newContent, DocType docType)` Deprecated. Deprecated in beta10 because the DocType is now part of the content list itself

Method Summary
`Parent` | `addContent(java.util.Collection c)` Appends all children in the given collection to the end of the content list.
`Parent` | `addContent(Content child)` Adds the specified PI to the document.
`Parent` | `addContent(int index, java.util.Collection c)` 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()` This will return a deep clone of this `Document`.
`java.util.List` | `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` | `getContent()` This will return all content for the `Document`.
`java.util.List` | `getContent(Filter 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.
`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()` This will return the ``DocType`` declaration for this `Document`, or `null` if none exists.
`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 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` | `removeContent()` Removes all child content from this parent.
`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.
`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.
`Parent` | `setContent(java.util.Collection newContent)` This sets the content of the `Document`.
`Parent` | `setContent(Content child)` Set this parent's content to the supplied child.
`Parent` | `setContent(int index, java.util.Collection collection)` Replace 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.
`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

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

Parameters:
  `content` - `List` of starter content
Throws:
  `IllegalAddException` - if the List contains more than one Element or objects of illegal types.

### Document

    public Document(java.util.List newContent,
                    DocType docType)

  Deprecated. Deprecated in beta10 because the DocType is now part of the content list itself

  This will create a new `Document`, with the supplied list of content, and the supplied ``DocType`` declaration.

Parameters:
  `newContent` - `List` of starter content
  `docType` - `DocType` declaration.
Throws:
  `IllegalAddException` - if (1) the List contains more than one Element or objects of illegal types, or (2) if the given docType object is already attached to a document.

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.
  Throws:
    `IllegalAddException` - if the given docType is already attached to a Document.

### addContent

    public Parent addContent(Content child)

  Adds the specified PI to the document.

  Specified by:
    `addContent` in interface `Parent`
  Parameters:
    `child` - the Content to add
  Returns:
    `Document` this document modified.
  Throws:
    `IllegalAddException` - if the given processing instruction already has a parent element.

### addContent

    public Parent addContent(java.util.Collection c)

  Description copied from interface: `Parent`
  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 parent on which the method was called

### addContent

    public Parent addContent(int index,
                             Content child)

  Description copied from interface: `Parent`
  Inserts the child into the content list at the given index.

  Specified by:
    `addContent` in interface `Parent`
  Parameters:
    `child` - child to insert
  Returns:
    the parent on which the method was called

### addContent

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

  Description copied from interface: `Parent`
  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:
    `c` - collection to insert
  Returns:
    the parent on which the method was called

### 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 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 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 java.util.List getContent(Filter 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`
  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 interface `Parent`
  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 interface `Parent`
  Parameters:
    `filter` - filter to apply
  Returns:
    list of the old children detached from this parent

### setContent

    public Parent setContent(java.util.Collection 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.

  Specified by:
    `setContent` in interface `Parent`
  Parameters:
    `newContent` - `List` of content to set
  Returns:
    this document modified
  Throws:
    `IllegalAddException` - if the List contains objects of illegal types.

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

  Description copied from interface: `Parent`
  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.

  Specified by:
    `setContent` in interface `Parent`
  Parameters:
    `index` - index of child to replace
    `child` - new content to replace the existing content
  Returns:
    the parent on which the method was called

### setContent

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

  Specified by:
    `setContent` in interface `Parent`
  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 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 Parent setContent(Content child)

  Description copied from interface: `Parent`
  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 `Parent.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 `Parent.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.

  Specified by:
    `setContent` in interface `Parent`
  Parameters:
    `child` - new content to replace existing content
  Returns:
    the parent on which the method was called

### 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 java.lang.Object clone()

  This will return a deep clone of this `Document`.

  Specified by:
    `clone` in interface `Parent`
  Overrides:
    `clone` in class `java.lang.Object`
  Returns:
    `Object` clone of this `Document`

### getDescendants

    public java.util.Iterator 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 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 interface `Parent`
  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.

  Specified by:
    `getParent` in interface `Parent`
  Returns:
    this parent's parent or null if none

### 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 interface `Parent`
  Returns:
    this child's owning document or null if none
  See Also:
    `Parent.getDocument()`

### canContain

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

  Description copied from interface: `Parent`
  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.

  Specified by:
    `canContain` in interface `Parent`
  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
  See Also:
    `org.jdom.ContentList#add(int, org.jdom.Content)`

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

  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

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.