Class XMLOutputter
- All Implemented Interfaces:
Cloneable
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 the outputString(...)
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
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
. To omit printing of the
encoding in the declaration use Format.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 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
ConstructorsConstructorDescriptionXMLOutputter
(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
Modifier and TypeMethodDescriptionclone()
Returns a cloned copy of this XMLOutputter.Escape any characters in the input string in such a way that the returned value is valid as output in an XML Attribute value.Escape any characters in the input string in such a way that the returned value is valid as output in an XML Element text.Returns the current format in use by the XMLOutputter.Returns the current XMLOutputProcessor instance in use by the XMLOutputter.final void
output
(List<? extends Content> list, OutputStream out) This will handle printing out a list of nodes.final void
This will handle printing out a list of nodes.final void
output
(CDATA cdata, OutputStream out) Print out a
node.CDATA
final void
Print out a
node.CDATA
final void
output
(Comment comment, OutputStream out) Print out a
.Comment
final void
Print out a
.Comment
final void
output
(DocType doctype, OutputStream out) This will print the
to the given OutputStream.DocType
final void
Print out the
.DocType
final void
output
(Document doc, OutputStream out) This will print the
to the given OutputStream.Document
final void
This will print theDocument
to the given Writer.final void
output
(Element element, OutputStream out) final void
void
output
(EntityRef entity, OutputStream out) Print out a
.EntityRef
final void
Print out an
.EntityRef
final void
output
(ProcessingInstruction pi, OutputStream out) Print out a
.ProcessingInstruction
final void
output
(ProcessingInstruction pi, Writer out) Print out a
.ProcessingInstruction
final void
output
(Text text, OutputStream out) Print out a
node.Text
final void
Print out a
node.Text
final void
outputElementContent
(Element element, OutputStream out) This will handle printing out an
's content only, not including its tag, and attributes.Element
final void
outputElementContent
(Element element, Writer out) This will handle printing out an
's content only, not including its tag, and attributes.Element
final String
outputElementContentString
(Element element) This will handle printing out an
's content only, not including its tag, and attributes.Element
final String
outputString
(List<? extends Content> list) Return a string representing a List ofContent
nodes.final String
outputString
(CDATA cdata) Return a string representing aCDATA
node.final String
outputString
(Comment comment) Return a string representing aComment
.final String
outputString
(DocType doctype) Return a string representing aDocType
.final String
outputString
(Document doc) Return a string representing aDocument
.final String
outputString
(Element element) Return a string representing anElement
.final String
outputString
(EntityRef entity) Return a string representing anEntityRef
.final String
Return a string representing aProcessingInstruction
.final String
outputString
(Text text) Return a string representing aText
node.void
Sets the new format logic for the XMLOutputter.void
setXMLOutputProcessor
(XMLOutputProcessor processor) Sets a new XMLOutputProcessor instance for this XMLOutputter.toString()
Return a string listing of the settings for this XMLOutputter instance.
-
Constructor Details
-
XMLOutputter
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
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
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
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 Details
-
setFormat
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
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
Returns the current XMLOutputProcessor instance in use by the XMLOutputter.- Returns:
- the current XMLOutputProcessor instance.
-
setXMLOutputProcessor
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
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:
IOException
- if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
This will print the
to the given OutputStream.DocType
- Parameters:
doctype
-DocType
to output.out
-OutputStream
to use.- Throws:
IOException
- if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
- Parameters:
element
-Element
to output.out
-OutputStream
to use.- Throws:
IOException
- if there's any problem writing.NullPointerException
- if the specified content is null.
-
outputElementContent
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:
IOException
- if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
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:
IOException
- if there's any problem writing.ClassCastException
- if non-Content
is forced in to the listNullPointerException
- if the List is null or contains null members.
-
output
Print out a
node.CDATA
- Parameters:
cdata
-CDATA
to output.out
-OutputStream
to use.- Throws:
IOException
- if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
Print out a
node. Performs the necessary entity escaping and whitespace stripping.Text
- Parameters:
text
-Text
to output.out
-OutputStream
to use.- Throws:
IOException
- if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
Print out a
.Comment
- Parameters:
comment
-Comment
to output.out
-OutputStream
to use.- Throws:
IOException
- if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
Print out a
.ProcessingInstruction
- Parameters:
pi
-ProcessingInstruction
to output.out
-OutputStream
to use.- Throws:
IOException
- if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
Print out a
.EntityRef
- Parameters:
entity
-EntityRef
to output.out
-OutputStream
to use.- Throws:
IOException
- if there's any problem writing.NullPointerException
- if the specified content is null.
-
outputString
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:
NullPointerException
- if the specified content is null.
-
outputString
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:
NullPointerException
- if the specified content is null.
-
outputString
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:
NullPointerException
- if the specified content is null.
-
outputString
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:
ClassCastException
- if non-Content
is forced in to the listNullPointerException
- if the List is null or contains null members.
-
outputString
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:
NullPointerException
- if the specified content is null.
-
outputString
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:
NullPointerException
- if the specified content is null.
-
outputString
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:
NullPointerException
- if the specified content is null.
-
outputString
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:
NullPointerException
- if the specified content is null.
-
outputString
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:
NullPointerException
- if the specified content is null.
-
outputElementContentString
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:
NullPointerException
- if the specified content is null.
-
output
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
outputElementContent
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
output
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:
IOException
- - if there's any problem writing.NullPointerException
- if the specified content is null.
-
escapeAttributeEntities
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
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
Returns a cloned copy of this XMLOutputter. -
toString
Return a string listing of the settings for this XMLOutputter instance.
-