JDOM API: Class XMLOutputter

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.jdom.output
Class XMLOutputter

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

public class XMLOutputter
extends java.lang.Object
implements java.lang.Cloneable

XMLOutputter takes a JDOM tree and formats it to a stream as XML. This formatter performs typical document formatting. The XML declaration and processing instructions are always on their own lines. Empty elements are printed as <empty/> and text-only contents are printed as <tag>content</tag> on a single line. Constructor parameters control the indent amount and whether new lines are printed between elements. The other parameters are configurable through the set* methods.

For compact machine-readable output create a default XMLOutputter and call setTrimText(true) to strip any whitespace that was preserved from the source.

There are output(...) methods to print any of the standard JDOM classes, including Document and Element, to either a Writer or an OutputStream. Warning: using your own Writer may cause the outputter's preferred character encoding to be ignored. If you use encodings other than UTF8, we recommend using the method that takes an OutputStream instead.

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)

Field Summary
`protected static java.lang.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(java.lang.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(java.lang.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(java.lang.String indent, boolean newlines, java.lang.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 void`	`indent(java.io.Writer out, int level)` This will print the proper indent characters for the given indent level.
`protected java.io.Writer`	`makeWriter(java.io.OutputStream out)` Get an OutputStreamWriter, use preferred encoding.
`protected java.io.Writer`	`makeWriter(java.io.OutputStream out, java.lang.String encoding)` Get an OutputStreamWriter, use specified encoding.
`protected void`	`maybePrintln(java.io.Writer out)` This will print a new line only if the newlines flag was set to true
`void`	`output(CDATA cdata, java.io.OutputStream out)` Print out a `CDATA`
`void`	`output(CDATA cdata, java.io.Writer out)` Print out a `CDATA`
`void`	`output(Comment comment, java.io.OutputStream out)` Print out a `Comment`
`void`	`output(Comment comment, java.io.Writer out)` Print out a `Comment`
`void`	`output(Document doc, java.io.OutputStream out)` This will print the `Document` to the given output stream.
`void`	`output(Document doc, java.io.Writer writer)` This will print the `Document` to the given Writer.
`void`	`output(Element element, java.io.OutputStream out)` Print out an `Element`, including its `Attribute`s, and its value, and all contained (child) elements etc.
`void`	`output(Element element, java.io.Writer out)` Print out an `Element`, including its `Attribute`s, and its value, and all contained (child) elements etc.
`void`	`output(Entity entity, java.io.OutputStream out)` Print out an `Entity`.
`void`	`output(Entity entity, java.io.Writer out)` Print out an `Entity`.
`void`	`output(ProcessingInstruction processingInstruction, java.io.OutputStream out)` Print out a `ProcessingInstruction`
`void`	`output(ProcessingInstruction processingInstruction, java.io.Writer out)` Print out a `ProcessingInstruction`
`void`	`output(java.lang.String string, java.io.OutputStream out)` Print out a `String`.
`void`	`output(java.lang.String string, java.io.Writer out)` Print out a `String`.
`java.lang.String`	`outputString(Document doc)` Return a string representing a document.
`java.lang.String`	`outputString(Element element)` Return a string representing an element.
`int`	`parseArgs(java.lang.String[] args, int i)` parse command-line arguments of the form `-omitEncoding -indentSize 3 ...`
`protected void`	`printAttributes(java.util.List attributes, Element parent, java.io.Writer out, org.jdom.output.NamespaceStack namespaces)` This will handle printing out an `Attribute` list.
`protected void`	`printCDATASection(CDATA cdata, java.io.Writer out, int indentLevel)` This will handle printing out an `CDATA`, and its value.
`protected void`	`printComment(Comment comment, java.io.Writer out, int indentLevel)` This will write the comment to the specified writer.
`void`	`printDeclaration(Document doc, java.io.Writer out, java.lang.String encoding)` This will write the declaration to the given Writer.
`void`	`printDocType(DocType docType, java.io.Writer out)` This will write the DOCTYPE declaration if one exists.
`protected void`	`printElement(Element element, java.io.Writer out, int indentLevel, org.jdom.output.NamespaceStack namespaces)` This will handle printing out an `Element`, its `Attribute`s, and its value.
`void`	`printElementContent(Element element, java.io.Writer out)` This will handle printing out an `Element`'s content only, not including its tag, attributes, and namespace info.
`protected void`	`printElementContent(Element element, java.io.Writer out, int indentLevel, org.jdom.output.NamespaceStack namespaces, java.util.List mixedContent)` This will handle printing out an `Element`'s content only, not including its tag, attributes, and namespace info.
`protected void`	`printEntity(Entity entity, java.io.Writer out)` This will handle printing out an `Entity`.
`protected void`	`printNamespace(Namespace ns, java.io.Writer out)` This will handle printing out any needed `Namespace` declarations.
`protected void`	`printProcessingInstruction(ProcessingInstruction pi, java.io.Writer out, int indentLevel)` This will write the processing instruction to the specified writer.
`protected void`	`printString(java.lang.String s, java.io.Writer out)` Print a string.
`void`	`setEncoding(java.lang.String 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(java.lang.String indent)` This will set the indent `String` to use; this is usually a `String` of empty spaces.
`void`	`setIndentLevel(int indentLevel)` Set the initial indentation level.
`void`	`setIndentSize(int indentSize)` This will set the indent `String`'s size; an indentSize of 4 would result in the indention being equivalent to the `String` " " (four space characters).
`void`	`setLineSeparator(java.lang.String separator)` This will set the new-line separator.
`void`	`setNewlines(boolean newlines)`
`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`	`setSuppressDeclaration(boolean suppressDeclaration)` This will set whether the XML declaration (`<?xml version="1.0"?>`) will be suppressed or not.
`void`	`setTrimText(boolean trimText)` This will set whether the text is output verbatim (false) or with whitespace stripped as per `Element.getTextTrim()`. Default: false

Methods inherited from class java.lang.Object

clone, 
equals, 
finalize, 
getClass, 
hashCode, 
notify, 
notifyAll, 
toString, 
wait, 
wait, 
wait

Field Detail

STANDARD_INDENT

protected static final java.lang.String STANDARD_INDENT

standard value to indent by, if we are indenting

Constructor Detail

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.

XMLOutputter

public XMLOutputter(java.lang.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

XMLOutputter

public XMLOutputter(java.lang.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).

XMLOutputter

public XMLOutputter(java.lang.String indent,
                    boolean newlines,
                    java.lang.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.

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

Method Detail

setLineSeparator

public void setLineSeparator(java.lang.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.

We could change this to the System default, but I prefer not to make output platform dependent. A carriage return, linefeed pair is the most generally acceptable linebreak. Another possibility is to use only a line feed, which is XML's preferred (but not required) solution. However, both carriage return and linefeed are required for many network protocols, and the parser on the other end should normalize this. --Rusty

Parameters:: separator - String line separator to use.
See Also:: setNewlines(boolean)

setNewlines

public void setNewlines(boolean newlines)

Parameters:: newlines - true indicates new lines should be printed, else new lines are ignored (compacted).
See Also:: setLineSeparator(String)

setEncoding

public void setEncoding(java.lang.String encoding)

Parameters:: encoding - encoding format

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

setSuppressDeclaration

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.

Parameters:: suppressDeclaration - boolean indicating whether or not the XML declaration should be suppressed.

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.

setTrimText

public void setTrimText(boolean trimText)

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

Default: false

Parameters:: trimText - boolean true=>trim the whitespace, false=>use text verbatim

setIndent

public void setIndent(java.lang.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.

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

setIndentLevel

public void setIndentLevel(int indentLevel)

Set the initial indentation level. This can be used to output a document (or, more likely, an element) starting at a given indent level, so it's not always flush against the left margin. Default: 0

Parameters:: indentLevel - the number of indents to start with

setIndentSize

public void setIndentSize(int indentSize)

This will set the indent String's size; an indentSize of 4 would result in the indention being equivalent to the String " " (four space characters).

Parameters:: indentSize - int number of spaces in indentation.

indent

protected void indent(java.io.Writer out,
                      int level)
               throws java.io.IOException

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

Parameters:: out - Writer to write to; level - int indentation level

maybePrintln

protected void maybePrintln(java.io.Writer out)
                     throws java.io.IOException

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

Parameters:: out - Writer to write to

makeWriter

protected java.io.Writer makeWriter(java.io.OutputStream out)
                             throws java.io.UnsupportedEncodingException

Get an OutputStreamWriter, use preferred encoding.

makeWriter

protected java.io.Writer makeWriter(java.io.OutputStream out,
                                    java.lang.String encoding)
                             throws java.io.UnsupportedEncodingException

Get an OutputStreamWriter, use specified encoding.

output

public void output(Document doc,
                   java.io.OutputStream out)
            throws java.io.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.

output

public void output(Document doc,
                   java.io.Writer writer)
            throws java.io.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 UTF8, we recommend using the method that takes an OutputStream instead.

Note: as with all Writers, you may need to flush() yours after this method returns.

Parameters:: doc - Document to format.; out - Writer to write to.
Throws:: IOException - - if there's any problem writing.

output

public void output(Element element,
                   java.io.Writer out)
            throws java.io.IOException

Print out an Element, including its Attributes, and its value, and all contained (child) elements etc.

Parameters:: element - Element to output.; out - Writer to write to.

output

public void output(Element element,
                   java.io.OutputStream out)
            throws java.io.IOException

Print out an Element, including its Attributes, and its value, and all contained (child) elements etc.

Parameters:: element - Element to output.; out - Writer to write to.

output

public void output(CDATA cdata,
                   java.io.Writer out)
            throws java.io.IOException

Print out a CDATA

Parameters:: cdata - CDATA to output.; out - Writer to write to.

output

public void output(CDATA cdata,
                   java.io.OutputStream out)
            throws java.io.IOException

Print out a CDATA

Parameters:: cdata - CDATA to output.; out - OutputStream to write to.

output

public void output(Comment comment,
                   java.io.Writer out)
            throws java.io.IOException

Print out a Comment

Parameters:: comment - Comment to output.; out - Writer to write to.

output

public void output(Comment comment,
                   java.io.OutputStream out)
            throws java.io.IOException

Print out a Comment

Parameters:: comment - Comment to output.; out - OutputStream to write to.

output

public void output(java.lang.String string,
                   java.io.Writer out)
            throws java.io.IOException

Print out a String. Perfoms the necessary entity escaping and whitespace stripping.

Parameters:: string - String to output.; out - Writer to write to.

output

public void output(java.lang.String string,
                   java.io.OutputStream out)
            throws java.io.IOException

Print out a String. Perfoms the necessary entity escaping and whitespace stripping.

Parameters:: cdata - CDATA to output.; out - OutputStream to write to.

output

public void output(Entity entity,
                   java.io.Writer out)
            throws java.io.IOException

Print out an Entity.

Parameters:: entity - Entity to output.; out - Writer to write to.

output

public void output(Entity entity,
                   java.io.OutputStream out)
            throws java.io.IOException

Print out an Entity.

Parameters:: cdata - CDATA to output.; out - OutputStream to write to.

output

public void output(ProcessingInstruction processingInstruction,
                   java.io.Writer out)
            throws java.io.IOException

Print out a ProcessingInstruction

Parameters:: element - ProcessingInstruction to output.; out - Writer to write to.

output

public void output(ProcessingInstruction processingInstruction,
                   java.io.OutputStream out)
            throws java.io.IOException

Print out a ProcessingInstruction

Parameters:: processingInstruction - ProcessingInstruction to output.; out - OutputStream to write to.

outputString

public java.lang.String outputString(Document doc)
                              throws java.io.IOException

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.

outputString

public java.lang.String outputString(Element element)
                              throws java.io.IOException

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.

printDeclaration

public void printDeclaration(Document doc,
                             java.io.Writer out,
                             java.lang.String encoding)
                      throws java.io.IOException

This will write the declaration to the given Writer. Assumes XML version 1.0 since we don't directly know.

Parameters:: docType - DocType whose declaration to write.; out - Writer to write to.

printDocType

public void printDocType(DocType docType,
                         java.io.Writer out)
                  throws java.io.IOException

This will write the DOCTYPE declaration if one exists.

Parameters:: doc - Document whose declaration to write.; out - Writer to write to.

printComment

protected void printComment(Comment comment,
                            java.io.Writer out,
                            int indentLevel)
                     throws java.io.IOException

This will write the comment to the specified writer.

Parameters:: comment - Comment to write.; out - Writer to write to.; indentLevel - Current depth in hierarchy.

printProcessingInstruction

protected void printProcessingInstruction(ProcessingInstruction pi,
                                          java.io.Writer out,
                                          int indentLevel)
                                   throws java.io.IOException

This will write the processing instruction to the specified writer.

Parameters:: comment - ProcessingInstruction to write.; out - Writer to write to.; indentLevel - Current depth in hierarchy.

printCDATASection

protected void printCDATASection(CDATA cdata,
                                 java.io.Writer out,
                                 int indentLevel)
                          throws java.io.IOException

This will handle printing out an CDATA, and its value.

Parameters:: cdata - CDATA to output.; out - Writer to write to.; indent - int level of indention.

printElement

protected void printElement(Element element,
                            java.io.Writer out,
                            int indentLevel,
                            org.jdom.output.NamespaceStack namespaces)
                     throws java.io.IOException

This will handle printing out an Element, its Attributes, 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.

printElementContent

public void printElementContent(Element element,
                                java.io.Writer out)
                         throws java.io.IOException

This will handle printing out an 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.

printElementContent

protected void printElementContent(Element element,
                                   java.io.Writer out,
                                   int indentLevel,
                                   org.jdom.output.NamespaceStack namespaces,
                                   java.util.List mixedContent)
                            throws java.io.IOException

This will handle printing out an 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.

printString

protected void printString(java.lang.String s,
                           java.io.Writer out)
                    throws java.io.IOException

Print a string. Escapes the element entities, trims interior whitespace if necessary.

printEntity

protected void printEntity(Entity entity,
                           java.io.Writer out)
                    throws java.io.IOException

This will handle printing out an Entity. 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 - Entity to output.; out - Writer to write to.

printNamespace

protected void printNamespace(Namespace ns,
                              java.io.Writer out)
                       throws java.io.IOException

This will handle printing out any needed Namespace declarations.

Parameters:: ns - Namespace to print definition of; out - Writer to write to.

printAttributes

protected void printAttributes(java.util.List attributes,
                               Element parent,
                               java.io.Writer out,
                               org.jdom.output.NamespaceStack namespaces)
                        throws java.io.IOException

This will handle printing out an Attribute list.

Parameters:: attributes - List of Attribute objcts; out - Writer to write to

parseArgs

public int parseArgs(java.lang.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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.jdom.output Class XMLOutputter

STANDARD_INDENT

XMLOutputter

XMLOutputter

XMLOutputter

XMLOutputter

XMLOutputter

setLineSeparator

setNewlines

setEncoding

setOmitEncoding

setSuppressDeclaration

setExpandEmptyElements

setTrimText

setIndent

setIndent

setIndentLevel

setIndentSize

indent

maybePrintln

makeWriter

makeWriter

output

output

output

output

output

output

output

output

output

output

output

output

output

output

outputString

outputString

printDeclaration

printDocType

printComment

printProcessingInstruction

printCDATASection

printElement

printElementContent

printElementContent

printString

printEntity

printNamespace

printAttributes

parseArgs

org.jdom.output
Class XMLOutputter