Class XMLOutputter
- All Implemented Interfaces:
Cloneable
This class is a fork from JDOM 1.0 modified to preserve CData sections and comments.
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
. For whitespace-normalized
output, use Format.getPrettyFormat()
.Format.getCompactFormat()
There are
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
output(...)
method. The default encoding is
UTF-8.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(...)
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)
- 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
Nested ClassesModifier and TypeClassDescriptionprotected static class
Our own null subclass of NamespaceStack. -
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionXMLOutputter
(Format format) This will create anXMLOutputter
with the specified format characteristics.XMLOutputter
(XMLOutputter that) This will create anXMLOutputter
with all the options as set in the givenXMLOutputter
. -
Method Summary
Modifier and TypeMethodDescriptionclone()
Returns a copy of this XMLOutputter.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.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.Returns the current format in use by the outputter.void
output
(List<?> list, OutputStream out) This will handle printing out a list of nodes.void
This will handle printing out a list of nodes.void
output
(org.jdom2.CDATA cdata, OutputStream out) Print out a
node.CDATA
void
Print out a
node.CDATA
void
output
(org.jdom2.Comment comment, OutputStream out) Print out a
.Comment
void
Print out a
.Comment
void
output
(org.jdom2.DocType doctype, OutputStream out) Print out the
.DocType
void
Print out the
.DocType
void
output
(org.jdom2.Document doc, OutputStream out) This will print theDocument
to the given output stream.void
This will print theDocument
to the given Writer.void
output
(org.jdom2.Element element, OutputStream out) Print out an
, including itsElement
s, and all contained (child) elements, etc.Attribute
void
Print out an
, including itsElement
s, and all contained (child) elements, etc.Attribute
void
output
(org.jdom2.EntityRef entity, OutputStream out) Print out a
.EntityRef
void
Print out a
.EntityRef
void
output
(org.jdom2.ProcessingInstruction pi, OutputStream out) Print out a
.ProcessingInstruction
void
Print out a
.ProcessingInstruction
void
output
(org.jdom2.Text text, OutputStream out) Print out a
node.Text
void
Print out a
node.Text
void
outputElementContent
(org.jdom2.Element element, OutputStream out) This will handle printing out an
's content only, not including its tag, and attributes.Element
void
outputElementContent
(org.jdom2.Element element, Writer out) This will handle printing out an
's content only, not including its tag, and attributes.Element
outputString
(List<?> list) Return a string representing a list of nodes.outputString
(org.jdom2.CDATA cdata) Return a string representing a CDATA node.outputString
(org.jdom2.Comment comment) Return a string representing a comment.outputString
(org.jdom2.DocType doctype) Return a string representing a DocType.outputString
(org.jdom2.Document doc) Return a string representing a document.outputString
(org.jdom2.Element element) Return a string representing an element.outputString
(org.jdom2.EntityRef entity) Return a string representing an entity.outputString
(org.jdom2.ProcessingInstruction pi) Return a string representing a PI.outputString
(org.jdom2.Text text) Return a string representing a Text node.protected void
printAttributes
(Writer out, List<?> attributes, org.jdom2.Element parent, XMLOutputter.NamespaceStack namespaces) This will handle printing of a
list.Attribute
protected void
printCDATA
(Writer out, org.jdom2.CDATA cdata) This will handle printing of
text.CDATA
protected void
printComment
(Writer out, org.jdom2.Comment comment) This will handle printing of comments.protected void
printDeclaration
(Writer out, org.jdom2.Document doc, String encoding) This will handle printing of the declaration.protected void
printDocType
(Writer out, org.jdom2.DocType docType) This handle printing the DOCTYPE declaration if one exists.protected void
printElement
(Writer out, org.jdom2.Element element, int level, XMLOutputter.NamespaceStack namespaces) This will handle printing of a
, itsElement
s, and all contained (child) elements, etc.Attribute
protected void
printEntityRef
(Writer out, org.jdom2.EntityRef entity) This will handle printing a
.EntityRef
protected void
printProcessingInstruction
(Writer out, org.jdom2.ProcessingInstruction pi) This will handle printing of processing instructions.protected void
This will handle printing of
strings.Text
void
Sets the new format logic for the outputter.toString()
Return a string listing of the settings for this XMLOutputter instance.
-
Field Details
-
PRESERVE_FORMAT
-
currentFormat
-
-
Constructor Details
-
XMLOutputter
public XMLOutputter() -
XMLOutputter
This will create anXMLOutputter
with the specified format characteristics. Note the format object is cloned internally before use. -
XMLOutputter
This will create anXMLOutputter
with all the options as set in the givenXMLOutputter
. Note thatXMLOutputter two = (XMLOutputter)one.clone();
would work equally well.- Parameters:
that
- the XMLOutputter to clone
-
-
Method Details
-
setFormat
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
-
getFormat
Returns the current format in use by the outputter. Note the Format object returned is a clone of the one used internally. -
output
This will print theDocument
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
Print out the
.DocType
- Parameters:
doctype
-DocType
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
Print out an
, including itsElement
s, and all contained (child) elements, etc.Attribute
- Parameters:
element
-Element
to output.out
-Writer
to use.- Throws:
IOException
-
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
-
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>".- Parameters:
list
-List
of nodes.out
-OutputStream
to use.- Throws:
IOException
-
output
Print out a
node.CDATA
- Parameters:
cdata
-CDATA
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
Print out a
node. Perfoms the necessary entity escaping and whitespace stripping.Text
- Parameters:
text
-Text
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
Print out a
.Comment
- Parameters:
comment
-Comment
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
Print out a
.ProcessingInstruction
- Parameters:
pi
-ProcessingInstruction
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
Print out a
.EntityRef
- Parameters:
entity
-EntityRef
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
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
Print out the
.DocType
- Parameters:
doctype
-DocType
to output.out
-Writer
to use.- Throws:
IOException
-
output
Print out an
, including itsElement
s, and all contained (child) elements, etc.Attribute
- Parameters:
element
-Element
to output.out
-Writer
to use.- Throws:
IOException
-
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
-Writer
to use.- Throws:
IOException
-
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>".- Parameters:
list
-List
of nodes.out
-Writer
to use.- Throws:
IOException
-
output
Print out a
node.CDATA
- Parameters:
cdata
-CDATA
to output.out
-Writer
to use.- Throws:
IOException
-
output
Print out a
node. Perfoms the necessary entity escaping and whitespace stripping.Text
- Parameters:
text
-Text
to output.out
-Writer
to use.- Throws:
IOException
-
output
Print out a
.Comment
- Parameters:
comment
-Comment
to output.out
-Writer
to use.- Throws:
IOException
-
output
Print out a
.ProcessingInstruction
- Parameters:
pi
-ProcessingInstruction
to output.out
-Writer
to use.- Throws:
IOException
-
output
Print out a
.EntityRef
- Parameters:
entity
-EntityRef
to output.out
-Writer
to use.- Throws:
IOException
-
outputString
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
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
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
Return a string representing a list of nodes. The list is assumed to contain legal JDOM nodes.- Parameters:
list
-List
to format.
-
outputString
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
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
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
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
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.
-
printDeclaration
protected void printDeclaration(Writer out, org.jdom2.Document doc, String encoding) throws IOException This will handle printing of the declaration. Assumes XML version 1.0 since we don't directly know.- Parameters:
out
-Writer
to use.doc
-Document
whose declaration to write.encoding
- The encoding to add to the declaration- Throws:
IOException
-
printDocType
This handle printing the DOCTYPE declaration if one exists.- Parameters:
out
-Writer
to use.docType
-Document
whose declaration to write.- Throws:
IOException
-
printComment
This will handle printing of comments.- Parameters:
out
-Writer
to use.comment
-Comment
to write.- Throws:
IOException
-
printProcessingInstruction
protected void printProcessingInstruction(Writer out, org.jdom2.ProcessingInstruction pi) throws IOException This will handle printing of processing instructions.- Parameters:
out
-Writer
to use.pi
-ProcessingInstruction
to write.- Throws:
IOException
-
printEntityRef
This will handle printing a
. Only the entity reference such asEntityRef
&entity;
will be printed. However, subclasses are free to override this method to print the contents of the entity instead.- Parameters:
out
-Writer
to use.entity
-EntityRef
to output.- Throws:
IOException
-
printCDATA
This will handle printing of
text.CDATA
- Parameters:
out
-Writer
to use.cdata
-CDATA
to output.- Throws:
IOException
-
printText
This will handle printing of
strings.Text
- Parameters:
out
-Writer
to use.text
-Text
to write.- Throws:
IOException
-
printElement
protected void printElement(Writer out, org.jdom2.Element element, int level, XMLOutputter.NamespaceStack namespaces) throws IOException This will handle printing of a
, itsElement
s, and all contained (child) elements, etc.Attribute
- Parameters:
out
-Writer
to use.element
-Element
to output.level
-int
level of indention.namespaces
-List
stack of Namespaces in scope.- Throws:
IOException
-
printAttributes
protected void printAttributes(Writer out, List<?> attributes, org.jdom2.Element parent, XMLOutputter.NamespaceStack namespaces) throws IOException This will handle printing of a
list.Attribute
- Parameters:
out
-Writer
to useattributes
-List
of Attribute objcts- Throws:
IOException
-
escapeAttributeEntities
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
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.
-
clone
Returns a copy of this XMLOutputter. -
toString
Return a string listing of the settings for this XMLOutputter instance.
-