|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.jdom.output.XMLOutputter
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 constructor
creates an outputter to output the document exactly as created.
Constructor parameters control the indent amount and whether new lines
are printed between elements. The other parameters are configurable
through the set*
methods.
The XML declaration is always printed on its own line. Empty elements
are by default printed as <empty/> but that can be configured.
Text-only contents are printed as <tag>content</tag> on a
single line.
For compact machine-readable output create a default XMLOutputter and call setTextNormalize(true) to normalize any whitespace that was preserved from the source.
For pretty output, set the indent to " ", set the new lines feature to true, and set text trimming to true.
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 output(...)
and pass in your own Writer
or
OutputStream
to if possible.
Inner Class Summary | |
protected class |
XMLOutputter.NamespaceStack
Our own null subclass of NamespaceStack. |
Field Summary | |
protected static String |
STANDARD_INDENT
standard value to indent by, if we are indenting |
Constructor Summary | |
XMLOutputter()
This will create an XMLOutputter with
no additional whitespace (indent or new lines) added;
the whitespace from the element text content is fully preserved. |
|
XMLOutputter(String indent)
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. |
|
XMLOutputter(String indent,
boolean newlines)
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. |
|
XMLOutputter(String indent,
boolean newlines,
String encoding)
This will create an XMLOutputter with
the given indent and new lines printing only if newlines is
true , and encoding format encoding . |
|
XMLOutputter(XMLOutputter that)
This will create an XMLOutputter with all the
options as set in the given XMLOutputter . |
Method Summary | |
protected XMLOutputter.NamespaceStack |
createNamespaceStack()
Factory for making new NamespaceStack objects. |
protected String |
escapeAttributeEntities(String st)
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. |
protected String |
escapeElementEntities(String st)
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. |
protected void |
indent(Writer out,
int level)
This will print the proper indent characters for the given indent level. |
protected Writer |
makeWriter(OutputStream out)
Get an OutputStreamWriter, use preferred encoding. |
protected Writer |
makeWriter(OutputStream out,
String enc)
Get an OutputStreamWriter, use specified encoding. |
protected void |
maybePrintln(Writer out)
This will print a new line only if the newlines flag was set to true |
void |
output(CDATA cdata,
OutputStream out)
Print out a
|
void |
output(CDATA cdata,
Writer out)
Print out a
|
void |
output(Comment comment,
OutputStream out)
Print out a
|
void |
output(Comment comment,
Writer out)
Print out a
|
void |
output(DocType doctype,
OutputStream out)
Print out a
|
void |
output(DocType doctype,
Writer out)
Print out a
|
void |
output(Document doc,
OutputStream out)
This will print the Document to the given output stream. |
void |
output(Document doc,
Writer out)
This will print the Document to the given
Writer. |
void |
output(Element element,
OutputStream out)
Print out an , including
its s, and its value, and all
contained (child) elements etc. |
void |
output(Element element,
Writer out)
Print out an , including
its s, and its value, and all
contained (child) elements etc. |
void |
output(EntityRef entity,
OutputStream out)
Print out an . |
void |
output(EntityRef entity,
Writer out)
Print out an . |
void |
output(ProcessingInstruction pi,
OutputStream out)
Print out a
|
void |
output(ProcessingInstruction pi,
Writer out)
Print out a
|
void |
output(String string,
OutputStream out)
|
void |
output(String string,
Writer out)
Print out a . |
void |
output(Text text,
OutputStream out)
|
void |
output(Text text,
Writer out)
Print out a . |
void |
outputElementContent(Element element,
OutputStream out)
This will handle printing out an 's content only, not including its tag, and
attributes. |
void |
outputElementContent(Element element,
Writer out)
This will handle printing out an 's content only, not including its tag, and
attributes. |
String |
outputString(CDATA cdata)
Return a string representing a CDATA section. |
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. |
int |
parseArgs(String[] args,
int i)
parse command-line arguments of the form -omitEncoding
-indentSize 3 ... |
protected void |
printAttributes(List attributes,
Element parent,
Writer out,
XMLOutputter.NamespaceStack namespaces)
This will handle printing out an list. |
protected void |
printCDATA(CDATA cdata,
Writer out)
This will handle printing out an ,
and its value. |
protected void |
printComment(Comment comment,
Writer out)
This will write the comment to the specified writer. |
protected void |
printDeclaration(Document doc,
Writer out,
String encoding)
This will write the declaration to the given Writer. |
protected void |
printDocType(DocType docType,
Writer out)
This will write the DOCTYPE declaration if one exists. |
protected void |
printElement(Element element,
Writer out,
int indentLevel,
XMLOutputter.NamespaceStack namespaces)
This will handle printing out an ,
its s, and its value. |
protected void |
printElementContent(Element element,
Writer out,
int indentLevel,
XMLOutputter.NamespaceStack namespaces,
List eltContent)
This will handle printing out an 's content only, not including its tag,
attributes, and namespace info. |
protected void |
printEntityRef(EntityRef entity,
Writer out)
This will handle printing out an . |
protected void |
printProcessingInstruction(ProcessingInstruction pi,
Writer out)
This will write the processing instruction to the specified writer. |
protected void |
printString(String s,
Writer out)
Print a string. |
void |
setEncoding(String encoding)
Sets the output encoding. |
void |
setExpandEmptyElements(boolean expandEmptyElements)
This will set whether empty elements are expanded from <tagName> to
<tagName></tagName> . |
void |
setIndent(boolean doIndent)
Set the indent on or off. |
void |
setIndent(String indent)
This will set the indent String to use; this
is usually a String of empty spaces. |
void |
setIndentLevel(int indentLevel)
Deprecated. Deprecated in beta7, because this is better done with a stacked FilterOutputStream |
void |
setIndentSize(int indentSize)
This will set the indent String 's size; an indentSize
of 4 would result in the indentation being equivalent to the
String " " (four space chars). |
void |
setLineSeparator(String separator)
This will set the new-line separator. |
void |
setNewlines(boolean newlines)
|
void |
setOmitDeclaration(boolean omitDeclaration)
This will set whether the XML declaration ( <?xml version="1.0"?> )
will be omitted or not. |
void |
setOmitEncoding(boolean omitEncoding)
This will set whether the XML declaration ( <?xml version="1.0" encoding="UTF-8"?> )
includes the encoding of the document. |
void |
setPadText(boolean padText)
Deprecated. Deprecated in beta7, because this is no longer necessary |
void |
setSuppressDeclaration(boolean suppressDeclaration)
Deprecated. Deprecated in beta7, use setOmitDeclaration() instead |
void |
setTextNormalize(boolean textNormalize)
This will set whether the text is output verbatim (false) or with whitespace normalized as per . |
void |
setTrimText(boolean textTrim)
Deprecated. Deprecated in beta7, use setTextNormalize() instead |
Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Field Detail |
protected static final String STANDARD_INDENT
Constructor Detail |
public XMLOutputter()
This will create an XMLOutputter
with
no additional whitespace (indent or new lines) added;
the whitespace from the element text content is fully preserved.
public XMLOutputter(String indent)
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.
indent
- the indent string, usually some number of spacespublic XMLOutputter(String indent, boolean newlines)
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.
indent
- the indent String
, 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 an XMLOutputter
with
the given indent and new lines printing only if newlines is
true
, and encoding format encoding
.
indent
- the indent String
, 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 an XMLOutputter
with all the
options as set in the given XMLOutputter
. Note
that XMLOutputter two = (XMLOutputter)one.clone();
would work equally well.
that
- the XMLOutputter to cloneMethod Detail |
public void setLineSeparator(String separator)
This will set the new-line separator. 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.
separator
- String
line separator to use.setNewlines(boolean)
,
setTextNormalize(boolean)
public void setNewlines(boolean newlines)
newlines
- true
indicates new lines should be
printed, else new lines are ignored (compacted).setLineSeparator(String)
public void setEncoding(String encoding)
encoding
- the encoding format. Use XML-style names like
"UTF-8" or "ISO-8859-1" or "US-ASCII"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.
omitEncoding
- boolean
indicating whether or not
the XML declaration should indicate the document encoding.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.
omitDeclaration
- boolean
indicating whether or not
the XML declaration should be omitted.public void setExpandEmptyElements(boolean expandEmptyElements)
This will set whether empty elements are expanded from
<tagName>
to
<tagName></tagName>
.
expandEmptyElements
- boolean
indicating whether or not
empty elements should be expanded.public void setTextNormalize(boolean textNormalize)
This will set whether the text is output verbatim (false)
or with whitespace normalized as per
.Element.getTextNormalize()
Default: false
textNormalize
- boolean
true=>normalize the
whitespace, false=>use text verbatimpublic void setTrimText(boolean textTrim)
This will set whether the text is output verbatim (false) or with whitespace stripped.
Default: false
trimText
- boolean
true=>trim the whitespace,
false=>use text verbatimpublic void setIndent(String indent)
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.
indent
- String
to use for indentation.public void setIndent(boolean doIndent)
doIndent
- if true, set indenting on; if false, set indenting offpublic void setIndentSize(int indentSize)
This will set the indent String
's size; an indentSize
of 4 would result in the indentation being equivalent to the
String
" " (four space chars).
indentSize
- int
number of spaces in indentation.protected void indent(Writer out, int level) throws IOException
This will print the proper indent characters for the given indent level.
out
- Writer
to write tolevel
- int
indentation levelprotected void maybePrintln(Writer out) throws IOException
This will print a new line only if the newlines flag was set to true
out
- Writer
to write toprotected Writer makeWriter(OutputStream out) throws UnsupportedEncodingException
protected Writer makeWriter(OutputStream out, String enc) throws UnsupportedEncodingException
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 write to.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 write to.public void output(Element element, Writer out) throws IOException
Print out an
, including
its Element
s, and its value, and all
contained (child) elements etc.
Attribute
element
- Element
to output.out
- Writer
to write to.public void output(Element element, OutputStream out) throws IOException
Print out an
, including
its Element
s, and its value, and all
contained (child) elements etc.
Attribute
element
- Element
to output.out
- Writer
to write to.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
element
- Element
to output.out
- Writer
to write to.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
element
- Element
to output.out
- OutputStream
to write to.public void output(CDATA cdata, Writer out) throws IOException
Print out a CDATA
cdata
- CDATA
to output.out
- Writer
to write to.public void output(CDATA cdata, OutputStream out) throws IOException
Print out a CDATA
cdata
- CDATA
to output.out
- OutputStream
to write to.public void output(Comment comment, Writer out) throws IOException
Print out a Comment
comment
- Comment
to output.out
- Writer
to write to.public void output(Comment comment, OutputStream out) throws IOException
Print out a Comment
comment
- Comment
to output.out
- OutputStream
to write to.public void output(String string, Writer out) throws IOException
Print out a
. Perfoms
the necessary entity escaping and whitespace stripping. String
string
- String
to output.out
- Writer
to write to.public void output(String string, OutputStream out) throws IOException
Print out a
. Perfoms
the necessary entity escaping and whitespace stripping. String
string
- String
to output.out
- OutputStream
to write to.public void output(Text text, Writer out) throws IOException
Print out a
. Perfoms
the necessary entity escaping and whitespace stripping. Text
text
- Text
to output.out
- Writer
to write to.public void output(Text text, OutputStream out) throws IOException
Print out a
. Perfoms
the necessary entity escaping and whitespace stripping. Text
text
- Text
to output.out
- OutputStream
to write to.public void output(EntityRef entity, Writer out) throws IOException
Print out an
.
EntityRef
entity
- EntityRef
to output.out
- Writer
to write to.public void output(EntityRef entity, OutputStream out) throws IOException
Print out an
.
EntityRef
entity
- EntityRef
to output.out
- OutputStream
to write to.public void output(ProcessingInstruction pi, Writer out) throws IOException
Print out a ProcessingInstruction
element
- ProcessingInstruction
to output.out
- Writer
to write to.public void output(ProcessingInstruction pi, OutputStream out) throws IOException
Print out a ProcessingInstruction
processingInstruction
- ProcessingInstruction
to output.out
- OutputStream
to write to.public void output(DocType doctype, Writer out) throws IOException
Print out a DocType
doctype
- DocType
to output.out
- Writer
to write to.public void output(DocType doctype, OutputStream out) throws IOException
Print out a DocType
doctype
- DocType
to output.out
- OutputStream
to write to.public String outputString(Document doc)
doc
- Document
to format.public String outputString(Element element)
doc
- Element
to format.public String outputString(Comment comment)
comment
- Comment
to format.public String outputString(CDATA cdata)
cdata
- CDATA
to format.public String outputString(ProcessingInstruction pi)
doc
- ProcessingInstruction
to format.public String outputString(DocType doctype)
doc
- DocType
to format.public String outputString(EntityRef entity)
doc
- EntityRef
to format.protected void printDeclaration(Document doc, Writer out, String encoding) throws IOException
This will write the declaration to the given Writer. Assumes XML version 1.0 since we don't directly know.
doc
- Document
whose declaration to write.out
- Writer
to write to.encoding
- The encoding to add to the declarationprotected void printDocType(DocType docType, Writer out) throws IOException
This will write the DOCTYPE declaration if one exists.
doc
- Document
whose declaration to write.out
- Writer
to write to.protected void printComment(Comment comment, Writer out) throws IOException
This will write the comment to the specified writer.
comment
- Comment
to write.out
- Writer
to write to.protected void printProcessingInstruction(ProcessingInstruction pi, Writer out) throws IOException
This will write the processing instruction to the specified writer.
comment
- ProcessingInstruction
to write.out
- Writer
to write to.protected void printCDATA(CDATA cdata, Writer out) throws IOException
This will handle printing out an
,
and its value.
CDATA
cdata
- CDATA
to output.out
- Writer
to write to.protected void printElement(Element element, Writer out, int indentLevel, XMLOutputter.NamespaceStack namespaces) throws IOException
This will handle printing out an
,
its Element
s, and its value.
Attribute
element
- Element
to output.out
- Writer
to write to.indent
- int
level of indention.namespaces
- List
stack of Namespaces in scope.protected void printElementContent(Element element, Writer out, int indentLevel, XMLOutputter.NamespaceStack namespaces, List eltContent) throws IOException
This will handle printing out an
's content only, not including its tag,
attributes, and namespace info. Element
element
- Element
to output.out
- Writer
to write to.indent
- int
level of indention.protected void printString(String s, Writer out) throws IOException
protected void printEntityRef(EntityRef entity, Writer out) throws IOException
This will handle printing out an
.
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.
entity
- EntityRef
to output.out
- Writer
to write to.protected void printAttributes(List attributes, Element parent, Writer out, XMLOutputter.NamespaceStack namespaces) throws IOException
This will handle printing out an
list.
Attribute
attributes
- List
of Attribute objctsout
- Writer
to write toprotected String escapeAttributeEntities(String st)
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.
st
- String
input to escape.String
with escaped content.protected String escapeElementEntities(String st)
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.
st
- String
input to escape.String
with escaped content.public int parseArgs(String[] args, int i)
-omitEncoding
-indentSize 3 ...
protected XMLOutputter.NamespaceStack createNamespaceStack()
public void setPadText(boolean padText)
Ensure that text immediately preceded by or followed by an element will be "padded" with a single space.
public void setIndentLevel(int indentLevel)
public void setSuppressDeclaration(boolean suppressDeclaration)
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.
suppressDeclaration
- boolean
indicating whether or not
the XML declaration should be suppressed.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |