Package org.jdom

Class Document

java.lang.Object
org.jdom.Document
All Implemented Interfaces:
Serializable, Cloneable, Parent
public class Document extends 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.85 $, $Date: 2007/11/10 05:28:58 $
Author:
Brett McLaughlin, Jason Hunter, Jools Enticknap, Bradley S. Huffman
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected String
    baseURI
    See http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030226/core.html#baseURIs-Considerations

  • Constructor Summary

    Constructors
    Constructor
    Description
    Document()
    Creates a new empty document.
    Document(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(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, 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.

  • Method Summary

    Modifier and Type
    Method
    Description
    Document
    addContent(int index, Collection c)
    Inserts the content in a collection into the content list at the given index.
    Document
    addContent(int index, Content child)
    Inserts the child into the content list at the given index.
    Document
    addContent(Collection c)
    Appends all children in the given collection to the end of the content list.
    Document
    addContent(Content child)
    Appends the child to the end of the content list.
    Object
    clone()
    This will return a deep clone of this Document.
    List
    cloneContent()
    Returns a list containing detached clones of this parent's content list.
    Element
    detachRootElement()
    Detach the root Element from this document.
    final boolean
    equals(Object ob)
    This tests for equality of this Document to the supplied Object.
    final String
    getBaseURI()
    Returns the URI from which this document was loaded, or null if this is not known.
    List
    getContent()
    This will return all content for the Document.
    Content
    getContent(int index)
    Returns the child at the given index.
    List
    getContent(Filter filter)
    Return a filtered view of this Document's content.
    int
    getContentSize()
    Returns the number of children in this parent's content list.
    Iterator
    getDescendants()
    Returns an iterator that walks over all descendants in document order.
    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.
    Object
    getProperty(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
    final 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.
    List
    removeContent()
    Removes all child content from this parent.
    Content
    removeContent(int index)
    Removes and returns the child at the given index, or returns null if there's no such child.
    boolean
    removeContent(Content child)
    Removes a single child node from the content list.
    List
    removeContent(Filter filter)
    Remove all child content from this parent matching the supplied filter.
    final void
    setBaseURI(String uri)
    Sets the effective URI from which this document was loaded, and against which relative URLs in this document will be resolved.
    Document
    setContent(int index, Collection collection)
    Replace the child at the given index whith the supplied collection.
    Document
    setContent(int index, Content child)
     
    Document
    setContent(Collection newContent)
    This sets the content of the Document.
    Document
    setContent(Content child)
    Set this document's content to be the supplied child.
    Document
    setDocType(DocType docType)
    This will set the DocType declaration for this Document.
    void
    setProperty(String id, 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.
    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 Details

    • baseURI

      protected String baseURI
      See http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030226/core.html#baseURIs-Considerations

  • Constructor Details

    • 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, 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(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. A null list is treated the same as the no-arg constructor.
      Parameters:
      content - List of starter content
      Throws:
      IllegalAddException - if the List contains more than one Element or objects of illegal types.

  • Method Details

    • 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:
      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.
      Returns:
      object on which the method was invoked
      Throws:
      IllegalAddException - if the given docType is already attached to a Document.

    • addContent

      public Document 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 document on which the method was called
      Throws:
      IllegalAddException - if the given child already has a parent.

    • addContent

      public Document addContent(Collection c)
      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:
      c - collection to append
      Returns:
      the document on which the method was called
      Throws:
      IllegalAddException - if any item in the collection already has a parent or is of an illegal type.

    • addContent

      public Document addContent(int index, Content child)
      Inserts the child into the content list at the given index.
      Parameters:
      index - location for adding the collection
      child - child to insert
      Returns:
      the parent on which the method was called
      Throws:
      IndexOutOfBoundsException - if index is negative or beyond the current number of children
      IllegalAddException - if the given child already has a parent.

    • addContent

      public Document addContent(int index, Collection c)
      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:
      index - location for adding the collection
      c - collection to insert
      Returns:
      the parent on which the method was called
      Throws:
      IndexOutOfBoundsException - if index is negative or beyond the current number of children
      IllegalAddException - if any item in the collection already has a parent or is of an illegal type.

    • cloneContent

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

      Specified by:
      getContent in interface Parent
      Parameters:
      filter - Filter to apply
      Returns:
      List - filtered Document content
      Throws:
      IllegalStateException - if the root element hasn't been set

    • removeContent

      public 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 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 select which content to remove
      Returns:
      list of the old children detached from this parent

    • setContent

      public Document setContent(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.

      Parameters:
      newContent - List of content to set
      Returns:
      this document modified
      Throws:
      IllegalAddException - if the List contains objects of illegal types or with existing parentage.

    • setBaseURI

      public final void setBaseURI(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 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 Document setContent(int index, Content child)

    • setContent

      public Document setContent(int index, 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.

      Parameters:
      index - - index of child to replace.
      collection - - collection of content to add.
      Returns:
      object on which the method was invoked
      Throws:
      IllegalAddException - if the collection contains objects of illegal types.
      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 Document setContent(Content child)
      Set this document's content to be the supplied child.

      If the supplied child is legal content for a Document 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 Document. If the user wants to continue working with a "live" list of this Document'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

    • toString

      public 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 Object
      Returns:
      String - information about the Document

    • equals

      public final boolean equals(Object ob)
      This tests for equality of this Document to the supplied Object.
      Overrides:
      equals in class 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 Object
      Returns:
      int hash code

    • clone

      public Object clone()
      This will return a deep clone of this Document.
      Specified by:
      clone in interface Parent
      Overrides:
      clone in class Object
      Returns:
      Object clone of this Document

    • getDescendants

      public 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 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
      Parameters:
      filter - filter to select which descendants to see
      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:

    • setProperty

      public void setProperty(String id, Object value)
      Assigns an arbitrary object to be associated with this document under the given "id" string. Null values are permitted. Strings beginning with "http://www.jdom.org/ are reserved for JDOM use.
      Parameters:
      id - the id of the stored object
      value - the object to store

    • getProperty

      public Object getProperty(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