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
methods to print any of the standard JDOM classes to either a Writer or an OutputStream.output(...)
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
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.Format.setEncoding(java.lang.String)
The methods
are for convenience only; for top performance you should call one of theoutputString(...)
methods and pass in your own Writer or OutputStream if possible.output(...)
All of the
output*(...)
methods will flush the destination Writer or OutputStream before returning, and none of them willclose()
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
. To omit printing of the encoding in the declaration useFormat.setOmitDeclaration(boolean)
. Unfortunately there is currently no way to know the original encoding of the document.Format.setOmitEncoding(boolean)
Empty elements are by default printed as <empty/>, but this can be configured with
to cause them to be expanded to <empty></empty>.Format.setExpandEmptyElements(boolean)
If changing the
Format
settings are insufficient for your output needs you can customise this XMLOutputter further by setting a differentXMLOutputProcessor
with thesetXMLOutputProcessor(XMLOutputProcessor)
method or an appropriate constructor. A fully-enabled Abstract classAbstractXMLOutputProcessor
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 Description XMLOutputter()
XMLOutputter(Format format)
This will create anXMLOutputter
with the specified format characteristics.XMLOutputter(Format format, XMLOutputProcessor processor)
This will create anXMLOutputter
with the specified format characteristics.XMLOutputter(XMLOutputProcessor processor)
This will create anXMLOutputter
with the specified XMLOutputProcessor.XMLOutputter(XMLOutputter that)
This will create anXMLOutputter
with the same customisations set in the givenXMLOutputter
instance.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method 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(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(CDATA cdata, java.io.OutputStream out)
Print out a
node.CDATA
void
output(CDATA cdata, java.io.Writer out)
Print out a
node.CDATA
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
to the given OutputStream.DocType
void
output(DocType doctype, java.io.Writer out)
Print out the
.DocType
void
output(Document doc, java.io.OutputStream out)
This will print the
to the given OutputStream.Document
void
output(Document doc, java.io.Writer out)
This will print theDocument
to the given Writer.void
output(Element element, java.io.OutputStream out)
void
output(Element element, java.io.Writer out)
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(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
node.Text
void
output(Text text, java.io.Writer out)
Print out a
node.Text
void
outputElementContent(Element element, java.io.OutputStream out)
This will handle printing out an
's content only, not including its tag, and attributes.Element
void
outputElementContent(Element element, java.io.Writer out)
This will handle printing out an
's content only, not including its tag, and attributes.Element
java.lang.String
outputElementContentString(Element element)
This will handle printing out an
's content only, not including its tag, and attributes.Element
java.lang.String
outputString(java.util.List<? extends Content> list)
Return a string representing a List ofContent
nodes.java.lang.String
outputString(CDATA cdata)
Return a string representing aCDATA
node.java.lang.String
outputString(Comment comment)
Return a string representing aComment
.java.lang.String
outputString(DocType doctype)
Return a string representing aDocType
.java.lang.String
outputString(Document doc)
Return a string representing aDocument
.java.lang.String
outputString(Element element)
Return a string representing anElement
.java.lang.String
outputString(EntityRef entity)
Return a string representing anEntityRef
.java.lang.String
outputString(ProcessingInstruction pi)
Return a string representing aProcessingInstruction
.java.lang.String
outputString(Text text)
Return a string representing aText
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.
-
-
-
Constructor Detail
-
XMLOutputter
public XMLOutputter(Format format, XMLOutputProcessor processor)
This will create anXMLOutputter
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 defaultFormat.getRawFormat()
processor
- The XMLOutputProcessor to delegate output to. If null the XMLOutputter will use the default XMLOutputProcessor.
-
XMLOutputter
public XMLOutputter()
-
XMLOutputter
public XMLOutputter(XMLOutputter that)
This will create anXMLOutputter
with the same customisations set in the givenXMLOutputter
instance. Note thatXMLOutputter two = one.clone();
would work equally well.- Parameters:
that
- the XMLOutputter to clone
-
XMLOutputter
public XMLOutputter(Format format)
This will create anXMLOutputter
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 defaultFormat.getRawFormat()
-
XMLOutputter
public XMLOutputter(XMLOutputProcessor processor)
This will create anXMLOutputter
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
to the given OutputStream. The characters are printed using the encoding specified in the constructor, or a default of UTF-8.Document
- 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
to the given OutputStream.DocType
- 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
- 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
'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>".Element
- 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 listjava.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
node.CDATA
- 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
node. Performs the necessary entity escaping and whitespace stripping.Text
- 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 aDocument
. 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 aDocType
.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 anElement
.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 ofContent
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 listjava.lang.NullPointerException
- if the List is null or contains null members.
-
outputString
public final java.lang.String outputString(CDATA cdata)
Return a string representing aCDATA
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 aText
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 aComment
.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 aProcessingInstruction
.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 anEntityRef
.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
'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>".Element
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 theDocument
to the given Writer.Note: ensure the character encoding of the
out
Writer is set the same as theFormat
's encoding (see 'warning' onXMLOutputter
).- 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 theFormat
's encoding (see 'warning' onXMLOutputter
).- 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
, including itsElement
s, and all contained (child) elements, etc.Attribute
Note: ensure the character encoding of the
out
Writer is set the same as theFormat
's encoding (see 'warning' onXMLOutputter
).- 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
'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>".Element
Note: ensure the character encoding of the
out
Writer is set the same as theFormat
's encoding (see 'warning' onXMLOutputter
).- 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 theFormat
's encoding (see 'warning' onXMLOutputter
).- 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
node.CDATA
Note: ensure the character encoding of the
out
Writer is set the same as theFormat
's encoding (see 'warning' onXMLOutputter
).- 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
node. Performs the necessary entity escaping and whitespace stripping.Text
Note: ensure the character encoding of the
out
Writer is set the same as theFormat
's encoding (see 'warning' onXMLOutputter
).- 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 theFormat
's encoding (see 'warning' onXMLOutputter
).- 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 theFormat
's encoding (see 'warning' onXMLOutputter
).- 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 theFormat
's encoding (see 'warning' onXMLOutputter
).- 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 classjava.lang.Object
-
toString
public java.lang.String toString()
Return a string listing of the settings for this XMLOutputter instance.- Overrides:
toString
in classjava.lang.Object
- Returns:
- a string listing the settings for this XMLOutputter instance
-
-