org.jdom.output
public class XMLOutputter extends Object implements Cloneable
XMLOutputter
takes a JDOM tree and formats it to a
stream as XML. 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 with the various set*()
methods.
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 XMLOutputter. 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 XMLOutputter manually in its
constructor or via the setEncoding() method. The default XMLOutputter
encoding is UTF-8.
The methods outputString(...)
are for convenience
only; for top performance you should call one of the
output(...)
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 setOmitDeclaration
.
To omit printing of the encoding in the declaration use
setOmitEncoding
. 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 setExpandEmptyElements
to cause them to
be expanded to <empty></empty>.
Several modes are available to effect the way textual content is printed. All modes are configurable through corresponding set*() methods. Below is a table which explains the modes and the effect on the resulting output.
Text Mode | Resulting behavior. |
---|---|
Default | All content is printed in the format it was created, no whitespace or line separators are are added or removed. |
TrimAllWhite | Content between tags consisting of all whitespace is not printed. If the content contains even one non-whitespace character, it is printed verbatim, whitespace and all. |
TextTrim | Same as TrimAllWhite, plus leading/trailing whitespace are trimmed. |
TextNormalize | Same as TextTrim, in addition interior whitespace is compressed to a single space. |
For pretty-print output, use setNewlines
in conjunction
with setIndent
. Setting newlines to true
causes
tags to be aligned and possibly indented. With newlines true
,
whitespace might be added back to fit alignment needs. In most cases
texual content is aligned with the surrounding tags (after the
appropriate text mode is applied). In the case where the only content
between the start and end tags is textual, the start tag, text, and end
tag are all printed on the same line.
When a element has a xml:space attribute with the value of "preserve", all formating is turned off and reverts back to the default until the element and it's contents have been printed. If a nested element contains another xml:space with the value "default" formatting is turned back on for the child element and then off for the remainder of the parent element.
Version: $Revision: 1.76 $, $Date: 2002/03/15 05:36:48 $
Nested Class Summary | |
---|---|
protected class | XMLOutputter.NamespaceStack Our own null subclass of NamespaceStack. |
Constructor Summary | |
---|---|
XMLOutputter()
This will create an | |
XMLOutputter(String indent)
This will create an | |
XMLOutputter(String indent, boolean newlines)
This will create an | |
XMLOutputter(String indent, boolean newlines, String encoding)
This will create an | |
XMLOutputter(XMLOutputter that)
This will create an |
Method Summary | |
---|---|
Object | clone()
Returns a copy of this XMLOutputter. |
protected XMLOutputter.NamespaceStack | createNamespaceStack() Factory for making new NamespaceStack objects. |
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. |
protected void | indent(Writer out)
This will print indents (only if the newlines flag was
set to |
protected void | indent(Writer out, int level)
This will print indents (only if the newlines flag was
set to |
protected Writer | makeWriter(OutputStream out) Get an OutputStreamWriter, using prefered encoding (see XMLOutputter). |
protected Writer | makeWriter(OutputStream out, String enc) Get an OutputStreamWriter, use specified encoding. |
protected void | newline(Writer out) This will print a new line only if the newlines flag was set to true. |
void | output(Document doc, OutputStream out)
This will print the |
void | output(DocType doctype, OutputStream out)
Print out the |
void | output(Element element, OutputStream out) |
void | output(List list, OutputStream out) This will handle printing out a list of nodes. |
void | output(CDATA cdata, OutputStream out)
Print out a |
void | output(Text text, OutputStream out)
Print out a |
void | output(String string, OutputStream out)
Print out a |
void | output(Comment comment, OutputStream out)
Print out a |
void | output(ProcessingInstruction pi, OutputStream out)
Print out a |
void | output(EntityRef entity, OutputStream out)
Print out a |
void | output(Document doc, Writer out)
This will print the |
void | output(DocType doctype, Writer out)
Print out the |
void | output(Element element, Writer out) |
void | output(List list, Writer out) This will handle printing out a list of nodes. |
void | output(CDATA cdata, Writer out)
Print out a |
void | output(Text text, Writer out)
Print out a |
void | output(String string, Writer out)
Print out a |
void | output(Comment comment, Writer out)
Print out a |
void | output(ProcessingInstruction pi, Writer out)
Print out a |
void | output(EntityRef entity, Writer out)
Print out a |
void | outputElementContent(Element element, OutputStream out)
This will handle printing out an Element 's content only, not including its tag, and
attributes. |
void | outputElementContent(Element element, Writer out)
This will handle printing out an |
String | outputString(Document doc) Return a string representing a document. |
String | outputString(DocType doctype) Return a string representing a DocType. |
String | outputString(Element element) Return a string representing an 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(Text text) Return a string representing a Text node. |
String | outputString(String str)
Return a string representing (with trimming, normalizatio, and
escaping possibly applied) a |
String | outputString(Comment comment) Return a string representing a comment. |
String | outputString(ProcessingInstruction pi) Return a string representing a PI. |
String | outputString(EntityRef entity) Return a string representing an entity. |
int | parseArgs(String[] args, int i)
Parse command-line arguments of the form |
protected void | printAttributes(List attributes, Element parent, Writer out, XMLOutputter.NamespaceStack namespaces)
This will handle printing of a |
protected void | printCDATA(CDATA cdata, Writer out)
This will handle printing of |
protected void | printComment(Comment comment, Writer out) This will handle printing of comments. |
protected void | printContent(List content, Writer out, int level, XMLOutputter.NamespaceStack namespaces)
This will handle printing of a |
protected void | printContentRange(List content, int start, int end, Writer out, int level, XMLOutputter.NamespaceStack namespaces) This will handle printing of content within a given range. |
protected void | printDeclaration(Document doc, Writer out, String encoding) This will handle printing of the declaration. |
protected void | printDocType(DocType docType, Writer out) This handle printing the DOCTYPE declaration if one exists. |
protected void | printElement(Element element, Writer out, int level, XMLOutputter.NamespaceStack namespaces) |
protected void | printElementContent(Element element, Writer out, int level, XMLOutputter.NamespaceStack namespaces)
This will handle printing of a |
protected void | printEntityRef(EntityRef entity, Writer out)
This will handle printing a |
protected void | printProcessingInstruction(ProcessingInstruction pi, Writer out) This will handle printing of processing instructions. |
protected void | printString(String str, Writer out)
This will handle printing a string. |
protected void | printText(Text text, Writer out)
This will handle printing of |
protected void | printTextRange(List content, int start, int end, Writer out) |
void | setEncoding(String encoding) Sets the output encoding. |
void | setExpandEmptyElements(boolean expandEmptyElements)
This will set whether empty elements are expanded from
|
void | setIndent(String indent)
This will set the indent |
void | setIndent(boolean doIndent)
Set the indent on or off, newlines must be set to |
void | setIndent(int size)
This will set the indent |
void | setIndentLevel(int level) Set the initial indentation level. |
void | setIndentSize(int indentSize)
This will set the indent |
void | setLineSeparator(String separator)
This will set the newline separator ( |
void | setNewlines(boolean newlines)
Sets whether newlines ( |
void | setOmitDeclaration(boolean omitDeclaration)
This will set whether the XML declaration
( |
void | setOmitEncoding(boolean omitEncoding)
This will set whether the XML declaration
( |
void | setPadText(boolean padText) Ensure that text immediately preceded by or followed by an element will be "padded" with a single space. |
void | setSuppressDeclaration(boolean suppressDeclaration)
This will set whether the XML declaration
( |
void | setTextNormalize(boolean textNormalize)
This will set whether the text is output verbatim (false)
or with whitespace normalized as per |
void | setTextTrim(boolean textTrim) This will set whether the text has leading/trailing whitespace trimmed. |
void | setTrimAllWhite(boolean trimAllWhite) This will set whether content between tags consisting of all whitespace is printed or trimmed. |
String | toString() Return a string listing of the settings for this XMLOutputter instance. |
This will create an XMLOutputter
with no additional
whitespace (indent or newlines) added; the whitespace from the
element text content is fully preserved.
This will create an XMLOutputter
with the given indent
added but no new lines added; all whitespace from the element text
content is included as well.
Parameters: indent the indent string, usually some number of spaces
This will create an XMLOutputter
with the given indent
that prints newlines only if newlines
is
true
; all whitespace from the element text content is
included as well.
Parameters: indent the indent String
, usually some number
of spaces newlines true
indicates new lines should be
printed, else new lines are ignored (compacted).
This will create an XMLOutputter
with
the given indent and new lines printing only if
newlines
is true
, and encoding format
encoding
.
Parameters: indent the indent String
, usually some number
of spaces newlines true
indicates new lines should be
printed, else new lines are ignored (compacted). encoding set encoding format. Use XML-style names like
"UTF-8" or "ISO-8859-1" or "US-ASCII"
This will create an XMLOutputter
with all the
options as set in the given XMLOutputter
. Note
that XMLOutputter two = (XMLOutputter)one.clone();
would work equally well.
Parameters: that the XMLOutputter to clone
Factory for making new NamespaceStack objects. The NamespaceStack created is actually an inner class extending the package protected NamespaceStack, as a way to make NamespaceStack "friendly" toward subclassers.
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 no converstion for ' 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.
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: st String
input to escape.
Returns: String
with escaped content.
Deprecated: since it's never used in XMLOutputter, used in XMLOutputter indent( out, 0) instead
This will print indents (only if the newlines flag was
set to true
, and indent is non-null).
Parameters: out Writer
to use level current indent level (number of tabs)
This will print indents (only if the newlines flag was
set to true
, and indent is non-null).
Parameters: out Writer
to use level current indent level (number of tabs)
Get an OutputStreamWriter, using prefered encoding (see XMLOutputter).
Get an OutputStreamWriter, use specified encoding.
This will print a new line only if the newlines flag was set to true.
Parameters: out Writer
to use
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.
Parameters: doc Document
to format. out OutputStream
to use.
Throws: IOException - if there's any problem writing.
Print out the DocType
.
Parameters: doctype DocType
to output. out OutputStream
to use.
Print out an Element
, including
it's Attribute
s, and all
contained (child) elements, etc.
Parameters: element Element
to output. out Writer
to use.
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.
Print out a CDATA
node.
Parameters: cdata CDATA
to output. out OutputStream
to use.
Print out a Text
node. Perfoms
the necessary entity escaping and whitespace stripping.
Parameters: text Text
to output. out OutputStream
to use.
Deprecated: see output(Text
,OutputStream
)
Print out a java.lang.String
. Perfoms
the necessary entity escaping and whitespace stripping.
Parameters: string String
to output. out OutputStream
to use.
Print out a Comment
.
Parameters: comment Comment
to output. out OutputStream
to use.
Print out a ProcessingInstruction
.
Parameters: processingInstruction ProcessingInstruction
to output. out OutputStream
to use.
Print out a EntityRef
.
Parameters: entity EntityRef
to output. out OutputStream
to use.
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.
Print out the DocType
.
Parameters: doctype DocType
to output. out Writer
to use.
Print out an Element
, including
it's Attribute
s, and all
contained (child) elements, etc.
Parameters: element Element
to output. out Writer
to use.
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.
Print out a CDATA
node.
Parameters: cdata CDATA
to output. out Writer
to use.
Print out a Text
node. Perfoms
the necessary entity escaping and whitespace stripping.
Parameters: text Text
to output. out Writer
to use.
Deprecated: see output(Text
,Writer
)
Print out a java.lang.String
. Perfoms
the necessary entity escaping and whitespace stripping.
Parameters: string String
to output. out Writer
to use.
Print out a Comment
.
Parameters: comment Comment
to output. out Writer
to use.
Print out a ProcessingInstruction
.
Parameters: element ProcessingInstruction
to output. out Writer
to use.
Print out a EntityRef
.
Parameters: entity EntityRef
to output. out Writer
to use.
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>".
Parameters: element Element
to output. out OutputStream
to use.
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>".
Parameters: element Element
to output. out Writer
to use.
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.
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.
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.
Return a string representing a list of nodes. The list is assumed to contain legal JDOM nodes.
Parameters: list List
to format.
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.
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.
Return a string representing (with trimming, normalizatio, and
escaping possibly applied) a String
. Warning: a
String is Unicode, which may not match the outputter's specified
encoding.
Parameters: str String
to format.
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.
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.
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.
Parse command-line arguments of the form -omitEncoding
-indentSize 3 ...
Returns: int index of first parameter that we didn't understand
This will handle printing of a Attribute
list.
Parameters: attributes List
of Attribute objcts out Writer
to use
This will handle printing of CDATA
text.
Parameters: cdata CDATA
to output. out Writer
to use.
This will handle printing of comments.
Parameters: comment Comment
to write. out Writer
to use.
This will handle printing of a Element
's content only, not including it's tag,
attributes, or namespace info.
Parameters: content List
of content to output. out Writer
to use. level int
level of indentation. namespaces List
stack of Namespaces in scope.
This will handle printing of content within a given range. The range to print is specified in typical Java fashion; the starting index is inclusive, while the ending index is exclusive.
Parameters: content List
of content to output starting index of first content node (inclusive. ending index of last content node (exclusive). out Writer
to use. level int
level of indentation. namespaces List
stack of Namespaces in scope.
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
This handle printing the DOCTYPE declaration if one exists.
Parameters: doc Document
whose declaration to write. out Writer
to use.
This will handle printing of a Element
,
it's Attribute
s, and all contained (child)
elements, etc.
Parameters: element Element
to output. out Writer
to use. indent int
level of indention. namespaces List
stack of Namespaces in scope.
This will handle printing of a Element
's content only, not including it's tag,
attributes, or namespace info.
Parameters: element Element
to output. out Writer
to use. level int
level of indentation. namespaces List
stack of Namespaces in scope.
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.
Parameters: entity EntityRef
to output. out Writer
to use.
This will handle printing of processing instructions.
Parameters: comment ProcessingInstruction
to write. out Writer
to use.
This will handle printing of Text
strings.
Parameters: text Text
to write. out Writer
to use.
This will handle printing of a sequence of CDATA
or Text
nodes. It is a error to have any other
pass this method any other type of node.
Parameters: content List
of content to output starting index of first content node (inclusive). ending index of last content node (exclusive). out Writer
to use.
Sets the output encoding. The name should be an accepted XML encoding.
Parameters: encoding the encoding format. Use XML-style names like "UTF-8" or "ISO-8859-1" or "US-ASCII"
This will set whether empty elements are expanded from
<tagName/>
to
<tagName></tagName>
.
Parameters: expandEmptyElements boolean
indicating whether or not
empty elements should be expanded.
This will set the indent String
to use; this
is usually a String
of empty spaces. If you pass
null, or the empty string (""), then no indentation will
happen. Default: none (null)
Parameters: indent String
to use for indentation.
Set the indent on or off, newlines must be set to true
for indentation to actually occur. If setting on, will use the
value of STANDARD_INDENT, which is usually two spaces.
Parameters: doIndent if true, set indenting on; if false, set indenting off
This will set the indent String
's size; a size
of 4 would result in the indentation being equivalent to the
String
" " (four spaces).
Parameters: size int
number of spaces in indentation.
Deprecated: Deprecated in beta7, because this is better done with a stacked FilterOutputStream
Set the initial indentation level.
This will set the indent String
's size; an indentSize
of 4 would result in the indentation being equivalent to the
String
" " (four spaces).
Parameters: indentSize int
number of spaces in indentation.
This will set the newline separator (lineSeparator
).
The default is \r\n
. Note that if the "newlines"
property is false, this value is irrelevant. To make it output
the system default line ending string, call
setLineSeparator(System.getProperty("line.separator"))
To output "UNIX-style" documents, call
setLineSeparator("\n")
. To output "Mac-style"
documents, call setLineSeparator("\r")
. DOS-style
documents use CR-LF ("\r\n"), which is the default.
Note that this only applies to newlines generated by the
outputter. If you parse an XML document that contains newlines
embedded inside a text node, and you do not call
setTextNormalize
, then the newlines will be output
verbatim, as "\n" which is how parsers normalize them.
Parameters: separator String
line separator to use.
See Also: XMLOutputter
Sets whether newlines (lineSeparator
) should
be printed.
Parameters: newlines true
indicates new lines should be
printed, else new lines are ignored (compacted).
See Also: setLineSeparator
This will set whether the XML declaration
(<?xml version="1.0"?>
)
will be omitted or not. It is common to omit this in uses such
as SOAP and XML-RPC calls.
Parameters: omitDeclaration boolean
indicating whether or not
the XML declaration should be omitted.
This will set whether the XML declaration
(<?xml version="1.0" encoding="UTF-8"?>
)
includes the encoding of the document. It is common to omit
this in uses such as WML and other wireless device protocols.
Parameters: omitEncoding boolean
indicating whether or not
the XML declaration should indicate the document encoding.
Deprecated: Deprecated in beta7, because this is no longer necessary
Ensure that text immediately preceded by or followed by an element will be "padded" with a single space.
Deprecated: Deprecated in beta7, use setOmitDeclaration() instead
This will set whether the XML declaration
(<?xml version="1.0"?>
)
will be suppressed or not. It is common to suppress this in uses such
as SOAP and XML-RPC calls.
Parameters: suppressDeclaration boolean
indicating whether or not
the XML declaration should be suppressed.
This will set whether the text is output verbatim (false)
or with whitespace normalized as per getTextNormalize
.
Default: false
Parameters: textNormalize boolean
true=>normalize the
whitespace, false=>use text verbatim
This will set whether the text has leading/trailing whitespace trimmed.
Default: false
Parameters: textTrim boolean
true=>trim the leading/trailing
whitespace, false=>use text verbatim
This will set whether content between tags consisting of all whitespace is printed or trimmed.
Default: false
Parameters: trimAllWhite boolean
true=>content consisting of
only whitespace is not print, false=>use text verbatim
Return a string listing of the settings for this XMLOutputter instance.
Returns: a string listing the settings for this XMLOutputter instance