org.jdom2.output

Class XMLOutputter

java.lang.Object

org.jdom2.output.XMLOutputter

All Implemented Interfaces:

java.lang.Cloneable

public final class XMLOutputter
extends java.lang.Object
implements java.lang.Cloneable

Outputs a JDOM document as a stream of bytes.

The XMLOutputter 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 Format.getPrettyFormat().
• For whitespace-normalised output, use Format.getCompactFormat().
• For unmodified-format output, use Format.getRawFormat().

There are output(...) methods to print any of the standard JDOM classes 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 XML Character escaping as well as 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 Format.setEncoding(java.lang.String) method. The default encoding is UTF-8. If the default encoding of the platform is not UTF-8 and a default Format encoding is used, then there may be incorrectly formed characters in the output.

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

All of the output*(...) methods will flush the destination Writer or OutputStream before returning, and none of them will close() the destination.

XML declarations are always printed on their own line followed by a line separator (this doesn't change the semantics of the document). To omit printing of the declaration use Format.setOmitDeclaration(boolean). To omit printing of the encoding in the declaration use Format.setOmitEncoding(boolean). Unfortunately 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 Format.setExpandEmptyElements(boolean) to cause them to be expanded to <empty></empty>.

If changing the Format settings are insufficient for your output needs you can customise this XMLOutputter further by setting a different XMLOutputProcessor with the setXMLOutputProcessor(XMLOutputProcessor) method or an appropriate constructor. A fully-enabled Abstract class AbstractXMLOutputProcessor is available to be further extended to your needs if all you want to do is tweak some details.

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, Rolf Lear

Constructor Summary

Constructors

Constructor and Description
XMLOutputter() This will create an XMLOutputter with a default Format and XMLOutputProcessor.
XMLOutputter(Format format) This will create an XMLOutputter with the specified format characteristics.
XMLOutputter(Format format, XMLOutputProcessor processor) This will create an XMLOutputter with the specified format characteristics.
XMLOutputter(XMLOutputProcessor processor) This will create an XMLOutputter with the specified XMLOutputProcessor.
XMLOutputter(XMLOutputter that) This will create an XMLOutputter with the same customisations set in the given XMLOutputter instance.

Method Summary

Modifier and Type	Method and Description
XMLOutputter	clone() Returns a cloned copy of this XMLOutputter.
java.lang.String	escapeAttributeEntities(java.lang.String str) Escape any characters in the input string in such a way that the returned value is valid as output in an XML Attribute value.
java.lang.String	escapeElementEntities(java.lang.String str) Escape any characters in the input string in such a way that the returned value is valid as output in an XML Element text.
Format	getFormat() Returns the current format in use by the XMLOutputter.
XMLOutputProcessor	getXMLOutputProcessor() Returns the current XMLOutputProcessor instance in use by the XMLOutputter.
void	output(CDATA cdata, java.io.OutputStream out) Print out a CDATA node.
void	output(CDATA cdata, java.io.Writer out) Print out a CDATA node.
void	output(Comment comment, java.io.OutputStream out) Print out a Comment.
void	output(Comment comment, java.io.Writer out) Print out a Comment.
void	output(DocType doctype, java.io.OutputStream out) This will print the DocType to the given OutputStream.
void	output(DocType doctype, java.io.Writer out) Print out the DocType.
void	output(Document doc, java.io.OutputStream out) This will print the Document to the given OutputStream.
void	output(Document doc, java.io.Writer out) This will print the Document to the given Writer.
void	output(Element element, java.io.OutputStream out) Print out an Element, including its Attributes, and all contained (child) elements, etc.
void	output(Element element, java.io.Writer out) Print out an Element, including its Attributes, and all contained (child) elements, etc.
void	output(EntityRef entity, java.io.OutputStream out) Print out a EntityRef.
void	output(EntityRef entity, java.io.Writer out) Print out an EntityRef.
void	output(java.util.List<? extends Content> list, java.io.OutputStream out) This will handle printing out a list of nodes.
void	output(java.util.List<? extends Content> list, java.io.Writer out) This will handle printing out a list of nodes.
void	output(ProcessingInstruction pi, java.io.OutputStream out) Print out a ProcessingInstruction.
void	output(ProcessingInstruction pi, java.io.Writer out) Print out a ProcessingInstruction.
void	output(Text text, java.io.OutputStream out) Print out a Text node.
void	output(Text text, java.io.Writer out) Print out a Text node.
void	outputElementContent(Element element, java.io.OutputStream out) This will handle printing out an Element's content only, not including its tag, and attributes.
void	outputElementContent(Element element, java.io.Writer out) This will handle printing out an Element's content only, not including its tag, and attributes.
java.lang.String	outputElementContentString(Element element) This will handle printing out an Element's content only, not including its tag, and attributes.
java.lang.String	outputString(CDATA cdata) Return a string representing a CDATA node.
java.lang.String	outputString(Comment comment) Return a string representing a Comment.
java.lang.String	outputString(DocType doctype) Return a string representing a DocType.
java.lang.String	outputString(Document doc) Return a string representing a Document.
java.lang.String	outputString(Element element) Return a string representing an Element.
java.lang.String	outputString(EntityRef entity) Return a string representing an EntityRef.
java.lang.String	outputString(java.util.List<? extends Content> list) Return a string representing a List of Content nodes.
java.lang.String	outputString(ProcessingInstruction pi) Return a string representing a ProcessingInstruction.
java.lang.String	outputString(Text text) Return a string representing a Text node.
void	setFormat(Format newFormat) Sets the new format logic for the XMLOutputter.
void	setXMLOutputProcessor(XMLOutputProcessor processor) Sets a new XMLOutputProcessor instance for this XMLOutputter.
java.lang.String	toString() Return a string listing of the settings for this XMLOutputter instance.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XMLOutputter

public XMLOutputter(Format format,
                    XMLOutputProcessor processor)

This will create an XMLOutputter with the specified format characteristics.

Note: the format object is cloned internally before use. If you want to modify the Format after constructing the XMLOutputter you can modify the Format instance getFormat() returns.

Parameters:

format - The Format instance to use. This instance will be cloned() and as a consequence, changes made to the specified format instance will not be reflected in this XMLOutputter. A null input format indicates that XMLOutputter should use the default Format.getRawFormat()

processor - The XMLOutputProcessor to delegate output to. If null the XMLOutputter will use the default XMLOutputProcessor.

XMLOutputter

public XMLOutputter()

This will create an XMLOutputter with a default Format and XMLOutputProcessor.

XMLOutputter

public XMLOutputter(XMLOutputter that)

This will create an XMLOutputter with the same customisations set in the given XMLOutputter instance. Note that XMLOutputter two = one.clone(); would work equally well.

Parameters:

that - the XMLOutputter to clone

XMLOutputter

public XMLOutputter(Format format)

This will create an XMLOutputter with the specified format characteristics.

Note: the format object is cloned internally before use.

Parameters:

format - The Format instance to use. This instance will be cloned() and as a consequence, changes made to the specified format instance will not be reflected in this XMLOutputter. A null input format indicates that XMLOutputter should use the default Format.getRawFormat()

XMLOutputter

public XMLOutputter(XMLOutputProcessor processor)

This will create an XMLOutputter with the specified XMLOutputProcessor.

Parameters:

processor - The XMLOutputProcessor to delegate output to. If null the XMLOutputter will use the default XMLOutputProcessor.

Method Detail

setFormat

public void setFormat(Format newFormat)

Sets the new format logic for the XMLOutputter. Note the Format object is cloned internally before use.

Parameters:

newFormat - the format to use for subsequent output

See Also:

getFormat()

getFormat

public Format getFormat()

Returns the current format in use by the XMLOutputter. Note the Format object returned is not a clone of the one used internally, thus, an XMLOutputter instance is able to have its Format changed by changing the settings on the Format instance returned by this method.

Returns:

the current Format instance used by this XMLOutputter.

getXMLOutputProcessor

public XMLOutputProcessor getXMLOutputProcessor()

Returns the current XMLOutputProcessor instance in use by the XMLOutputter.

Returns:

the current XMLOutputProcessor instance.

setXMLOutputProcessor

public void setXMLOutputProcessor(XMLOutputProcessor processor)

Sets a new XMLOutputProcessor instance for this XMLOutputter. Note the processor object is expected to be thread-safe.

Parameters:

processor - the new XMLOutputProcesor to use for output

output

public final void output(Document doc,
                         java.io.OutputStream out)
                  throws java.io.IOException

This will print the Document to the given OutputStream. 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:

java.io.IOException - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(DocType doctype,
                         java.io.OutputStream out)
                  throws java.io.IOException

This will print the DocType to the given OutputStream.

Parameters:

doctype - DocType to output.

out - OutputStream to use.

Throws:

java.io.IOException - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(Element element,
                         java.io.OutputStream out)
                  throws java.io.IOException

Print out an Element, including its Attributes, and all contained (child) elements, etc.

Parameters:

element - Element to output.

out - OutputStream to use.

Throws:

java.io.IOException - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

outputElementContent

public final void outputElementContent(Element element,
                                       java.io.OutputStream out)
                                throws java.io.IOException

This will handle printing out an 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.

Throws:

java.io.IOException - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(java.util.List<? extends Content> list,
                         java.io.OutputStream out)
                  throws java.io.IOException

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

The list is assumed to contain legal JDOM nodes. If other content is coerced on to the list it will cause ClassCastExceptions, and null Lists or null list members will cause NullPointerException.

Parameters:

list - List of nodes.

out - OutputStream to use.

Throws:

java.io.IOException - if there's any problem writing.

java.lang.ClassCastException - if non-Content is forced in to the list

java.lang.NullPointerException - if the List is null or contains null members.

output

public final void output(CDATA cdata,
                         java.io.OutputStream out)
                  throws java.io.IOException

Print out a CDATA node.

Parameters:

cdata - CDATA to output.

out - OutputStream to use.

Throws:

java.io.IOException - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(Text text,
                         java.io.OutputStream out)
                  throws java.io.IOException

Print out a Text node. Performs the necessary entity escaping and whitespace stripping.

Parameters:

text - Text to output.

out - OutputStream to use.

Throws:

java.io.IOException - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(Comment comment,
                         java.io.OutputStream out)
                  throws java.io.IOException

Print out a Comment.

Parameters:

comment - Comment to output.

out - OutputStream to use.

Throws:

java.io.IOException - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(ProcessingInstruction pi,
                         java.io.OutputStream out)
                  throws java.io.IOException

Print out a ProcessingInstruction.

Parameters:

pi - ProcessingInstruction to output.

out - OutputStream to use.

Throws:

java.io.IOException - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public void output(EntityRef entity,
                   java.io.OutputStream out)
            throws java.io.IOException

Print out a EntityRef.

Parameters:

entity - EntityRef to output.

out - OutputStream to use.

Throws:

java.io.IOException - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

outputString

public final java.lang.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.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.NullPointerException - if the specified content is null.

outputString

public final java.lang.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.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.NullPointerException - if the specified content is null.

outputString

public final java.lang.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.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.NullPointerException - if the specified content is null.

outputString

public final java.lang.String outputString(java.util.List<? extends Content> list)

Return a string representing a List of Content nodes.
The list is assumed to contain legal JDOM nodes. If other content is coerced on to the list it will cause ClassCastExceptions, and null List members will cause NullPointerException.

Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

list - List to format.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.ClassCastException - if non-Content is forced in to the list

java.lang.NullPointerException - if the List is null or contains null members.

outputString

public final java.lang.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.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.NullPointerException - if the specified content is null.

outputString

public final java.lang.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.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.NullPointerException - if the specified content is null.

outputString

public final java.lang.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.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.NullPointerException - if the specified content is null.

outputString

public final java.lang.String outputString(ProcessingInstruction pi)

Return a string representing a ProcessingInstruction.

Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

pi - ProcessingInstruction to format.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.NullPointerException - if the specified content is null.

outputString

public final java.lang.String outputString(EntityRef entity)

Return a string representing an EntityRef.

Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

entity - EntityRef to format.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.NullPointerException - if the specified content is null.

outputElementContentString

public final java.lang.String outputElementContentString(Element element)

This will handle printing out an 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>".

Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

element - Element to output.

Returns:

the input content formatted as an XML String.

Throws:

java.lang.NullPointerException - if the specified content is null.

output

public final void output(Document doc,
                         java.io.Writer out)
                  throws java.io.IOException

This will print the Document to the given Writer.

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

doc - Document to format.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(DocType doctype,
                         java.io.Writer out)
                  throws java.io.IOException

Print out the DocType.

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

doctype - DocType to output.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(Element element,
                         java.io.Writer out)
                  throws java.io.IOException

Print out an Element, including its Attributes, and all contained (child) elements, etc.

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

element - Element to output.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

outputElementContent

public final void outputElementContent(Element element,
                                       java.io.Writer out)
                                throws java.io.IOException

This will handle printing out an 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>".

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

element - Element to output.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(java.util.List<? extends Content> list,
                         java.io.Writer out)
                  throws java.io.IOException

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

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

list - List of nodes.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(CDATA cdata,
                         java.io.Writer out)
                  throws java.io.IOException

Print out a CDATA node.

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

cdata - CDATA to output.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(Text text,
                         java.io.Writer out)
                  throws java.io.IOException

Print out a Text node. Performs the necessary entity escaping and whitespace stripping.

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

text - Text to output.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(Comment comment,
                         java.io.Writer out)
                  throws java.io.IOException

Print out a Comment.

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

comment - Comment to output.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(ProcessingInstruction pi,
                         java.io.Writer out)
                  throws java.io.IOException

Print out a ProcessingInstruction.

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

pi - ProcessingInstruction to output.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

output

public final void output(EntityRef entity,
                         java.io.Writer out)
                  throws java.io.IOException

Print out an EntityRef.

Note: ensure the character encoding of the out Writer is set the same as the Format's encoding (see 'warning' on XMLOutputter).

Parameters:

entity - EntityRef to output.

out - Writer to use.

Throws:

java.io.IOException - - if there's any problem writing.

java.lang.NullPointerException - if the specified content is null.

escapeAttributeEntities

public java.lang.String escapeAttributeEntities(java.lang.String str)

Escape any characters in the input string in such a way that the returned value is valid as output in an XML Attribute value.

Parameters:

str - the input String to escape

Returns:

the escaped version of the input String

escapeElementEntities

public java.lang.String escapeElementEntities(java.lang.String str)

Escape any characters in the input string in such a way that the returned value is valid as output in an XML Element text.

Parameters:

str - the input String to escape

Returns:

the escaped version of the input String

clone

public XMLOutputter clone()

Returns a cloned copy of this XMLOutputter.

Overrides:

clone in class java.lang.Object

toString

public java.lang.String toString()

Return a string listing of the settings for this XMLOutputter instance.

Overrides:

toString in class java.lang.Object

Returns:

a string listing the settings for this XMLOutputter instance