Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
org.jdom.output.XMLOutputter
public class XMLOutputter
extends java.lang.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. |
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.
Nested Class Summary | |
protected class |
|
Constructor Summary | |
| |
| |
| |
| |
|
Method Summary | |
Object |
|
protected org.jdom.output.NamespaceStack |
|
String |
|
String |
|
protected void |
|
protected void |
|
protected Writer |
|
protected Writer |
|
protected void |
|
void |
|
void |
|
void |
|
void |
|
void | |
void | |
void | |
void | |
void | |
void | |
void | |
void | |
void | |
void | |
void | |
void | |
void |
|
void |
|
void | |
void | |
void |
|
void |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
int |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected void | |
protected void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
String |
|
public XMLOutputter()
This will create anXMLOutputter
with no additional whitespace (indent or newlines) added; the whitespace from the element text content is fully preserved.
public XMLOutputter(String indent)
This will create anXMLOutputter
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
public XMLOutputter(String indent, boolean newlines)
This will create anXMLOutputter
with the given indent that prints newlines only ifnewlines
istrue
; all whitespace from the element text content is included as well.
- Parameters:
indent
- the indentString
, usually some number of spacesnewlines
-true
indicates new lines should be printed, else new lines are ignored (compacted).
public XMLOutputter(String indent, boolean newlines, String encoding)
This will create anXMLOutputter
with the given indent and new lines printing only ifnewlines
istrue
, and encoding formatencoding
.
- Parameters:
indent
- the indentString
, usually some number of spacesnewlines
-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"
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
public Object clone()
Returns a copy of this XMLOutputter.
protected org.jdom.output.NamespaceStack createNamespaceStack()
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.
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 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.
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:
- Returns:
String
with escaped content.
protected void indent(Writer out) throws IOException
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 totrue
, and indent is non-null).
- Parameters:
out
-Writer
to use
protected void indent(Writer out, int level) throws IOException
This will print indents (only if the newlines flag was set totrue
, and indent is non-null).
- Parameters:
out
-Writer
to uselevel
- current indent level (number of tabs)
protected Writer makeWriter(OutputStream out) throws java.io.UnsupportedEncodingException
Get an OutputStreamWriter, using prefered encoding (seesetEncoding(String)
).
protected Writer makeWriter(OutputStream out, String enc) throws java.io.UnsupportedEncodingException
Get an OutputStreamWriter, use specified encoding.
protected void newline(Writer out) throws IOException
This will print a new line only if the newlines flag was set to true.
- Parameters:
out
-Writer
to use
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.
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.
public void output(String string, OutputStream out) throws IOException
Deprecated. see output(
Text
,OutputStream
)Print out a. Perfoms the necessary entity escaping and whitespace stripping.
java.lang.String
- Parameters:
string
-String
to output.out
-OutputStream
to use.
public void output(String string, Writer out) throws IOException
Deprecated. see output(
Text
,Writer
)Print out a. Perfoms the necessary entity escaping and whitespace stripping.
java.lang.String
- Parameters:
string
-String
to output.out
-Writer
to use.
public void output(CDATA cdata, OutputStream out) throws IOException
Print out anode.
CDATA
- Parameters:
cdata
-CDATA
to output.out
-OutputStream
to use.
public void output(CDATA cdata, Writer out) throws IOException
Print out anode.
CDATA
- Parameters:
cdata
-CDATA
to output.out
-Writer
to use.
public void output(Comment comment, OutputStream out) throws IOException
Print out a.
Comment
- Parameters:
comment
-Comment
to output.out
-OutputStream
to use.
public void output(Comment comment, Writer out) throws IOException
Print out a.
Comment
- Parameters:
comment
-Comment
to output.out
-Writer
to use.
public void output(DocType doctype, OutputStream out) throws IOException
Print out the.
DocType
- Parameters:
doctype
-DocType
to output.out
-OutputStream
to use.
public void output(DocType doctype, Writer out) throws IOException
Print out the.
DocType
- Parameters:
doctype
-DocType
to output.out
-Writer
to use.
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.
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.
public void output(Element element, OutputStream out) throws IOException
- Parameters:
element
-Element
to output.out
-Writer
to use.
public void output(Element element, Writer out) throws IOException
- Parameters:
element
-Element
to output.out
-Writer
to use.
public void output(EntityRef entity, OutputStream out) throws IOException
Print out a.
EntityRef
- Parameters:
entity
-EntityRef
to output.out
-OutputStream
to use.
public void output(EntityRef entity, Writer out) throws IOException
Print out a.
EntityRef
- Parameters:
entity
-EntityRef
to output.out
-Writer
to use.
public void output(ProcessingInstruction pi, OutputStream out) throws IOException
Print out a.
ProcessingInstruction
- Parameters:
out
-OutputStream
to use.
public void output(ProcessingInstruction pi, Writer out) throws IOException
Print out a.
ProcessingInstruction
- Parameters:
out
-Writer
to use.
public void output(Text text, OutputStream out) throws IOException
Print out anode. Perfoms the necessary entity escaping and whitespace stripping.
Text
- Parameters:
text
-Text
to output.out
-OutputStream
to use.
public void output(Text text, Writer out) throws IOException
Print out anode. Perfoms the necessary entity escaping and whitespace stripping.
Text
- Parameters:
text
-Text
to output.out
-Writer
to use.
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.
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.
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.
public String outputString(String str)
Return a string representing (with trimming, normalizatio, and escaping possibly applied) aString
. Warning: a String is Unicode, which may not match the outputter's specified encoding.
- Parameters:
str
-String
to format.
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.
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.
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.
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.
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.
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.
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.
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.
public int parseArgs(String[] args, int i)
Parse command-line arguments of the form-omitEncoding -indentSize 3 ...
- Returns:
- int index of first parameter that we didn't understand
protected void printAttributes(List attributes, Element parent, Writer out, org.jdom.output.NamespaceStack namespaces) throws IOException
This will handle printing of alist.
Attribute
- Parameters:
attributes
-List
of Attribute objctsout
-Writer
to use
protected void printCDATA(CDATA cdata, Writer out) throws IOException
This will handle printing oftext.
CDATA
- Parameters:
cdata
-CDATA
to output.out
-Writer
to use.
protected void printComment(Comment comment, Writer out) throws IOException
This will handle printing of comments.
- Parameters:
comment
-Comment
to write.out
-Writer
to use.
protected void printContent(List content, Writer out, int level, org.jdom.output.NamespaceStack namespaces) throws IOException
This will handle printing of a's content only, not including it's tag, attributes, or namespace info.
Element
- Parameters:
content
-List
of content to output.out
-Writer
to use.level
-int
level of indentation.namespaces
-List
stack of Namespaces in scope.
protected void printContentRange(List content, int start, int end, Writer out, int level, org.jdom.output.NamespaceStack namespaces) throws IOException
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 outputout
-Writer
to use.level
-int
level of indentation.namespaces
-List
stack of Namespaces in scope.
protected void printDeclaration(Document doc, Writer out, 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
protected void printDocType(DocType docType, Writer out) throws IOException
This handle printing the DOCTYPE declaration if one exists.
- Parameters:
out
-Writer
to use.
protected void printElement(Element element, Writer out, int level, org.jdom.output.NamespaceStack namespaces) throws IOException
- Parameters:
element
-Element
to output.out
-Writer
to use.namespaces
-List
stack of Namespaces in scope.
protected void printElementContent(Element element, Writer out, int level, org.jdom.output.NamespaceStack namespaces) throws IOException
This will handle printing of a's content only, not including it's tag, attributes, or namespace info.
Element
- Parameters:
element
-Element
to output.out
-Writer
to use.level
-int
level of indentation.namespaces
-List
stack of Namespaces in scope.
protected void printEntityRef(EntityRef entity, Writer out) throws IOException
This will handle printing a. Only the entity reference such as
EntityRef
&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.
protected void printProcessingInstruction(ProcessingInstruction pi, Writer out) throws IOException
This will handle printing of processing instructions.
- Parameters:
out
-Writer
to use.
protected void printString(String str, Writer out) throws IOException
This will handle printing a string. Escapes the element entities, trims interior whitespace, etc. if necessary.
protected void printText(Text text, Writer out) throws IOException
This will handle printing ofstrings.
Text
- Parameters:
text
-Text
to write.out
-Writer
to use.
protected void printTextRange(List content, int start, int end, Writer out) throws IOException
This will handle printing of a sequence ofor
CDATA
nodes. It is a error to have any other pass this method any other type of node.
Text
- Parameters:
content
-List
of content to outputout
-Writer
to use.
public void setEncoding(String encoding)
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"
public void setExpandEmptyElements(boolean expandEmptyElements)
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.
public void setIndent(String indent)
This will set the indentString
to use; this is usually aString
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.
public void setIndent(boolean doIndent)
Set the indent on or off, newlines must be set totrue
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
public void setIndent(int size)
This will set the indentString
's size; a size of 4 would result in the indentation being equivalent to theString
" " (four spaces).
- Parameters:
size
-int
number of spaces in indentation.
public void setIndentLevel(int level)
Deprecated. Deprecated in beta7, because this is better done with a stacked FilterOutputStream
Set the initial indentation level.
public void setIndentSize(int indentSize)
This will set the indentString
's size; an indentSize of 4 would result in the indentation being equivalent to theString
" " (four spaces).
- Parameters:
indentSize
-int
number of spaces in indentation.
public void setLineSeparator(String separator)
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, callsetLineSeparator(System.getProperty("line.separator"))
To output "UNIX-style" documents, callsetLineSeparator("\n")
. To output "Mac-style" documents, callsetLineSeparator("\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 callsetTextNormalize
, then the newlines will be output verbatim, as "\n" which is how parsers normalize them.
- Parameters:
separator
-String
line separator to use.
public void setNewlines(boolean newlines)
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(String)
public void setOmitDeclaration(boolean omitDeclaration)
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.
public void setOmitEncoding(boolean omitEncoding)
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.
public void setPadText(boolean padText)
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.
public void setSuppressDeclaration(boolean suppressDeclaration)
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.
public void setTextNormalize(boolean textNormalize)
This will set whether the text is output verbatim (false) or with whitespace normalized as per. Default: false
Element.getTextNormalize()
- Parameters:
textNormalize
-boolean
true=>normalize the whitespace, false=>use text verbatim
public void setTextTrim(boolean textTrim)
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
public void setTrimAllWhite(boolean trimAllWhite)
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
public String toString()
Return a string listing of the settings for this XMLOutputter instance.
- Returns:
- a string listing the settings for this XMLOutputter instance