Public Member Functions | |
XMLOutputter () | |
XMLOutputter (String indent) | |
XMLOutputter (String indent, boolean newlines) | |
XMLOutputter (String indent, boolean newlines, String encoding) | |
XMLOutputter (XMLOutputter that) | |
void | setLineSeparator (String separator) |
void | setNewlines (boolean newlines) |
void | setEncoding (String encoding) |
void | setOmitEncoding (boolean omitEncoding) |
void | setOmitDeclaration (boolean omitDeclaration) |
void | setExpandEmptyElements (boolean expandEmptyElements) |
void | setTrimAllWhite (boolean trimAllWhite) |
void | setTextTrim (boolean textTrim) |
void | setTextNormalize (boolean textNormalize) |
void | setIndent (String indent) |
void | output (Document doc, OutputStream out) throws IOException |
void | output (DocType doctype, OutputStream out) throws IOException |
void | output (Element element, OutputStream out) throws IOException |
void | outputElementContent (Element element, OutputStream out) throws IOException |
void | output (List list, OutputStream out) throws IOException |
void | output (CDATA cdata, OutputStream out) throws IOException |
void | output (Text text, OutputStream out) throws IOException |
void | output (Comment comment, OutputStream out) throws IOException |
void | output (ProcessingInstruction pi, OutputStream out) throws IOException |
void | output (EntityRef entity, OutputStream out) throws IOException |
void | output (Document doc, Writer out) throws IOException |
void | output (DocType doctype, Writer out) throws IOException |
void | output (Element element, Writer out) throws IOException |
void | outputElementContent (Element element, Writer out) throws IOException |
void | output (List list, Writer out) throws IOException |
void | output (CDATA cdata, Writer out) throws IOException |
void | output (Text text, Writer out) throws IOException |
void | output (Comment comment, Writer out) throws IOException |
void | output (ProcessingInstruction pi, Writer out) throws IOException |
void | output (EntityRef entity, Writer out) throws IOException |
String | outputString (Document doc) |
String | outputString (DocType doctype) |
String | outputString (Element element) |
String | outputString (List list) |
String | outputString (CDATA cdata) |
String | outputString (Text text) |
String | outputString (Comment comment) |
String | outputString (ProcessingInstruction pi) |
String | outputString (EntityRef entity) |
String | escapeAttributeEntities (String str) |
String | escapeElementEntities (String str) |
int | parseArgs (String[] args, int i) |
Object | clone () |
String | toString () |
void | output (String string, OutputStream out) throws IOException |
void | output (String string, Writer out) throws IOException |
void | setIndent (boolean doIndent) |
void | setIndent (int size) |
void | setIndentSize (int indentSize) |
String | outputString (String str) |
Protected Member Functions | |
Writer | makeWriter (OutputStream out) throws java.io.UnsupportedEncodingException |
Writer | makeWriter (OutputStream out, String enc) throws java.io.UnsupportedEncodingException |
void | printDeclaration (Document doc, Writer out, String encoding) throws IOException |
void | printDocType (DocType docType, Writer out) throws IOException |
void | printComment (Comment comment, Writer out) throws IOException |
void | printProcessingInstruction (ProcessingInstruction pi, Writer out) throws IOException |
void | printEntityRef (EntityRef entity, Writer out) throws IOException |
void | printCDATA (CDATA cdata, Writer out) throws IOException |
void | printText (Text text, Writer out) throws IOException |
void | printString (String str, Writer out) throws IOException |
void | printElement (Element element, Writer out, int level, NamespaceStack namespaces) throws IOException |
void | printContentRange (List content, int start, int end, Writer out, int level, NamespaceStack namespaces) throws IOException |
void | printTextRange (List content, int start, int end, Writer out) throws IOException |
void | printAttributes (List attributes, Element parent, Writer out, NamespaceStack namespaces) throws IOException |
void | newline (Writer out) throws IOException |
void | indent (Writer out, int level) throws IOException |
NamespaceStack | createNamespaceStack () |
Package Attributes | |
Format | noFormatting = new Format() |
Format | defaultFormat = new Format() |
Format | currentFormat = defaultFormat |
Classes | |
class | Format |
class | NamespaceStack |
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 its 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.
,
org::jdom::output::XMLOutputter::XMLOutputter | ( | ) | [inline] |
This will create an XMLOutputter
with no additional whitespace (indent or newlines) added; the whitespace from the element text content is fully preserved.
org::jdom::output::XMLOutputter::XMLOutputter | ( | String | indent | ) | [inline] |
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 spaces |
org::jdom::output::XMLOutputter::XMLOutputter | ( | String | indent, | |
boolean | newlines | |||
) | [inline] |
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 spaces | |
newlines | true indicates new lines should be printed, else new lines are ignored (compacted). |
org::jdom::output::XMLOutputter::XMLOutputter | ( | String | indent, | |
boolean | newlines, | |||
String | encoding | |||
) | [inline] |
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 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" |
org::jdom::output::XMLOutputter::XMLOutputter | ( | XMLOutputter | that | ) | [inline] |
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 clone |
void org::jdom::output::XMLOutputter::setLineSeparator | ( | String | separator | ) | [inline] |
This will set the newline separator (lineSeparator
). The default is
. 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. |
void org::jdom::output::XMLOutputter::setNewlines | ( | boolean | newlines | ) | [inline] |
Sets whether newlines (lineSeparator
) should be added during output as an attempt to beautify code without pre-existing whitespace. Usually called in conjunction with setIndent.
newlines | true indicates new lines should be added for beautification. |
void org::jdom::output::XMLOutputter::setEncoding | ( | String | encoding | ) | [inline] |
Sets the output encoding. The name should be an accepted XML encoding.
encoding | the encoding format. Use XML-style names like "UTF-8" or "ISO-8859-1" or "US-ASCII" |
void org::jdom::output::XMLOutputter::setOmitEncoding | ( | boolean | omitEncoding | ) | [inline] |
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. |
void org::jdom::output::XMLOutputter::setOmitDeclaration | ( | boolean | omitDeclaration | ) | [inline] |
This will set whether the XML declaration (<?xml version="1.0"?gt;
) 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. |
void org::jdom::output::XMLOutputter::setExpandEmptyElements | ( | boolean | expandEmptyElements | ) | [inline] |
This will set whether empty elements are expanded from <tagName/>
to <tagName></tagName>
.
expandEmptyElements | boolean indicating whether or not empty elements should be expanded. |
void org::jdom::output::XMLOutputter::setTrimAllWhite | ( | boolean | trimAllWhite | ) | [inline] |
This will set whether content between tags consisting of all whitespace is printed or trimmed.
Default: false
trimAllWhite | boolean true=>content consisting of only whitespace is not print, false=>use text verbatim |
void org::jdom::output::XMLOutputter::setTextTrim | ( | boolean | textTrim | ) | [inline] |
This will set whether the text has leading/trailing whitespace trimmed.
Default: false
textTrim | boolean true=>trim the leading/trailing whitespace, false=>use text verbatim |
void org::jdom::output::XMLOutputter::setTextNormalize | ( | boolean | textNormalize | ) | [inline] |
This will set whether the text is output verbatim (false) or with whitespace normalized as per org.jdom.Element#getTextNormalize()
.
Default: false
textNormalize | boolean true=>normalize the whitespace, false=>use text verbatim |
void org::jdom::output::XMLOutputter::setIndent | ( | String | indent | ) | [inline] |
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)
indent | String to use for indentation. |
void org::jdom::output::XMLOutputter::output | ( | Document | doc, | |
OutputStream | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | DocType | doctype, | |
OutputStream | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | Element | element, | |
OutputStream | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::outputElementContent | ( | Element | element, | |
OutputStream | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | List | list, | |
OutputStream | out | |||
) | throws IOException [inline] |
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. |
void org::jdom::output::XMLOutputter::output | ( | CDATA | cdata, | |
OutputStream | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | Text | text, | |
OutputStream | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | Comment | comment, | |
OutputStream | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | ProcessingInstruction | pi, | |
OutputStream | out | |||
) | throws IOException [inline] |
Print out a ProcessingInstruction
.
pi | ProcessingInstruction to output. | |
out | OutputStream to use. |
void org::jdom::output::XMLOutputter::output | ( | EntityRef | entity, | |
OutputStream | out | |||
) | throws IOException [inline] |
Writer org::jdom::output::XMLOutputter::makeWriter | ( | OutputStream | out | ) | throws java.io.UnsupportedEncodingException [inline, protected] |
Get an OutputStreamWriter, using prefered encoding (see setEncoding).
Writer org::jdom::output::XMLOutputter::makeWriter | ( | OutputStream | out, | |
String | enc | |||
) | throws java.io.UnsupportedEncodingException [inline, protected] |
Get an OutputStreamWriter, use specified encoding.
void org::jdom::output::XMLOutputter::output | ( | Document | doc, | |
Writer | out | |||
) | throws IOException [inline] |
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. |
IOException | - if there's any problem writing. |
void org::jdom::output::XMLOutputter::output | ( | DocType | doctype, | |
Writer | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | Element | element, | |
Writer | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::outputElementContent | ( | Element | element, | |
Writer | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | List | list, | |
Writer | out | |||
) | throws IOException [inline] |
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. |
void org::jdom::output::XMLOutputter::output | ( | CDATA | cdata, | |
Writer | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | Text | text, | |
Writer | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | Comment | comment, | |
Writer | out | |||
) | throws IOException [inline] |
void org::jdom::output::XMLOutputter::output | ( | ProcessingInstruction | pi, | |
Writer | out | |||
) | throws IOException [inline] |
Print out a ProcessingInstruction
.
pi | ProcessingInstruction to output. | |
out | Writer to use. |
void org::jdom::output::XMLOutputter::output | ( | EntityRef | entity, | |
Writer | out | |||
) | throws IOException [inline] |
String org::jdom::output::XMLOutputter::outputString | ( | Document | doc | ) | [inline] |
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. |
String org::jdom::output::XMLOutputter::outputString | ( | DocType | doctype | ) | [inline] |
String org::jdom::output::XMLOutputter::outputString | ( | Element | element | ) | [inline] |
Return a string representing an element. Warning: a String is Unicode, which may not match the outputter's specified encoding.
element | Element to format. |
String org::jdom::output::XMLOutputter::outputString | ( | List | list | ) | [inline] |
Return a string representing a list of nodes. The list is assumed to contain legal JDOM nodes.
list | List to format. |
String org::jdom::output::XMLOutputter::outputString | ( | CDATA | cdata | ) | [inline] |
String org::jdom::output::XMLOutputter::outputString | ( | Text | text | ) | [inline] |
String org::jdom::output::XMLOutputter::outputString | ( | Comment | comment | ) | [inline] |
Return a string representing a comment. Warning: a String is Unicode, which may not match the outputter's specified encoding.
comment | Comment to format. |
String org::jdom::output::XMLOutputter::outputString | ( | ProcessingInstruction | pi | ) | [inline] |
Return a string representing a PI. Warning: a String is Unicode, which may not match the outputter's specified encoding.
pi | ProcessingInstruction to format. |
String org::jdom::output::XMLOutputter::outputString | ( | EntityRef | entity | ) | [inline] |
Return a string representing an entity. Warning: a String is Unicode, which may not match the outputter's specified encoding.
entity | EntityRef to format. |
void org::jdom::output::XMLOutputter::printDeclaration | ( | Document | doc, | |
Writer | out, | |||
String | encoding | |||
) | throws IOException [inline, protected] |
This will handle printing of the declaration. Assumes XML version 1.0 since we don't directly know.
doc | Document whose declaration to write. | |
out | Writer to use. | |
encoding | The encoding to add to the declaration |
void org::jdom::output::XMLOutputter::printDocType | ( | DocType | docType, | |
Writer | out | |||
) | throws IOException [inline, protected] |
This handle printing the DOCTYPE declaration if one exists.
docType | Document whose declaration to write. | |
out | Writer to use. |
void org::jdom::output::XMLOutputter::printComment | ( | Comment | comment, | |
Writer | out | |||
) | throws IOException [inline, protected] |
void org::jdom::output::XMLOutputter::printProcessingInstruction | ( | ProcessingInstruction | pi, | |
Writer | out | |||
) | throws IOException [inline, protected] |
This will handle printing of processing instructions.
pi | ProcessingInstruction to write. | |
out | Writer to use. |
void org::jdom::output::XMLOutputter::printEntityRef | ( | EntityRef | entity, | |
Writer | out | |||
) | throws IOException [inline, protected] |
void org::jdom::output::XMLOutputter::printCDATA | ( | CDATA | cdata, | |
Writer | out | |||
) | throws IOException [inline, protected] |
void org::jdom::output::XMLOutputter::printText | ( | Text | text, | |
Writer | out | |||
) | throws IOException [inline, protected] |
void org::jdom::output::XMLOutputter::printString | ( | String | str, | |
Writer | out | |||
) | throws IOException [inline, protected] |
This will handle printing a string. Escapes the element entities, trims interior whitespace, etc. if necessary.
void org::jdom::output::XMLOutputter::printElement | ( | Element | element, | |
Writer | out, | |||
int | level, | |||
NamespaceStack | namespaces | |||
) | throws IOException [inline, protected] |
void org::jdom::output::XMLOutputter::printContentRange | ( | List | content, | |
int | start, | |||
int | end, | |||
Writer | out, | |||
int | level, | |||
NamespaceStack | namespaces | |||
) | throws IOException [inline, protected] |
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.
content | List of content to output | |
start | index of first content node (inclusive. | |
end | index of last content node (exclusive). | |
out | Writer to use. | |
level | int level of indentation. | |
namespaces | List stack of Namespaces in scope. |
void org::jdom::output::XMLOutputter::printTextRange | ( | List | content, | |
int | start, | |||
int | end, | |||
Writer | out | |||
) | throws IOException [inline, protected] |
void org::jdom::output::XMLOutputter::printAttributes | ( | List | attributes, | |
Element | parent, | |||
Writer | out, | |||
NamespaceStack | namespaces | |||
) | throws IOException [inline, protected] |
void org::jdom::output::XMLOutputter::newline | ( | Writer | out | ) | throws IOException [inline, protected] |
This will print a new line only if the newlines flag was set to true.
out | Writer to use |
void org::jdom::output::XMLOutputter::indent | ( | Writer | out, | |
int | level | |||
) | throws IOException [inline, protected] |
This will print indents (only if the newlines flag was set to true
, and indent is non-null).
out | Writer to use | |
level | current indent level (number of tabs) |
String org::jdom::output::XMLOutputter::escapeAttributeEntities | ( | String | str | ) | [inline] |
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.
str | String input to escape. |
String
with escaped content. String org::jdom::output::XMLOutputter::escapeElementEntities | ( | String | str | ) | [inline] |
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. int org::jdom::output::XMLOutputter::parseArgs | ( | String[] | args, | |
int | i | |||
) | [inline] |
Parse command-line arguments of the form -omitEncoding -indentSize 3 …
.
Object org::jdom::output::XMLOutputter::clone | ( | ) | [inline] |
Returns a copy of this XMLOutputter.
String org::jdom::output::XMLOutputter::toString | ( | ) | [inline] |
Return a string listing of the settings for this XMLOutputter instance.
NamespaceStack org::jdom::output::XMLOutputter::createNamespaceStack | ( | ) | [inline, protected] |
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.
void org::jdom::output::XMLOutputter::output | ( | String | string, | |
OutputStream | out | |||
) | throws IOException [inline] |
Print out a java.lang.String
. Perfoms the necessary entity escaping and whitespace stripping.
string | String to output. | |
out | OutputStream to use. |
void org::jdom::output::XMLOutputter::output | ( | String | string, | |
Writer | out | |||
) | throws IOException [inline] |
Print out a java.lang.String
. Perfoms the necessary entity escaping and whitespace stripping.
string | String to output. | |
out | Writer to use. |
void org::jdom::output::XMLOutputter::setIndent | ( | boolean | doIndent | ) | [inline] |
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.
doIndent | if true, set indenting on; if false, set indenting off |
void org::jdom::output::XMLOutputter::setIndent | ( | int | size | ) | [inline] |
This will set the indent String
's size; a size of 4 would result in the indentation being equivalent to the String
" " (four spaces).
size | int number of spaces in indentation. |
void org::jdom::output::XMLOutputter::setIndentSize | ( | int | indentSize | ) | [inline] |
This will set the indent String
's size; an indentSize of 4 would result in the indentation being equivalent to the String
" " (four spaces).
indentSize | int number of spaces in indentation. |
String org::jdom::output::XMLOutputter::outputString | ( | String | str | ) | [inline] |
Return a string representing (with trimming, normalization, and escaping possibly applied) a String
. Warning: a String is Unicode, which may not match the outputter's specified encoding.
str | String to format. |