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
Format.getPrettyFormat()
. For whitespace-normalized
output, use
Format.getCompactFormat()
.
There are
output(...)
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
Format.setEncoding(String)
method. The default encoding is
UTF-8.
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.
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
Format.setOmitDeclaration(boolean)
. To omit printing of the
encoding in the declaration use
Format.setOmitEncoding(boolean)
.
Unfortunatly 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>.
clone
public Object clone()
Returns a copy of this XMLOutputter.
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.
str
- String
input to escape.
String
with escaped content.
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.
str
- String
input to escape.
String
with escaped content.
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(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>".
list
- List
of nodes.out
- OutputStream
to use.
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>".
list
- List
of nodes.out
- Writer
to use.
output
public void output(CDATA cdata,
OutputStream out)
throws IOException
cdata
- CDATA
to output.out
- OutputStream
to use.
output
public void output(CDATA cdata,
Writer out)
throws IOException
cdata
- CDATA
to output.out
- Writer
to use.
output
public void output(Comment comment,
OutputStream out)
throws IOException
comment
- Comment
to output.out
- OutputStream
to use.
output
public void output(Comment comment,
Writer out)
throws IOException
comment
- Comment
to output.out
- Writer
to use.
output
public void output(DocType doctype,
OutputStream out)
throws IOException
doctype
- DocType
to output.out
- OutputStream
to use.
output
public void output(DocType doctype,
Writer out)
throws IOException
doctype
- DocType
to output.out
- Writer
to use.
output
public void output(Document doc,
OutputStream out)
throws IOException
This will print the Document
to the given output stream.
The characters are printed using the encoding specified in the
constructor, or a default of UTF-8.
doc
- Document
to format.out
- OutputStream
to use.
output
public void output(Document doc,
Writer out)
throws IOException
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.
doc
- Document
to format.out
- Writer
to use.
output
public void output(Element element,
OutputStream out)
throws IOException
Print out an
Element
, including
its
Attribute
s, and all
contained (child) elements, etc.
element
- Element
to output.out
- Writer
to use.
output
public void output(Element element,
Writer out)
throws IOException
Print out an
Element
, including
its
Attribute
s, and all
contained (child) elements, etc.
element
- Element
to output.out
- Writer
to use.
output
public void output(EntityRef entity,
OutputStream out)
throws IOException
entity
- EntityRef
to output.out
- OutputStream
to use.
output
public void output(EntityRef entity,
Writer out)
throws IOException
entity
- EntityRef
to output.out
- Writer
to use.
output
public void output(ProcessingInstruction pi,
OutputStream out)
throws IOException
pi
- ProcessingInstruction
to output.out
- OutputStream
to use.
output
public void output(ProcessingInstruction pi,
Writer out)
throws IOException
pi
- ProcessingInstruction
to output.out
- Writer
to use.
output
public void output(Text text,
OutputStream out)
throws IOException
Print out a
Text
node. Perfoms
the necessary entity escaping and whitespace stripping.
text
- Text
to output.out
- OutputStream
to use.
output
public void output(Text text,
Writer out)
throws IOException
Print out a
Text
node. Perfoms
the necessary entity escaping and whitespace stripping.
text
- Text
to output.out
- Writer
to use.
outputElementContent
public void outputElementContent(Element element,
OutputStream out)
throws 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>".
element
- Element
to output.out
- OutputStream
to use.
outputElementContent
public void outputElementContent(Element element,
Writer out)
throws 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>".
element
- Element
to output.out
- Writer
to use.
outputString
public String outputString(List list)
Return a string representing a list of nodes. The list is
assumed to contain legal JDOM nodes.
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.
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.
comment
- Comment
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.
doctype
- DocType
to format.
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.
doc
- Document
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.
element
- Element
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.
entity
- EntityRef
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.
pi
- ProcessingInstruction
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.
printAttributes
protected void printAttributes(Writer out,
List attributes,
Element parent,
org.jdom.output.NamespaceStack namespaces)
throws IOException
This will handle printing of a
Attribute
list.
out
- Writer
to useattributes
- List
of Attribute objcts
printCDATA
protected void printCDATA(Writer out,
CDATA cdata)
throws IOException
This will handle printing of
CDATA
text.
out
- Writer
to use.cdata
- CDATA
to output.
printComment
protected void printComment(Writer out,
Comment comment)
throws IOException
This will handle printing of comments.
out
- Writer
to use.comment
- Comment
to write.
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.
out
- Writer
to use.doc
- Document
whose declaration to write.encoding
- The encoding to add to the declaration
printDocType
protected void printDocType(Writer out,
DocType docType)
throws IOException
This handle printing the DOCTYPE declaration if one exists.
out
- Writer
to use.docType
- Document
whose declaration to write.
printElement
protected void printElement(Writer out,
Element element,
int level,
org.jdom.output.NamespaceStack namespaces)
throws IOException
This will handle printing of a
Element
,
its
Attribute
s, and all contained (child)
elements, etc.
out
- Writer
to use.element
- Element
to output.level
- int
level of indention.namespaces
- List
stack of Namespaces in scope.
printEntityRef
protected void printEntityRef(Writer out,
EntityRef entity)
throws IOException
This will handle printing a
EntityRef
.
Only the entity reference such as
&entity;
will be printed. However, subclasses are free to override
this method to print the contents of the entity instead.
out
- Writer
to use.entity
- EntityRef
to output.
printProcessingInstruction
protected void printProcessingInstruction(Writer out,
ProcessingInstruction pi)
throws IOException
This will handle printing of processing instructions.
out
- Writer
to use.pi
- ProcessingInstruction
to write.
printText
protected void printText(Writer out,
Text text)
throws IOException
This will handle printing of
Text
strings.
out
- Writer
to use.text
- Text
to write.
setFormat
public void setFormat(Format newFormat)
Sets the new format logic for the outputter. Note the Format
object is cloned internally before use.
newFormat
- the format to use for output
toString
public String toString()
Return a string listing of the settings for this
XMLOutputter instance.
- a string listing the settings for this XMLOutputter instance