Class XMLOutputter
- java.lang.Object
-
- org.jdom.output.XMLOutputter
-
- All Implemented Interfaces:
Cloneable
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
. For whitespace-normalized output, useFormat.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 theoutput(...)
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 theoutputString(...)
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 seperator (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)
. Unfortunatly 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)
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description protected class
XMLOutputter.NamespaceStack
Our own null subclass of NamespaceStack.
-
Field Summary
Fields Modifier and Type Field Description protected Format
currentFormat
protected static Format
preserveFormat
-
Constructor Summary
Constructors Constructor Description XMLOutputter()
XMLOutputter(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
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Object
clone()
Returns a copy of this XMLOutputter.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.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.Format
getFormat()
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
output(List list, Writer out)
This will handle printing out a list of nodes.void
output(CDATA cdata, OutputStream out)
Print out a
node.CDATA
void
output(CDATA cdata, Writer out)
Print out a
node.CDATA
void
output(Comment comment, OutputStream out)
Print out a
.Comment
void
output(Comment comment, Writer out)
Print out a
.Comment
void
output(DocType doctype, OutputStream out)
Print out the
.DocType
void
output(DocType doctype, Writer out)
Print out the
.DocType
void
output(Document doc, OutputStream out)
This will print theDocument
to the given output stream.void
output(Document doc, Writer out)
This will print theDocument
to the given Writer.void
output(Element element, OutputStream out)
void
output(Element element, Writer out)
void
output(EntityRef entity, OutputStream out)
Print out a
.EntityRef
void
output(EntityRef entity, Writer out)
Print out a
.EntityRef
void
output(ProcessingInstruction pi, OutputStream out)
Print out a
.ProcessingInstruction
void
output(ProcessingInstruction pi, Writer out)
Print out a
.ProcessingInstruction
void
output(Text text, OutputStream out)
Print out a
node.Text
void
output(Text text, Writer out)
Print out a
node.Text
void
outputElementContent(Element element, OutputStream out)
This will handle printing out an
's content only, not including its tag, and attributes.Element
void
outputElementContent(Element element, Writer out)
This will handle printing out an
's content only, not including its tag, and attributes.Element
String
outputString(List list)
Return a string representing a list of nodes.String
outputString(CDATA cdata)
Return a string representing a CDATA node.String
outputString(Comment comment)
Return a string representing a comment.String
outputString(DocType doctype)
Return a string representing a DocType.String
outputString(Document doc)
Return a string representing a document.String
outputString(Element element)
Return a string representing an element.String
outputString(EntityRef entity)
Return a string representing an entity.String
outputString(ProcessingInstruction pi)
Return a string representing a PI.String
outputString(Text text)
Return a string representing a Text node.protected void
printAttributes(Writer out, List attributes, Element parent, XMLOutputter.NamespaceStack namespaces)
This will handle printing of a
list.Attribute
protected void
printCDATA(Writer out, CDATA cdata)
This will handle printing of
text.CDATA
protected void
printComment(Writer out, Comment comment)
This will handle printing of comments.protected void
printDeclaration(Writer out, Document doc, String encoding)
This will handle printing of the declaration.protected void
printDocType(Writer out, DocType docType)
This handle printing the DOCTYPE declaration if one exists.protected void
printElement(Writer out, Element element, int level, XMLOutputter.NamespaceStack namespaces)
protected void
printEntityRef(Writer out, EntityRef entity)
This will handle printing a
.EntityRef
protected void
printProcessingInstruction(Writer out, ProcessingInstruction pi)
This will handle printing of processing instructions.protected void
printText(Writer out, Text text)
This will handle printing of
strings.Text
void
setFormat(Format newFormat)
Sets the new format logic for the outputter.String
toString()
Return a string listing of the settings for this XMLOutputter instance.
-
-
-
Constructor Detail
-
XMLOutputter
public XMLOutputter()
-
XMLOutputter
public XMLOutputter(Format format)
This will create anXMLOutputter
with the specified format characteristics. Note the format object is cloned internally before use.
-
XMLOutputter
public XMLOutputter(XMLOutputter that)
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 Detail
-
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
-
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) throws IOException
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
public void output(DocType doctype, OutputStream out) throws IOException
Print out the
.DocType
- Parameters:
doctype
-DocType
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
public void output(Element element, OutputStream out) throws IOException
- Parameters:
element
-Element
to output.out
-Writer
to use.- Throws:
IOException
-
outputElementContent
public void outputElementContent(Element element, OutputStream out) throws 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:
IOException
-
output
public void output(List list, OutputStream out) throws 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>".- Parameters:
list
-List
of nodes.out
-OutputStream
to use.- Throws:
IOException
-
output
public void output(CDATA cdata, OutputStream out) throws IOException
Print out a
node.CDATA
- Parameters:
cdata
-CDATA
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
public void output(Text text, OutputStream out) throws IOException
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
public void output(Comment comment, OutputStream out) throws IOException
Print out a
.Comment
- Parameters:
comment
-Comment
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
public void output(ProcessingInstruction pi, OutputStream out) throws IOException
Print out a
.ProcessingInstruction
- Parameters:
pi
-ProcessingInstruction
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
public void output(EntityRef entity, OutputStream out) throws IOException
Print out a
.EntityRef
- Parameters:
entity
-EntityRef
to output.out
-OutputStream
to use.- Throws:
IOException
-
output
public void output(Document doc, Writer out) throws IOException
This will print theDocument
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) throws IOException
Print out the
.DocType
- Parameters:
doctype
-DocType
to output.out
-Writer
to use.- Throws:
IOException
-
output
public void output(Element element, Writer out) throws IOException
- Parameters:
element
-Element
to output.out
-Writer
to use.- Throws:
IOException
-
outputElementContent
public void outputElementContent(Element element, Writer out) throws 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
-Writer
to use.- Throws:
IOException
-
output
public void output(List list, Writer out) throws 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>".- Parameters:
list
-List
of nodes.out
-Writer
to use.- Throws:
IOException
-
output
public void output(CDATA cdata, Writer out) throws IOException
Print out a
node.CDATA
- Parameters:
cdata
-CDATA
to output.out
-Writer
to use.- Throws:
IOException
-
output
public void output(Text text, Writer out) throws IOException
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
public void output(Comment comment, Writer out) throws IOException
Print out a
.Comment
- Parameters:
comment
-Comment
to output.out
-Writer
to use.- Throws:
IOException
-
output
public void output(ProcessingInstruction pi, Writer out) throws IOException
Print out a
.ProcessingInstruction
- Parameters:
pi
-ProcessingInstruction
to output.out
-Writer
to use.- Throws:
IOException
-
output
public void output(EntityRef entity, Writer out) throws IOException
Print out a
.EntityRef
- Parameters:
entity
-EntityRef
to output.out
-Writer
to use.- Throws:
IOException
-
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.
-
printDeclaration
protected void printDeclaration(Writer out, 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:
doc
-Document
whose declaration to write.out
-Writer
to use.encoding
- The encoding to add to the declaration- Throws:
IOException
-
printDocType
protected void printDocType(Writer out, DocType docType) throws IOException
This handle printing the DOCTYPE declaration if one exists.- Parameters:
docType
-Document
whose declaration to write.out
-Writer
to use.- Throws:
IOException
-
printComment
protected void printComment(Writer out, Comment comment) throws IOException
This will handle printing of comments.- Parameters:
comment
-Comment
to write.out
-Writer
to use.- Throws:
IOException
-
printProcessingInstruction
protected void printProcessingInstruction(Writer out, ProcessingInstruction pi) throws IOException
This will handle printing of processing instructions.- Parameters:
pi
-ProcessingInstruction
to write.out
-Writer
to use.- Throws:
IOException
-
printEntityRef
protected void printEntityRef(Writer out, EntityRef entity) throws IOException
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:
entity
-EntityRef
to output.out
-Writer
to use.- Throws:
IOException
-
printCDATA
protected void printCDATA(Writer out, CDATA cdata) throws IOException
This will handle printing of
text.CDATA
- Parameters:
cdata
-CDATA
to output.out
-Writer
to use.- Throws:
IOException
-
printText
protected void printText(Writer out, Text text) throws IOException
This will handle printing of
strings.Text
- Parameters:
text
-Text
to write.out
-Writer
to use.- Throws:
IOException
-
printElement
protected void printElement(Writer out, Element element, int level, XMLOutputter.NamespaceStack namespaces) throws IOException
- Parameters:
element
-Element
to output.out
-Writer
to use.level
-int
level of indention.namespaces
-List
stack of Namespaces in scope.- Throws:
IOException
-
printAttributes
protected void printAttributes(Writer out, List attributes, Element parent, XMLOutputter.NamespaceStack namespaces) throws IOException
This will handle printing of a
list.Attribute
- Parameters:
attributes
-List
of Attribute objctsout
-Writer
to use- Throws:
IOException
-
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.- Throws:
IllegalArgumentException
- if an entity can not be escaped
-
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.- Throws:
IllegalArgumentException
- if an entity can not be escaped
-
-