## org.jdom
Class Document

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

public class Document
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

`Document` defines behavior for an XML Document, modeled in Java. Methods allow access to the root element as well as processing instructions and other document-level information.

Version:
  $Revision: 1.55 $, $Date: 2002/03/28 11:08:12 $
Author:
  Brett McLaughlin, Jason Hunter, Jools Enticknap, Bradley S. Huffman
See Also:
  Serialized Form

Field Summary
`protected org.jdom.ContentList` `content` This `Document`'s ``Comment``s, ``ProcessingInstruction``s and the root ``Element``.
`protected DocType` `docType` The ``DocType`` declaration.

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(java.util.List content)` This will create a new `Document`, with the supplied list of content, and no ``DocType`` declaration.
`Document(java.util.List newContent, DocType docType)` This will create a new `Document`, with the supplied list of content, and the supplied ``DocType`` declaration.

Method Summary
`Document` `addContent(Comment comment)` This will add a comment to the `Document`.
`Document` `addContent(ProcessingInstruction pi)` Adds the specified PI to the document.
`java.lang.Object` `clone()` This will return a deep clone of this `Document`.
`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.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.
`DocType` `getDocType()` This will return the ``DocType`` declaration for this `Document`, or `null` if none exists.
`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.
`boolean` `removeContent(Comment comment)` This removes the specified `Comment`.
`boolean` `removeContent(ProcessingInstruction pi)` This removes the specified `ProcessingInstruction`.
`Document` `setContent(java.util.List newContent)` This sets the content of the `Document`.
`Document` `setDocType(DocType docType)` This will set the ``DocType`` declaration for this `Document`.
`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

### content

    protected org.jdom.ContentList content

  This `Document`'s ``Comment``s, ``ProcessingInstruction``s and the root ``Element``.

### docType

    protected DocType docType

  The ``DocType`` declaration.

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)

  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.

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

### Document

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

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

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

### Document

    public Document(java.util.List content)

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

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

Method Detail

### 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:
    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 Document addContent(ProcessingInstruction pi)

  Adds the specified PI to the document.

  Parameters:
    `pi` - the ProcessingInstruction to add.
  Returns:
    `Document` this document modified.
  Throws:
    IllegalAddException - if the given processing instruction already has a parent element.

### addContent

    public Document addContent(Comment comment)

  This will add a comment to the `Document`.

  Parameters:
    `comment` - `Comment` to add.
  Returns:
    `Document` - this object modified.
  Throws:
    IllegalAddException - if the given comment already has a parent element.

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

  Returns:
    `List` - all Document content
  Throws:
    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.

  Parameters:
    `filter` - `Filter` to apply
  Returns:
    `List` - filtered Document content
  Throws:
    IllegalStateException - if the root element hasn't been set

### setContent

    public Document setContent(java.util.List 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()`) 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()` 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.

  Returns:
    this document modified
  Throws:
    IllegalAddException - if the List contains objects of illegal types.

### removeContent

    public boolean removeContent(ProcessingInstruction pi)

  This removes the specified `ProcessingInstruction`. If the specified `ProcessingInstruction` is not a child of this `Document`, this method does nothing.

  Parameters:
    `child` - `ProcessingInstruction` to delete
  Returns:
    whether deletion occurred

### removeContent

    public boolean removeContent(Comment comment)

  This removes the specified `Comment`. If the specified `Comment` is not a child of this `Document`, this method does nothing.

  Parameters:
    `comment` - `Comment` to delete
  Returns:
    whether deletion occurred

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

  Overrides:
    clone in class java.lang.Object
  Returns:
    `Object` - clone of this `Document`.

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