All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.jdom.output.XMLOutputter

java.lang.Object
   |
   +----org.jdom.output.XMLOutputter

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 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.

Version:
1.0
Author:
Brett McLaughlin, Jason Hunter, Jason Reid, Wolfgang Werner, Elliotte Rusty Harold, David & Will (from Post Tool Design), Dan Schaffer, Alex Chaffee (alex@jguru.com)

Variable Index

 o STANDARD_INDENT
standard value to indent by, if we are indenting

Constructor Index

 o 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.

 o XMLOutputter(String)

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.

 o XMLOutputter(String, boolean)

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.

 o XMLOutputter(String, boolean, String)

This will create an XMLOutputter with the given indent and new lines printing only if newlines is true, and encoding format encoding.

 o XMLOutputter(XMLOutputter)

This will create an XMLOutputter with all the options as set in the given XMLOutputter.

Method Index

 o createNamespaceStack()
Factory for making new NamespaceStack objects.
 o escapeAttributeEntities(String)

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.

 o escapeElementEntities(String)

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.

 o indent(Writer, int)

This will print the proper indent characters for the given indent level.

 o makeWriter(OutputStream)
Get an OutputStreamWriter, use preferred encoding.
 o makeWriter(OutputStream, String)
Get an OutputStreamWriter, use specified encoding.
 o maybePrintln(Writer)

This will print a new line only if the newlines flag was set to true

 o output(CDATA, OutputStream)

Print out a {

 o output(CDATA, Writer)

Print out a {

 o output(Comment, OutputStream)

Print out a {

 o output(Comment, Writer)

Print out a {

 o output(DocType, OutputStream)

Print out a {

 o output(DocType, Writer)

Print out a {

 o output(Document, OutputStream)

This will print the Document to the given output stream.

 o output(Document, Writer)

This will print the Document to the given Writer.

 o output(Element, OutputStream)

Print out an {

 o output(Element, Writer)

Print out an {

 o output(EntityRef, OutputStream)

Print out an {

 o output(EntityRef, Writer)

Print out an {

 o output(ProcessingInstruction, OutputStream)

Print out a {

 o output(ProcessingInstruction, Writer)

Print out a {

 o output(String, OutputStream)

Print out a {

 o output(String, Writer)

Print out a {

 o output(Text, OutputStream)

Print out a {

 o output(Text, Writer)

Print out a {

 o outputElementContent(Element, OutputStream)

This will handle printing out an {

 o outputElementContent(Element, Writer)

This will handle printing out an {

 o outputString(CDATA)
Return a string representing a CDATA section.
 o outputString(Comment)
Return a string representing a comment.
 o outputString(DocType)
Return a string representing a DocType.
 o outputString(Document)
Return a string representing a document.
 o outputString(Element)
Return a string representing an element.
 o outputString(EntityRef)
Return a string representing an entity.
 o outputString(ProcessingInstruction)
Return a string representing a PI.
 o parseArgs(String[], int)
parse command-line arguments of the form -omitEncoding -indentSize 3 ...
 o printAttributes(List, Element, Writer, XMLOutputter. NamespaceStack)

This will handle printing out an {

 o printCDATA(CDATA, Writer)

This will handle printing out an {

 o printComment(Comment, Writer)

This will write the comment to the specified writer.

 o printDeclaration(Document, Writer, String)

This will write the declaration to the given Writer.

 o printDocType(DocType, Writer)

This will write the DOCTYPE declaration if one exists.

 o printElement(Element, Writer, int, XMLOutputter. NamespaceStack)

This will handle printing out an {

 o printElementContent(Element, Writer, int, XMLOutputter. NamespaceStack, List)

This will handle printing out an {

 o printEntityRef(EntityRef, Writer)

This will handle printing out an {

 o printProcessingInstruction(ProcessingInstruction, Writer)

This will write the processing instruction to the specified writer.

 o printString(String, Writer)
Print a string.
 o setEncoding(String)
Sets the output encoding.
 o setExpandEmptyElements(boolean)

This will set whether empty elements are expanded from <tagName> to <tagName></tagName>.

 o setIndent(boolean)
Set the indent on or off.
 o setIndent(String)

This will set the indent String to use; this is usually a String of empty spaces.

 o setIndentLevel(int)
Set the initial indentation level. Deprecated.
 o setIndentSize(int)

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).

 o setLineSeparator(String)

This will set the new-line separator.

 o setNewlines(boolean)
 o setOmitDeclaration(boolean)

This will set whether the XML declaration (<?xml version="1.0"?>) will be omitted or not.

 o setOmitEncoding(boolean)

This will set whether the XML declaration (<?xml version="1.0" encoding="UTF-8"?>) includes the encoding of the document.

 o setPadText(boolean)

Ensure that text immediately preceded by or followed by an element will be "padded" with a single space. Deprecated.

 o setSuppressDeclaration(boolean)

This will set whether the XML declaration (<?xml version="1.0"?>) will be suppressed or not. Deprecated.

 o setTextNormalize(boolean)

This will set whether the text is output verbatim (false) or with whitespace normalized as per {

 o setTrimText(boolean)

This will set whether the text is output verbatim (false) or with whitespace stripped.

Default: false

Deprecated.

Variables

 o STANDARD_INDENT
 protected static final String STANDARD_INDENT
standard value to indent by, if we are indenting

Constructors

 o XMLOutputter
 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.

 o XMLOutputter
 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.

Parameters:
indent - the indent string, usually some number of spaces
 o XMLOutputter
 public 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.

Parameters:
indent - the indent String, usually some number of spaces
newlines - true indicates new lines should be printed, else new lines are ignored (compacted).
 o XMLOutputter
 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.

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"
 o XMLOutputter
 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.

Parameters:
that - the XMLOutputter to clone

Methods

 o setLineSeparator
 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.

Parameters:
separator - String line separator to use.
See Also:
setNewlines, setTextNormalize
 o setNewlines
 public void setNewlines(boolean newlines)
Parameters:
newlines - true indicates new lines should be printed, else new lines are ignored (compacted).
See Also:
setLineSeparator
 o setEncoding
 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"
 o setOmitEncoding
 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.
 o setOmitDeclaration
 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.
 o setExpandEmptyElements
 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.
 o setTextNormalize
 public void setTextNormalize(boolean textNormalize)

This will set whether the text is output verbatim (false) or with whitespace normalized as per {@link org.jdom.Element#getTextNormalize()}.

Default: false

Parameters:
textNormalize - boolean true=>normalize the whitespace, false=>use text verbatim
 o setTrimText
 public void setTrimText(boolean textTrim)
Note: setTrimText() is deprecated. Deprecated in beta7, use setTextNormalize() instead

This will set whether the text is output verbatim (false) or with whitespace stripped.

Default: false

Parameters:
trimText - boolean true=>trim the whitespace, false=>use text verbatim
 o setIndent
 public 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.

Default: none (null)

Parameters:
indent - String to use for indentation.
 o setIndent
 public void setIndent(boolean doIndent)
Set the indent on or off. 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
 o setIndentSize
 public 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).

Parameters:
indentSize - int number of spaces in indentation.
 o indent
 protected void indent(Writer out,
                       int level) throws IOException

This will print the proper indent characters for the given indent level.

Parameters:
out - Writer to write to
level - int indentation level
 o maybePrintln
 protected void maybePrintln(Writer out) throws IOException

This will print a new line only if the newlines flag was set to true

Parameters:
out - Writer to write to
 o makeWriter
 protected Writer makeWriter(OutputStream out) throws UnsupportedEncodingException
Get an OutputStreamWriter, use preferred encoding.

 o makeWriter
 protected Writer makeWriter(OutputStream out,
                             String enc) throws UnsupportedEncodingException
Get an OutputStreamWriter, use specified encoding.

 o output
 public void output(Document doc,
                    OutputStream out) throws IOException

This will print the Document to the given output stream. The characters are printed using the encoding specified in the constructor, or a default of UTF-8.

Parameters:
doc - Document to format.
out - OutputStream to write to.
Throws: IOException
- if there's any problem writing.
 o output
 public void output(Document doc,
                    Writer out) throws IOException

This will print the Document to the given Writer.

Warning: using your own Writer may cause the outputter's preferred character encoding to be ignored. If you use encodings other than UTF-8, we recommend using the method that takes an OutputStream instead.

Parameters:
doc - Document to format.
out - Writer to write to.
Throws: IOException
- if there's any problem writing.
 o output
 public void output(Element element,
                    Writer out) throws IOException

Print out an {@link Element}, including its {@link Attribute}s, and its value, and all contained (child) elements etc.

Parameters:
element - Element to output.
out - Writer to write to.
 o output
 public void output(Element element,
                    OutputStream out) throws IOException

Print out an {@link Element}, including its {@link Attribute}s, and its value, and all contained (child) elements etc.

Parameters:
element - Element to output.
out - Writer to write to.
 o outputElementContent
 public void outputElementContent(Element element,
                                  Writer out) throws IOException

This will handle printing out an {@link 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 write to.
 o outputElementContent
 public void outputElementContent(Element element,
                                  OutputStream out) throws IOException

This will handle printing out an {@link 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 write to.
 o output
 public void output(CDATA cdata,
                    Writer out) throws IOException

Print out a {@link CDATA}

Parameters:
cdata - CDATA to output.
out - Writer to write to.
 o output
 public void output(CDATA cdata,
                    OutputStream out) throws IOException

Print out a {@link CDATA}

Parameters:
cdata - CDATA to output.
out - OutputStream to write to.
 o output
 public void output(Comment comment,
                    Writer out) throws IOException

Print out a {@link Comment}

Parameters:
comment - Comment to output.
out - Writer to write to.
 o output
 public void output(Comment comment,
                    OutputStream out) throws IOException

Print out a {@link Comment}

Parameters:
comment - Comment to output.
out - OutputStream to write to.
 o output
 public void output(String string,
                    Writer out) throws IOException

Print out a {@link java.lang.String}. Perfoms the necessary entity escaping and whitespace stripping.

Parameters:
string - String to output.
out - Writer to write to.
 o output
 public void output(String string,
                    OutputStream out) throws IOException

Print out a {@link java.lang.String}. Perfoms the necessary entity escaping and whitespace stripping.

Parameters:
string - String to output.
out - OutputStream to write to.
 o output
 public void output(Text text,
                    Writer out) throws IOException

Print out a {@link Text}. Perfoms the necessary entity escaping and whitespace stripping.

Parameters:
text - Text to output.
out - Writer to write to.
 o output
 public void output(Text text,
                    OutputStream out) throws IOException

Print out a {@link Text}. Perfoms the necessary entity escaping and whitespace stripping.

Parameters:
text - Text to output.
out - OutputStream to write to.
 o output
 public void output(EntityRef entity,
                    Writer out) throws IOException

Print out an {@link EntityRef}.

Parameters:
entity - EntityRef to output.
out - Writer to write to.
 o output
 public void output(EntityRef entity,
                    OutputStream out) throws IOException

Print out an {@link EntityRef}.

Parameters:
entity - EntityRef to output.
out - OutputStream to write to.
 o output
 public void output(ProcessingInstruction pi,
                    Writer out) throws IOException

Print out a {@link ProcessingInstruction}

Parameters:
element - ProcessingInstruction to output.
out - Writer to write to.
 o output
 public void output(ProcessingInstruction pi,
                    OutputStream out) throws IOException

Print out a {@link ProcessingInstruction}

Parameters:
processingInstruction - ProcessingInstruction to output.
out - OutputStream to write to.
 o output
 public void output(DocType doctype,
                    Writer out) throws IOException

Print out a {@link DocType}

Parameters:
doctype - DocType to output.
out - Writer to write to.
 o output
 public void output(DocType doctype,
                    OutputStream out) throws IOException

Print out a {@link DocType}

Parameters:
doctype - DocType to output.
out - OutputStream to write to.
 o outputString
 public String outputString(Document doc)
Return a string representing a document. Uses an internal StringWriter. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:
doc - Document to format.
 o outputString
 public String outputString(Element element)
Return a string representing an element. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:
doc - Element to format.
 o outputString
 public String outputString(Comment comment)
Return a string representing a comment. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:
comment - Comment to format.
 o outputString
 public String outputString(CDATA cdata)
Return a string representing a CDATA section. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:
cdata - CDATA to format.
 o outputString
 public String outputString(ProcessingInstruction pi)
Return a string representing a PI. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:
doc - ProcessingInstruction to format.
 o outputString
 public String outputString(DocType doctype)
Return a string representing a DocType. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:
doc - DocType to format.
 o outputString
 public String outputString(EntityRef entity)
Return a string representing an entity. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:
doc - EntityRef to format.
 o printDeclaration
 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.

Parameters:
doc - Document whose declaration to write.
out - Writer to write to.
encoding - The encoding to add to the declaration
 o printDocType
 protected void printDocType(DocType docType,
                             Writer out) throws IOException

This will write the DOCTYPE declaration if one exists.

Parameters:
doc - Document whose declaration to write.
out - Writer to write to.
 o printComment
 protected void printComment(Comment comment,
                             Writer out) throws IOException

This will write the comment to the specified writer.

Parameters:
comment - Comment to write.
out - Writer to write to.
 o printProcessingInstruction
 protected void printProcessingInstruction(ProcessingInstruction pi,
                                           Writer out) throws IOException

This will write the processing instruction to the specified writer.

Parameters:
comment - ProcessingInstruction to write.
out - Writer to write to.
 o printCDATA
 protected void printCDATA(CDATA cdata,
                           Writer out) throws IOException

This will handle printing out an {@link CDATA}, and its value.

Parameters:
cdata - CDATA to output.
out - Writer to write to.
 o printElement
 protected void printElement(Element element,
                             Writer out,
                             int indentLevel,
                             XMLOutputter. NamespaceStack namespaces) throws IOException

This will handle printing out an {@link Element}, its {@link Attribute}s, and its value.

Parameters:
element - Element to output.
out - Writer to write to.
indent - int level of indention.
namespaces - List stack of Namespaces in scope.
 o printElementContent
 protected void printElementContent(Element element,
                                    Writer out,
                                    int indentLevel,
                                    XMLOutputter. NamespaceStack namespaces,
                                    List eltContent) throws IOException

This will handle printing out an {@link Element}'s content only, not including its tag, attributes, and namespace info.

Parameters:
element - Element to output.
out - Writer to write to.
indent - int level of indention.
 o printString
 protected void printString(String s,
                            Writer out) throws IOException
Print a string. Escapes the element entities, trims interior whitespace if necessary.

 o printEntityRef
 protected void printEntityRef(EntityRef entity,
                               Writer out) throws IOException

This will handle printing out an {@link 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 write to.
 o printAttributes
 protected void printAttributes(List attributes,
                                Element parent,
                                Writer out,
                                XMLOutputter. NamespaceStack namespaces) throws IOException

This will handle printing out an {@link Attribute} list.

Parameters:
attributes - List of Attribute objcts
out - Writer to write to
 o escapeAttributeEntities
 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. It does no converstion for ' because it's not necessary as the outputter writes attributes surrounded by double-quotes.

Parameters:
st - String input to escape.
Returns:
String with escaped content.
 o escapeElementEntities
 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.

Parameters:
st - String input to escape.
Returns:
String with escaped content.
 o parseArgs
 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
 o createNamespaceStack
 protected XMLOutputter. 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.

 o setPadText
 public void setPadText(boolean padText)
Note: setPadText() is 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.

 o setIndentLevel
 public void setIndentLevel(int indentLevel)
Note: setIndentLevel() is deprecated. Deprecated in beta7, because this is better done with a stacked FilterOutputStream

Set the initial indentation level.

 o setSuppressDeclaration
 public void setSuppressDeclaration(boolean suppressDeclaration)
Note: setSuppressDeclaration() is 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.

All Packages  Class Hierarchy  This Package  Previous  Next  Index