Class XMLOutputter

java.lang.Object

org.apache.maven.archetype.common.util.XMLOutputter

All Implemented Interfaces:

Cloneable

public class XMLOutputter
extends Object
implements Cloneable

This class is a fork from JDOM 1.0 modified to preserve CData sections and comments.

Outputs a JDOM document as a stream of bytes. 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 by setting a new Format object. For pretty-print output, use Format.getPrettyFormat(). For whitespace-normalized output, use Format.getCompactFormat().

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 Format object. 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 Format manually in its constructor or via the Format.setEncoding(String) method. The default encoding is UTF-8.

The methods outputString(...) are for convenience only; for top performance you should call one of the output(...) methods and pass in your own Writer or OutputStream if possible.

XML declarations are always printed on their own line followed by a line separator (this doesn't change the semantics of the document). To omit printing of the declaration use Format.setOmitDeclaration(boolean). To omit printing of the encoding in the declaration use Format.setOmitEncoding(boolean). Unfortunately 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 Format.setExpandEmptyElements(boolean) to cause them to be expanded to <empty></empty>.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	XMLOutputter.NamespaceStack	Our own null subclass of NamespaceStack.

Field Summary

Fields

Modifier and Type	Field	Description
protected Format	currentFormat
private boolean	escapeOutput	Whether output escaping is enabled for the being processed Element - default is true
protected static final Format	PRESERVE_FORMAT
private Format	userFormat

Constructor Summary

Constructors

Constructor	Description
XMLOutputter()	This will create an XMLOutputter with the default Format matching Format.getRawFormat().
XMLOutputter(Format format)	This will create an XMLOutputter with the specified format characteristics.
XMLOutputter(XMLOutputter that)	This will create an XMLOutputter with all the options as set in the given XMLOutputter.

Method Summary

Modifier and Type	Method	Description
Object	clone()	Returns a copy of this XMLOutputter.
private XMLOutputter.NamespaceStack	createNamespaceStack()	Factory for making new NamespaceStack objects.
private boolean	endsWithWhite(String str)
String	escapeAttributeEntities(String str)	This will take the pre-defined entities in XML 1.0 and convert their character representation to the appropriate entity reference, suitable for XML attributes.
String	escapeElementEntities(String str)	This will take the three pre-defined entities in XML 1.0 (used specifically in XML elements) and convert their character representation to the appropriate entity reference, suitable for XML element content.
Format	getFormat()	Returns the current format in use by the outputter.
private void	indent(Writer out, int level)	This will print indents (only if the newlines flag was set to true, and indent is non-null).
private boolean	isAllWhitespace(Object obj)
private static boolean	isWhitespace(char c)
private Writer	makeWriter(OutputStream out)	Get an OutputStreamWriter, using prefered encoding (see Format.setEncoding(String)).
private static Writer	makeWriter(OutputStream out, String enc)	Get an OutputStreamWriter, use specified encoding.
private void	newline(Writer out)	This will print a new line only if the newlines flag was set to true.
private static int	nextNonText(List<?> content, int start)
void	output(List<?> list, OutputStream out)	This will handle printing out a list of nodes.
void	output(List<?> list, Writer out)	This will handle printing out a list of nodes.
void	output(org.jdom2.CDATA cdata, OutputStream out)	Print out a CDATA node.
void	output(org.jdom2.CDATA cdata, Writer out)	Print out a CDATA node.
void	output(org.jdom2.Comment comment, OutputStream out)	Print out a Comment.
void	output(org.jdom2.Comment comment, Writer out)	Print out a Comment.
void	output(org.jdom2.DocType doctype, OutputStream out)	Print out the DocType.
void	output(org.jdom2.DocType doctype, Writer out)	Print out the DocType.
void	output(org.jdom2.Document doc, OutputStream out)	This will print the Document to the given output stream.
void	output(org.jdom2.Document doc, Writer out)	This will print the Document to the given Writer.
void	output(org.jdom2.Element element, OutputStream out)	Print out an Element, including its Attributes, and all contained (child) elements, etc.
void	output(org.jdom2.Element element, Writer out)	Print out an Element, including its Attributes, and all contained (child) elements, etc.
void	output(org.jdom2.EntityRef entity, OutputStream out)	Print out a EntityRef.
void	output(org.jdom2.EntityRef entity, Writer out)	Print out a EntityRef.
void	output(org.jdom2.ProcessingInstruction pi, OutputStream out)	Print out a ProcessingInstruction.
void	output(org.jdom2.ProcessingInstruction pi, Writer out)	Print out a ProcessingInstruction.
void	output(org.jdom2.Text text, OutputStream out)	Print out a Text node.
void	output(org.jdom2.Text text, Writer out)	Print out a Text node.
void	outputElementContent(org.jdom2.Element element, OutputStream out)	This will handle printing out an Element's content only, not including its tag, and attributes.
void	outputElementContent(org.jdom2.Element element, Writer out)	This will handle printing out an Element's content only, not including its tag, and attributes.
String	outputString(List<?> list)	Return a string representing a list of nodes.
String	outputString(org.jdom2.CDATA cdata)	Return a string representing a CDATA node.
String	outputString(org.jdom2.Comment comment)	Return a string representing a comment.
String	outputString(org.jdom2.DocType doctype)	Return a string representing a DocType.
String	outputString(org.jdom2.Document doc)	Return a string representing a document.
String	outputString(org.jdom2.Element element)	Return a string representing an element.
String	outputString(org.jdom2.EntityRef entity)	Return a string representing an entity.
String	outputString(org.jdom2.ProcessingInstruction pi)	Return a string representing a PI.
String	outputString(org.jdom2.Text text)	Return a string representing a Text node.
private void	printAdditionalNamespaces(Writer out, org.jdom2.Element element, XMLOutputter.NamespaceStack namespaces)
protected void	printAttributes(Writer out, List<?> attributes, org.jdom2.Element parent, XMLOutputter.NamespaceStack namespaces)	This will handle printing of a Attribute list.
protected void	printCDATA(Writer out, org.jdom2.CDATA cdata)	This will handle printing of CDATA text.
protected void	printComment(Writer out, org.jdom2.Comment comment)	This will handle printing of comments.
private void	printContentRange(Writer out, List<?> content, int start, int end, int level, XMLOutputter.NamespaceStack namespaces)	This will handle printing of content within a given range.
protected void	printDeclaration(Writer out, org.jdom2.Document doc, String encoding)	This will handle printing of the declaration.
protected void	printDocType(Writer out, org.jdom2.DocType docType)	This handle printing the DOCTYPE declaration if one exists.
protected void	printElement(Writer out, org.jdom2.Element element, int level, XMLOutputter.NamespaceStack namespaces)	This will handle printing of a Element, its Attributes, and all contained (child) elements, etc.
private void	printElementNamespace(Writer out, org.jdom2.Element element, XMLOutputter.NamespaceStack namespaces)
protected void	printEntityRef(Writer out, org.jdom2.EntityRef entity)	This will handle printing a EntityRef.
private void	printNamespace(Writer out, org.jdom2.Namespace ns, XMLOutputter.NamespaceStack namespaces)	This will handle printing of any needed Namespace declarations.
protected void	printProcessingInstruction(Writer out, org.jdom2.ProcessingInstruction pi)	This will handle printing of processing instructions.
private void	printQualifiedName(Writer out, org.jdom2.Attribute a)
private void	printQualifiedName(Writer out, org.jdom2.Element e)
private void	printString(Writer out, String str)	This will handle printing a string.
protected void	printText(Writer out, org.jdom2.Text text)	This will handle printing of Text strings.
private void	printTextRange(Writer out, List<?> content, int start, int end)	This will handle printing of a sequence of CDATA or Text nodes.
void	setFormat(Format newFormat)	Sets the new format logic for the outputter.
private int	skipLeadingWhite(List<?> content, int start)
private int	skipTrailingWhite(List<?> content, int start)
private boolean	startsWithWhite(String str)
String	toString()	Return a string listing of the settings for this XMLOutputter instance.

Methods inherited from class Object

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

Field Details

userFormat

private Format userFormat

PRESERVE_FORMAT

protected static final Format PRESERVE_FORMAT

currentFormat

protected Format currentFormat

escapeOutput

private boolean escapeOutput

Whether output escaping is enabled for the being processed Element - default is true

Constructor Details

XMLOutputter

public XMLOutputter()

This will create an XMLOutputter with the default Format matching Format.getRawFormat().

XMLOutputter

public XMLOutputter(Format format)

This will create an XMLOutputter with the specified format characteristics. Note the format object is cloned internally before use.

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 Details

setFormat

public void setFormat(Format newFormat)

Sets the new format logic for the outputter. Note the Format object is cloned internally before use.

Parameters:

newFormat - the format to use for output

getFormat

public Format getFormat()

Returns the current format in use by the outputter. Note the Format object returned is a clone of the one used internally.

output

public void output(org.jdom2.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 use.

Throws:

IOException - - if there's any problem writing.

output

public void output(org.jdom2.DocType doctype,
 OutputStream out)
            throws IOException

Print out the DocType.

Parameters:

doctype - DocType to output.

out - OutputStream to use.

Throws:

IOException

output

public void output(org.jdom2.Element element,
 OutputStream out)
            throws IOException

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

Parameters:

element - Element to output.

out - Writer to use.

Throws:

IOException

outputElementContent

public void outputElementContent(org.jdom2.Element element,
 OutputStream out)
                          throws IOException

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

Throws:

IOException

output

public void output(List<?> list,
 OutputStream out)
            throws IOException

This will handle printing out a list of nodes. This can be useful for printing the content of an element that contains HTML, like "<description>JDOM is <b>fun>!</description>".

Parameters:

list - List of nodes.

out - OutputStream to use.

Throws:

IOException

output

public void output(org.jdom2.CDATA cdata,
 OutputStream out)
            throws IOException

Print out a CDATA node.

Parameters:

cdata - CDATA to output.

out - OutputStream to use.

Throws:

IOException

output

public void output(org.jdom2.Text text,
 OutputStream out)
            throws IOException

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

Parameters:

text - Text to output.

out - OutputStream to use.

Throws:

IOException

output

public void output(org.jdom2.Comment comment,
 OutputStream out)
            throws IOException

Print out a Comment.

Parameters:

comment - Comment to output.

out - OutputStream to use.

Throws:

IOException

output

public void output(org.jdom2.ProcessingInstruction pi,
 OutputStream out)
            throws IOException

Print out a ProcessingInstruction.

Parameters:

pi - ProcessingInstruction to output.

out - OutputStream to use.

Throws:

IOException

output

public void output(org.jdom2.EntityRef entity,
 OutputStream out)
            throws IOException

Print out a EntityRef.

Parameters:

entity - EntityRef to output.

out - OutputStream to use.

Throws:

IOException

makeWriter

private Writer makeWriter(OutputStream out)
                   throws UnsupportedEncodingException

Get an OutputStreamWriter, using prefered encoding (see Format.setEncoding(String)).

Throws:

UnsupportedEncodingException

makeWriter

private static Writer makeWriter(OutputStream out,
 String enc)
                          throws UnsupportedEncodingException

Get an OutputStreamWriter, use specified encoding.

Throws:

UnsupportedEncodingException

output

public void output(org.jdom2.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 use.

Throws:

IOException - - if there's any problem writing.

output

public void output(org.jdom2.DocType doctype,
 Writer out)
            throws IOException

Print out the DocType.

Parameters:

doctype - DocType to output.

out - Writer to use.

Throws:

IOException

output

public void output(org.jdom2.Element element,
 Writer out)
            throws IOException

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

Parameters:

element - Element to output.

out - Writer to use.

Throws:

IOException

outputElementContent

public void outputElementContent(org.jdom2.Element element,
 Writer out)
                          throws IOException

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

Throws:

IOException

output

public void output(List<?> list,
 Writer out)
            throws IOException

This will handle printing out a list of nodes. This can be useful for printing the content of an element that contains HTML, like "<description>JDOM is <b>fun>!</description>".

Parameters:

list - List of nodes.

out - Writer to use.

Throws:

IOException

output

public void output(org.jdom2.CDATA cdata,
 Writer out)
            throws IOException

Print out a CDATA node.

Parameters:

cdata - CDATA to output.

out - Writer to use.

Throws:

IOException

output

public void output(org.jdom2.Text text,
 Writer out)
            throws IOException

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

Parameters:

text - Text to output.

out - Writer to use.

Throws:

IOException

output

public void output(org.jdom2.Comment comment,
 Writer out)
            throws IOException

Print out a Comment.

Parameters:

comment - Comment to output.

out - Writer to use.

Throws:

IOException

output

public void output(org.jdom2.ProcessingInstruction pi,
 Writer out)
            throws IOException

Print out a ProcessingInstruction.

Parameters:

pi - ProcessingInstruction to output.

out - Writer to use.

Throws:

IOException

output

public void output(org.jdom2.EntityRef entity,
 Writer out)
            throws IOException

Print out a EntityRef.

Parameters:

entity - EntityRef to output.

out - Writer to use.

Throws:

IOException

outputString

public String outputString(org.jdom2.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.

outputString

public String outputString(org.jdom2.DocType doctype)

Return a string representing a DocType. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

doctype - DocType to format.

outputString

public String outputString(org.jdom2.Element element)

Return a string representing an element. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

element - Element to format.

outputString

public String outputString(List<?> list)

Return a string representing a list of nodes. The list is assumed to contain legal JDOM nodes.

Parameters:

list - List to format.

outputString

public String outputString(org.jdom2.CDATA cdata)

Return a string representing a CDATA node. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

cdata - CDATA to format.

outputString

public String outputString(org.jdom2.Text text)

Return a string representing a Text node. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

text - Text to format.

outputString

public String outputString(org.jdom2.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.

outputString

public String outputString(org.jdom2.ProcessingInstruction pi)

Return a string representing a PI. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

pi - ProcessingInstruction to format.

outputString

public String outputString(org.jdom2.EntityRef entity)

Return a string representing an entity. Warning: a String is Unicode, which may not match the outputter's specified encoding.

Parameters:

entity - EntityRef to format.

printDeclaration

protected void printDeclaration(Writer out,
 org.jdom2.Document doc,
 String encoding)
                         throws IOException

This will handle printing of the declaration. Assumes XML version 1.0 since we don't directly know.

Parameters:

out - Writer to use.

doc - Document whose declaration to write.

encoding - The encoding to add to the declaration

Throws:

IOException

printDocType

protected void printDocType(Writer out,
 org.jdom2.DocType docType)
                     throws IOException

This handle printing the DOCTYPE declaration if one exists.

Parameters:

out - Writer to use.

docType - Document whose declaration to write.

Throws:

IOException

printComment

protected void printComment(Writer out,
 org.jdom2.Comment comment)
                     throws IOException

This will handle printing of comments.

Parameters:

out - Writer to use.

comment - Comment to write.

Throws:

IOException

printProcessingInstruction

protected void printProcessingInstruction(Writer out,
 org.jdom2.ProcessingInstruction pi)
                                   throws IOException

This will handle printing of processing instructions.

Parameters:

out - Writer to use.

pi - ProcessingInstruction to write.

Throws:

IOException

printEntityRef

protected void printEntityRef(Writer out,
 org.jdom2.EntityRef entity)
                       throws IOException

This will handle printing a 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:

out - Writer to use.

entity - EntityRef to output.

Throws:

IOException

printCDATA

protected void printCDATA(Writer out,
 org.jdom2.CDATA cdata)
                   throws IOException

This will handle printing of CDATA text.

Parameters:

out - Writer to use.

cdata - CDATA to output.

Throws:

IOException

printText

protected void printText(Writer out,
 org.jdom2.Text text)
                  throws IOException

This will handle printing of Text strings.

Parameters:

out - Writer to use.

text - Text to write.

Throws:

IOException

printString

private void printString(Writer out,
 String str)
                  throws IOException

This will handle printing a string. Escapes the element entities, trims interior whitespace, etc. if necessary.

Throws:

IOException

printElement

protected void printElement(Writer out,
 org.jdom2.Element element,
 int level,
 XMLOutputter.NamespaceStack namespaces)
                     throws IOException

This will handle printing of a Element, its Attributes, and all contained (child) elements, etc.

Parameters:

out - Writer to use.

element - Element to output.

level - int level of indention.

namespaces - List stack of Namespaces in scope.

Throws:

IOException

printContentRange

private void printContentRange(Writer out,
 List<?> content,
 int start,
 int end,
 int level,
 XMLOutputter.NamespaceStack namespaces)
                        throws IOException

This will handle printing of content within a given range. The range to print is specified in typical Java fashion; the starting index is inclusive, while the ending index is exclusive.

Parameters:

out - Writer to use.

content - List of content to output

start - index of first content node (inclusive.

end - index of last content node (exclusive).

level - int level of indentation.

namespaces - List stack of Namespaces in scope.

Throws:

IOException

printTextRange

private void printTextRange(Writer out,
 List<?> content,
 int start,
 int end)
                     throws IOException

This will handle printing of a sequence of CDATA or Text nodes. It is an error to have any other pass this method any other type of node.

Parameters:

out - Writer to use.

content - List of content to output

start - index of first content node (inclusive).

end - index of last content node (exclusive).

Throws:

IOException

printNamespace

private void printNamespace(Writer out,
 org.jdom2.Namespace ns,
 XMLOutputter.NamespaceStack namespaces)
                     throws IOException

This will handle printing of any needed Namespace declarations.

Parameters:

out - Writer to use.

ns - Namespace to print definition of

Throws:

IOException

printAttributes

protected void printAttributes(Writer out,
 List<?> attributes,
 org.jdom2.Element parent,
 XMLOutputter.NamespaceStack namespaces)
                        throws IOException

This will handle printing of a Attribute list.

Parameters:

out - Writer to use

attributes - List of Attribute objcts

Throws:

IOException

printElementNamespace

private void printElementNamespace(Writer out,
 org.jdom2.Element element,
 XMLOutputter.NamespaceStack namespaces)
                            throws IOException

Throws:

IOException

printAdditionalNamespaces

private void printAdditionalNamespaces(Writer out,
 org.jdom2.Element element,
 XMLOutputter.NamespaceStack namespaces)
                                throws IOException

Throws:

IOException

newline

private void newline(Writer out)
              throws IOException

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

Parameters:

out - Writer to use

Throws:

IOException

indent

private void indent(Writer out,
 int level)
             throws IOException

This will print indents (only if the newlines flag was set to true, and indent is non-null).

Parameters:

out - Writer to use

level - current indent level (number of tabs)

Throws:

IOException

skipLeadingWhite

private int skipLeadingWhite(List<?> content,
 int start)

skipTrailingWhite

private int skipTrailingWhite(List<?> content,
 int start)

nextNonText

private static int nextNonText(List<?> content,
 int start)

isAllWhitespace

private boolean isAllWhitespace(Object obj)

startsWithWhite

private boolean startsWithWhite(String str)

endsWithWhite

private boolean endsWithWhite(String str)

isWhitespace

private static boolean isWhitespace(char c)

escapeAttributeEntities

public String escapeAttributeEntities(String str)

This will take the pre-defined entities in XML 1.0 and convert their character representation to the appropriate entity reference, suitable for XML attributes. It does not convert the single quote (') because it's not necessary as the outputter writes attributes surrounded by double-quotes.

Parameters:

str - String input to escape.

Returns:

String with escaped content.

escapeElementEntities

public String escapeElementEntities(String str)

This will take the three pre-defined entities in XML 1.0 (used specifically in XML elements) and convert their character representation to the appropriate entity reference, suitable for XML element content.

Parameters:

str - String input to escape.

Returns:

String with escaped content.

clone

public Object clone()

Returns a copy of this XMLOutputter.

Overrides:

clone in class Object

toString

public String toString()

Return a string listing of the settings for this XMLOutputter instance.

Overrides:

toString in class Object

Returns:

a string listing the settings for this XMLOutputter instance

createNamespaceStack

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

printQualifiedName

private void printQualifiedName(Writer out,
 org.jdom2.Element e)
                         throws IOException

Throws:

IOException

printQualifiedName

private void printQualifiedName(Writer out,
 org.jdom2.Attribute a)
                         throws IOException

Throws:

IOException