org.jdom
Class 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 the user to the root element as well as processing instructions and other document-level information.

Version:
1.0
Author:
Brett McLaughlin, Jason Hunter
See Also:
Serialized Form

Field Summary
protected  List content
          This Document's Comments, ProcessingInstructions and the root Element
protected  DocType docType
          The DocType declaration
 
Constructor Summary
protected Document()
           Default, no-args constructor for implementations to use if needed.
  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(List content)
           This will create a new Document, with the supplied list of content, and no DocType declaration.
  Document(List content, 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.
 Object clone()
           This will return a deep clone of this Document.
 boolean equals(Object ob)
           This tests for equality of this Document to the supplied Object.
 List getContent()
           This will return all content for the Document.
 DocType getDocType()
           This will return the DocType declaration for this Document, or null if none exists.
 List getMixedContent()
          Deprecated. Deprecated in beta7, use getContent() instead
 ProcessingInstruction getProcessingInstruction(String target)
          Deprecated. Deprecated in beta7, use getContent() and examine for PIs manually
 List getProcessingInstructions()
          Deprecated. Deprecated in beta7, use getContent() and examine for PIs manually
 List getProcessingInstructions(String target)
          Deprecated. Deprecated in beta7, use getContent() and examine for PIs manually
 Element getRootElement()
           This will return the root Element for this Document
 String getSerializedForm()
          Deprecated. Deprecated in beta7, use XMLOutputter.outputString(Document) instead
 int hashCode()
           This returns the hash code for this Document.
 boolean removeContent(Comment comment)
           This removes the specified Comment.
 boolean removeContent(ProcessingInstruction pi)
           This removes the specified ProcessingInstruction.
 boolean removeProcessingInstruction(String target)
          Deprecated. Deprecated in beta7, use getContent() and remove PIs manually
 boolean removeProcessingInstructions(String target)
          Deprecated. Deprecated in beta7, use getContent() and remove PIs manually
 Document setContent(List newContent)
           This will set all content for the Document.
 Document setDocType(DocType docType)
           This will set the DocType declaration for this Document.
 Document setMixedContent(List mixedContent)
          Deprecated. Deprecated in beta7, use setContent(List) instead
 Document setProcessingInstructions(List pis)
          Deprecated. Deprecated in beta7, use getContent() and add PIs manually
 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 Detail

content

protected List content
This Document's Comments, ProcessingInstructions and the root Element

docType

protected DocType docType
The DocType declaration
Constructor Detail

Document

protected Document()

Default, no-args constructor for implementations to use if needed.


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(List content,
                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(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

getRootElement

public Element getRootElement()

This will return the root Element for this Document

Returns:
Element - the document's root element

setRootElement

public Document setRootElement(Element rootElement)

This sets the root Element for the Document.

Parameters:
rootElement - Element to be new root.
Returns:
Document - modified Document.
Throws:
IllegalAddException - if the given rootElement already has a parent.

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

Returns:
List - all Document content

setContent

public Document setContent(List newContent)

This will set all content for the Document. The List may contain only objects of type Element, Comment, and ProcessingInstruction; and only one Element that becomes the root. In event of an exception the original content will be unchanged and the items in the added content will be unaltered.

Parameters:
content - the new content
Returns:
the modified Document
Throws:
IllegalAddException - if the List contains more than one Element or objects of illegal types.

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.

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

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

getSerializedForm

public final String getSerializedForm()
Deprecated. Deprecated in beta7, use XMLOutputter.outputString(Document) instead

This will return the Document in XML format, usable in an XML document.

Returns:
String - the serialized form of the Document.
Throws:
RuntimeException - always! This method is not yet implemented. It is also deprecated as of beta 7.

getProcessingInstructions

public List getProcessingInstructions()
Deprecated. Deprecated in beta7, use getContent() and examine for PIs manually

This will return the list of ProcessingInstructions for this Document located at the document level (outside the root element). The returned list is "live" in document order and changes to it affect the document's actual content.

Returns:
List - PIs for document.

getProcessingInstructions

public List getProcessingInstructions(String target)
Deprecated. Deprecated in beta7, use getContent() and examine for PIs manually

This returns the processing instructions for this Document located at the document level (outside the root element) which have the supplied target. The returned list is "live" in document order and changes to it affect the document's actual content.

Parameters:
target - String target of PI to return.
Returns:
List - all PIs with the specified target.

getProcessingInstruction

public ProcessingInstruction getProcessingInstruction(String target)
Deprecated. Deprecated in beta7, use getContent() and examine for PIs manually

This returns the first processing instruction for this Document located at the document level (outside the root element) for the supplied target, or null if no such processing instruction exists.

Parameters:
target - String target of PI to return.
Returns:
ProcessingInstruction - the first PI with the specified target, or null if no such PI exists.

removeProcessingInstruction

public boolean removeProcessingInstruction(String target)
Deprecated. Deprecated in beta7, use getContent() and remove PIs manually

This will remove the first PI with the specified target.

Parameters:
target - String target of PI to remove.
Returns:
boolean - whether the requested PI was removed.

removeProcessingInstructions

public boolean removeProcessingInstructions(String target)
Deprecated. Deprecated in beta7, use getContent() and remove PIs manually

This will remove all PIs with the specified target.

Parameters:
target - String target of PI to remove.
Returns:
boolean - whether the requested PIs were removed.

setProcessingInstructions

public Document setProcessingInstructions(List pis)
Deprecated. Deprecated in beta7, use getContent() and add PIs manually

This sets the PIs for this Document to those in the List

Parameters:
pis - List of PIs to use.
Returns:
Document - this Document modified.

getMixedContent

public List getMixedContent()
Deprecated. Deprecated in beta7, use getContent() instead

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.

Returns:
List - all Document content

setMixedContent

public Document setMixedContent(List mixedContent)
Deprecated. Deprecated in beta7, use setContent(List) instead

This will set all content for the Document. The List may contain only objects of type Element, Comment, and ProcessingInstruction; and only one Element that becomes the root. In event of an exception the original content will be unchanged and the items in the added content will be unaltered.

Parameters:
content - the new mixed content
Returns:
the modified Document
Throws:
IllegalAddException - if the List contains more than one Element or objects of illegal types.


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