    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Class org.jdom.Document

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

public class Document
extends Object
implements Serializable, 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

##

content
  This `Document`'s `{`
docType
  The `{`

##

Document()

  Creates a new empty document.

Document(Element)

  This will create a new `Document`, with the supplied `{`

Document(Element, DocType)

  This will create a new `Document`, with the supplied `{`

Document(List)

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

Document(List, DocType)

  This will create a new `Document`, with the supplied list of content, and the supplied `{`

##

addContent(Comment)

  This will add a comment to the `Document`.

addContent(ProcessingInstruction)

  Adds the specified PI to the document.

clone()

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

detachRootElement()

  Detach the root `{`

equals(Object)

  This tests for equality of this `Document` to the supplied `Object`.

getContent()

  This will return all content for the `Document`.

getContent(Filter)

  Return a filtered view of this `Document`'s content.

getDocType()

  This will return the `{`

getRootElement()

  This will return the root `Element` for this `Document`

hashCode()

  This returns the hash code for this `Document`.

hasRootElement()

  This will return `true` if this document has a root element, `false` otherwise.

removeContent(Comment)

  This removes the specified `Comment`.

removeContent(ProcessingInstruction)

  This removes the specified `ProcessingInstruction`.

setContent(List)

  This sets the content of the `Document`.

setDocType(DocType)

  This will set the `{`

setRootElement(Element)

  This sets the root `{`

toString()

  This returns a `String` representation of the `Document`, suitable for debugging.

##

content

     protected ContentList content

  This `Document`'s `{@link Comment}`s, `{@link ProcessingInstruction}`s and the root `{@link Element}`.

docType

     protected DocType docType

  The `{@link DocType}` declaration.

##

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 `{@link Element}` as the root element and the supplied `{@link 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 `{@link Element}` as the root element, and no `{@link DocType}` declaration.

  Parameters:
    rootElement - `Element` for document root

Document

     public Document(List newContent,
                     DocType docType)

  This will create a new `Document`, with the supplied list of content, and the supplied `{@link 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(List content)

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

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

##

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 `{@link 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 `{@link Element}` from this document.

  Returns:
    removed root `Element`

getDocType

     public DocType getDocType()

  This will return the `{@link 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 `{@link 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 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 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(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 {@link #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 {@link #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 String toString()

  This returns a `String` representation of the `Document`, suitable for debugging. If the XML representation of the `Document` is desired, {@link org.jdom.output.XMLOutputter#outputString(Document)} should be used.

  Returns:
    `String` - information about the `Document`
  Overrides:
    toString in class Object

equals

     public final boolean equals(Object ob)

  This tests for equality of this `Document` to the supplied `Object`.

  Parameters:
    ob - `Object` to compare to.
  Returns:
    `boolean` - whether the `Document` is equal to the supplied `Object`.
  Overrides:
    equals in class Object

hashCode

     public final int hashCode()

  This returns the hash code for this `Document`.

  Returns:
    `int` - hash code.
  Overrides:
    hashCode in class Object

clone

     public Object clone()

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

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

    All Packages  Class Hierarchy  This Package  Previous  Next  Index