org.jdom.output

Class XMLOutputter

public class XMLOutputter extends Object implements Cloneable

Outputs a JDOM document as a stream of bytes. The outputter can manage many styles of document formatting, from untouched to pretty printed. The default is to output the document content exactly as created, but this can be changed by setting a new Format object. For pretty-print output, use {@link Format#getPrettyFormat()}. For whitespace-normalized output, use {@link Format#getCompactFormat()}.

There are {@link #output output(...)} methods to print any of the standard JDOM classes, including Document and Element, to either a Writer or an OutputStream. Warning: When outputting to a Writer, make sure the writer's encoding matches the encoding setting in the Format object. This ensures the encoding in which the content is written (controlled by the Writer configuration) matches the encoding placed in the document's XML declaration (controlled by the XMLOutputter). Because a Writer cannot be queried for its encoding, the information must be passed to the Format manually in its constructor or via the {@link Format#setEncoding} method. The default encoding is UTF-8.

The methods {@link #outputString outputString(...)} are for convenience only; for top performance you should call one of the {@link #output output(...)} methods and pass in your own Writer or OutputStream if possible.

XML declarations are always printed on their own line followed by a line seperator (this doesn't change the semantics of the document). To omit printing of the declaration use {@link Format#setOmitDeclaration}. To omit printing of the encoding in the declaration use {@link Format#setOmitEncoding}. Unfortunatly there is currently no way to know the original encoding of the document.

Empty elements are by default printed as <empty/>, but this can be configured with {@link Format#setExpandEmptyElements} to cause them to be expanded to <empty></empty>.

Version: $Revision: 1.112 $, $Date: 2004/09/01 06:08:18 $

Author: Brett McLaughlin Jason Hunter Jason Reid Wolfgang Werner Elliotte Rusty Harold David & Will (from Post Tool Design) Dan Schaffer Alex Chaffee Bradley S. Huffman

Nested Class Summary
protected classXMLOutputter.NamespaceStack
Our own null subclass of NamespaceStack.
Field Summary
protected FormatcurrentFormat
protected static FormatpreserveFormat
Constructor Summary
XMLOutputter()
This will create an XMLOutputter with the default {@link Format} matching {@link Format#getRawFormat}.
XMLOutputter(Format format)
This will create an XMLOutputter with the specified format characteristics.
XMLOutputter(XMLOutputter that)
This will create an XMLOutputter with all the options as set in the given XMLOutputter.
Method Summary
Objectclone()
Returns a copy of this XMLOutputter.
StringescapeAttributeEntities(String str)
This will take the pre-defined entities in XML 1.0 and convert their character representation to the appropriate entity reference, suitable for XML attributes.
StringescapeElementEntities(String str)
This will take the three pre-defined entities in XML 1.0 (used specifically in XML elements) and convert their character representation to the appropriate entity reference, suitable for XML element content.
FormatgetFormat()
Returns the current format in use by the outputter.
voidoutput(Document doc, OutputStream out)
This will print the Document to the given output stream.
voidoutput(DocType doctype, OutputStream out)
Print out the {@link DocType}.
voidoutput(Element element, OutputStream out)
Print out an {@link Element}, including its {@link Attribute}s, and all contained (child) elements, etc.
voidoutput(List list, OutputStream out)
This will handle printing out a list of nodes.
voidoutput(CDATA cdata, OutputStream out)
Print out a {@link CDATA} node.
voidoutput(Text text, OutputStream out)
Print out a {@link Text} node.
voidoutput(Comment comment, OutputStream out)
Print out a {@link Comment}.
voidoutput(ProcessingInstruction pi, OutputStream out)
Print out a {@link ProcessingInstruction}.
voidoutput(EntityRef entity, OutputStream out)
Print out a {@link EntityRef}.
voidoutput(Document doc, Writer out)
This will print the Document to the given Writer.
voidoutput(DocType doctype, Writer out)
Print out the {@link DocType}.
voidoutput(Element element, Writer out)
Print out an {@link Element}, including its {@link Attribute}s, and all contained (child) elements, etc.
voidoutput(List list, Writer out)
This will handle printing out a list of nodes.
voidoutput(CDATA cdata, Writer out)
Print out a {@link CDATA} node.
voidoutput(Text text, Writer out)
Print out a {@link Text} node.
voidoutput(Comment comment, Writer out)
Print out a {@link Comment}.
voidoutput(ProcessingInstruction pi, Writer out)
Print out a {@link ProcessingInstruction}.
voidoutput(EntityRef entity, Writer out)
Print out a {@link EntityRef}.
voidoutputElementContent(Element element, OutputStream out)
This will handle printing out an {@link Element}'s content only, not including its tag, and attributes.
voidoutputElementContent(Element element, Writer out)
This will handle printing out an {@link Element}'s content only, not including its tag, and attributes.
StringoutputString(Document doc)
Return a string representing a document.
StringoutputString(DocType doctype)
Return a string representing a DocType.
StringoutputString(Element element)
Return a string representing an element.
StringoutputString(List list)
Return a string representing a list of nodes.
StringoutputString(CDATA cdata)
Return a string representing a CDATA node.
StringoutputString(Text text)
Return a string representing a Text node.
StringoutputString(Comment comment)
Return a string representing a comment.
StringoutputString(ProcessingInstruction pi)
Return a string representing a PI.
StringoutputString(EntityRef entity)
Return a string representing an entity.
protected voidprintAttributes(Writer out, List attributes, Element parent, XMLOutputter.NamespaceStack namespaces)
This will handle printing of a {@link Attribute} list.
protected voidprintCDATA(Writer out, CDATA cdata)
This will handle printing of {@link CDATA} text.
protected voidprintComment(Writer out, Comment comment)
This will handle printing of comments.
protected voidprintDeclaration(Writer out, Document doc, String encoding)
This will handle printing of the declaration.
protected voidprintDocType(Writer out, DocType docType)
This handle printing the DOCTYPE declaration if one exists.
protected voidprintElement(Writer out, Element element, int level, XMLOutputter.NamespaceStack namespaces)
This will handle printing of a {@link Element}, its {@link Attribute}s, and all contained (child) elements, etc.
protected voidprintEntityRef(Writer out, EntityRef entity)
This will handle printing a {@link EntityRef}.
protected voidprintProcessingInstruction(Writer out, ProcessingInstruction pi)
This will handle printing of processing instructions.
protected voidprintText(Writer out, Text text)
This will handle printing of {@link Text} strings.
voidsetFormat(Format newFormat)
Sets the new format logic for the outputter.
StringtoString()
Return a string listing of the settings for this XMLOutputter instance.

Field Detail

currentFormat

protected Format currentFormat

preserveFormat

protected static final Format preserveFormat

Constructor Detail

XMLOutputter

public XMLOutputter()
This will create an XMLOutputter with the default {@link Format} matching {@link Format#getRawFormat}.

XMLOutputter

public XMLOutputter(Format format)
This will create an XMLOutputter with the specified format characteristics. Note the format object is cloned internally before use.

XMLOutputter

public XMLOutputter(XMLOutputter that)
This will create an XMLOutputter with all the options as set in the given XMLOutputter. Note that XMLOutputter two = (XMLOutputter)one.clone(); would work equally well.

Parameters: that the XMLOutputter to clone

Method Detail

clone

public Object clone()
Returns a copy of this XMLOutputter.

escapeAttributeEntities

public String escapeAttributeEntities(String str)
This will take the pre-defined entities in XML 1.0 and convert their character representation to the appropriate entity reference, suitable for XML attributes. It does not convert the single quote (') because it's not necessary as the outputter writes attributes surrounded by double-quotes.

Parameters: str String input to escape.

Returns: String with escaped content.

escapeElementEntities

public String escapeElementEntities(String str)
This will take the three pre-defined entities in XML 1.0 (used specifically in XML elements) and convert their character representation to the appropriate entity reference, suitable for XML element content.

Parameters: str String input to escape.

Returns: String with escaped content.

getFormat

public Format getFormat()
Returns the current format in use by the outputter. Note the Format object returned is a clone of the one used internally.

output

public void output(Document doc, OutputStream out)
This will print the Document to the given output stream. The characters are printed using the encoding specified in the constructor, or a default of UTF-8.

Parameters: doc Document to format. out OutputStream to use.

Throws: IOException - if there's any problem writing.

output

public void output(DocType doctype, OutputStream out)
Print out the {@link DocType}.

Parameters: doctype DocType to output. out OutputStream to use.

output

public void output(Element element, OutputStream out)
Print out an {@link Element}, including its {@link Attribute}s, and all contained (child) elements, etc.

Parameters: element Element to output. out Writer to use.

output

public void output(List list, OutputStream out)
This will handle printing out a list of nodes. This can be useful for printing the content of an element that contains HTML, like "<description>JDOM is <b>fun>!</description>".

Parameters: list List of nodes. out OutputStream to use.

output

public void output(CDATA cdata, OutputStream out)
Print out a {@link CDATA} node.

Parameters: cdata CDATA to output. out OutputStream to use.

output

public void output(Text text, OutputStream out)
Print out a {@link Text} node. Perfoms the necessary entity escaping and whitespace stripping.

Parameters: text Text to output. out OutputStream to use.

output

public void output(Comment comment, OutputStream out)
Print out a {@link Comment}.

Parameters: comment Comment to output. out OutputStream to use.

output

public void output(ProcessingInstruction pi, OutputStream out)
Print out a {@link ProcessingInstruction}.

Parameters: pi ProcessingInstruction to output. out OutputStream to use.

output

public void output(EntityRef entity, OutputStream out)
Print out a {@link EntityRef}.

Parameters: entity EntityRef to output. out OutputStream to use.

output

public void output(Document doc, Writer out)
This will print the Document to the given Writer.

Warning: using your own Writer may cause the outputter's preferred character encoding to be ignored. If you use encodings other than UTF-8, we recommend using the method that takes an OutputStream instead.

Parameters: doc Document to format. out Writer to use.

Throws: IOException - if there's any problem writing.

output

public void output(DocType doctype, Writer out)
Print out the {@link DocType}.

Parameters: doctype DocType to output. out Writer to use.

output

public void output(Element element, Writer out)
Print out an {@link Element}, including its {@link Attribute}s, and all contained (child) elements, etc.

Parameters: element Element to output. out Writer to use.

output

public void output(List list, Writer out)
This will handle printing out a list of nodes. This can be useful for printing the content of an element that contains HTML, like "<description>JDOM is <b>fun>!</description>".

Parameters: list List of nodes. out Writer to use.

output

public void output(CDATA cdata, Writer out)
Print out a {@link CDATA} node.

Parameters: cdata CDATA to output. out Writer to use.

output

public void output(Text text, Writer out)
Print out a {@link Text} node. Perfoms the necessary entity escaping and whitespace stripping.

Parameters: text Text to output. out Writer to use.

output

public void output(Comment comment, Writer out)
Print out a {@link Comment}.

Parameters: comment Comment to output. out Writer to use.

output

public void output(ProcessingInstruction pi, Writer out)
Print out a {@link ProcessingInstruction}.

Parameters: pi ProcessingInstruction to output. out Writer to use.

output

public void output(EntityRef entity, Writer out)
Print out a {@link EntityRef}.

Parameters: entity EntityRef to output. out Writer to use.

outputElementContent

public void outputElementContent(Element element, OutputStream out)
This will handle printing out an {@link Element}'s content only, not including its tag, and attributes. This can be useful for printing the content of an element that contains HTML, like "<description>JDOM is <b>fun>!</description>".

Parameters: element Element to output. out OutputStream to use.

outputElementContent

public void outputElementContent(Element element, Writer out)
This will handle printing out an {@link Element}'s content only, not including its tag, and attributes. This can be useful for printing the content of an element that contains HTML, like "<description>JDOM is <b>fun>!</description>".

Parameters: element Element to output. out Writer to use.

outputString

public String outputString(Document doc)
Return a string representing a document. Uses an internal StringWriter. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters: doc Document to format.

outputString

public String outputString(DocType doctype)
Return a string representing a DocType. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters: doctype DocType to format.

outputString

public String outputString(Element element)
Return a string representing an element. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters: element Element to format.

outputString

public String outputString(List list)
Return a string representing a list of nodes. The list is assumed to contain legal JDOM nodes.

Parameters: list List to format.

outputString

public String outputString(CDATA cdata)
Return a string representing a CDATA node. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters: cdata CDATA to format.

outputString

public String outputString(Text text)
Return a string representing a Text node. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters: text Text to format.

outputString

public String outputString(Comment comment)
Return a string representing a comment. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters: comment Comment to format.

outputString

public String outputString(ProcessingInstruction pi)
Return a string representing a PI. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters: pi ProcessingInstruction to format.

outputString

public String outputString(EntityRef entity)
Return a string representing an entity. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters: entity EntityRef to format.

printAttributes

protected void printAttributes(Writer out, List attributes, Element parent, XMLOutputter.NamespaceStack namespaces)
This will handle printing of a {@link Attribute} list.

Parameters: attributes List of Attribute objcts out Writer to use

printCDATA

protected void printCDATA(Writer out, CDATA cdata)
This will handle printing of {@link CDATA} text.

Parameters: cdata CDATA to output. out Writer to use.

printComment

protected void printComment(Writer out, Comment comment)
This will handle printing of comments.

Parameters: comment Comment to write. out Writer to use.

printDeclaration

protected void printDeclaration(Writer out, Document doc, String encoding)
This will handle printing of the declaration. Assumes XML version 1.0 since we don't directly know.

Parameters: doc Document whose declaration to write. out Writer to use. encoding The encoding to add to the declaration

printDocType

protected void printDocType(Writer out, DocType docType)
This handle printing the DOCTYPE declaration if one exists.

Parameters: docType Document whose declaration to write. out Writer to use.

printElement

protected void printElement(Writer out, Element element, int level, XMLOutputter.NamespaceStack namespaces)
This will handle printing of a {@link Element}, its {@link Attribute}s, and all contained (child) elements, etc.

Parameters: element Element to output. out Writer to use. level int level of indention. namespaces List stack of Namespaces in scope.

printEntityRef

protected void printEntityRef(Writer out, EntityRef entity)
This will handle printing a {@link EntityRef}. Only the entity reference such as &entity; will be printed. However, subclasses are free to override this method to print the contents of the entity instead.

Parameters: entity EntityRef to output. out Writer to use.

printProcessingInstruction

protected void printProcessingInstruction(Writer out, ProcessingInstruction pi)
This will handle printing of processing instructions.

Parameters: pi ProcessingInstruction to write. out Writer to use.

printText

protected void printText(Writer out, Text text)
This will handle printing of {@link Text} strings.

Parameters: text Text to write. out Writer to use.

setFormat

public void setFormat(Format newFormat)
Sets the new format logic for the outputter. Note the Format object is cloned internally before use.

Parameters: newFormat the format to use for output

toString

public String toString()
Return a string listing of the settings for this XMLOutputter instance.

Returns: a string listing the settings for this XMLOutputter instance

Copyright B) 2004 Jason Hunter, Brett McLaughlin. All Rights Reserved.