public class

XmlWriter

extends Object
java.lang.Object
   ↳ com.google.gdata.util.common.xml.XmlWriter

Class Overview

Implements a simple XML writer on top of java.io.PrintWriter. This implementation can be conveniently used to generate XML responses in servlets.

The XmlWriter class exposes a number of protected methods that enable it to be subclassed for the purposes of customizing its output. See com.google.javascript.util.JsonWriter for an example.

Optional Behaviors

There are several behaviors of this class that are optionally available. These features are enabled by passing a Set<XmlWriter.WriterFlags> to the constructor: 
new XmlWriter(sw, EnumSet.of(WriterFlags.WRITE_HEADER,
     WriterFlags.EXPAND_EMPTY, WriterFlags.PRETTY_PRINT), null)
The caller can supply any of the values enumerated in XmlWriter.WriterFlags, or none. Once a feature has been enabled in the constructor, it cannot be turned off.

Including XML Header

The WRITE_HEADER flags causes XmlWriter to emit an XML header at the beginning of the XML document: 
<?xml version='1.0'?>

Expanding Empty Elements

The EXPAND_EMPTY flags causes XmlWriter to emit "expanded" empty elements (elements consisting of distinct begin and end tags): 
 <foo>
    <wee really="yeah"></wee>
 </foo>

Pretty Printing

The PRETTY_PRINT flag enables pretty printing. This feature formats the XML output with using new lines and tab characters: 

 <foo>
    <bar>
        <wee really="yeah"/>
    </bar>
 </foo>

Caveats

Elements containing mixed content (i.e. both text children and full-fledged elements) will not generally be formatted correctly. If your XML document contains mixed content, you may not want to use pretty printing:

Will produce wonky formatting: 

  w.startElement(null, "txt", null, null);
  w.simpleElement(null, "fooey", null, null);
  w.characters("Kleenex");
  w.endElement(null, "txt");
 <txt>
    <fooey/>Kleenex
 </txt>

You can ensure correct formatting of mixed content in your document by using the innerXml(String) method to write raw XML.

Correctly formatted: 

  w.startElement(null, "txt", null, null);
  w.innerXml("<fooey/>");
  w.characters("Kleenex");
  w.endElement(null, "txt");
 <txt><fooey/>Kleenex</txt>

Summary

Nested Classes
class XmlWriter.Attribute The Attribute class represents an XML attribute. 
class XmlWriter.Element The Element class contains information about an XML element. 
class XmlWriter.Namespace This class is deprecated. Use the XmlNamespace class instead.  
enum XmlWriter.WriterFlags Enumeration type that can be used to configure the XmlWriter behavior. 
Constants
String INDENTATION_UNIT
Fields
private String defaultNamespace Current default namespace.
private final Stack<XmlWriter.Element> elementStack Stack of currently opened elements.
protected String encoding Encoding of output
protected final Set<XmlWriter.WriterFlags> flags
private String nextDefaultNamespace
private Boolean standalone
protected final Writer writer The underlying output Writer associated with this XmlWriter.
Public Constructors
XmlWriter(Writer w, Set<XmlWriter.WriterFlags> f, String encoding, boolean standalone)
Constructor that allows standalone directive to be provided.
XmlWriter(Writer w, Set<XmlWriter.WriterFlags> f, String encoding)
The default namespace that will take effect on the next element transition.
XmlWriter(Writer w)
Constructs an XmlWriter instance associated that will generate XML content to an underlying Writer.
XmlWriter(Writer w, String encoding)
Constructor that writers header including encoding information.
XmlWriter(Writer w, boolean includeHeader)
This constructor is deprecated. see XmlWriter(Writer, Set, String)
Public Methods
void characters(String s)
Emits character data subject to XML escaping.
void characters(String s, boolean useCData)
Emits character data subject to either XML escaping or CDATA escaping.
void close()
Closes the XmlWriter and the underlying output writer.
void endElement(XmlNamespace namespace, String name)
Ends the current element.
void endElement()
Ends the current element.
void endRepeatingElement()
Indicates that the series of repeating elements have been completely written.
void flush()
Flushes the XmlWriter and the underlying output writer.
void innerXml(String xml)
Writes inner XML provided as a string.
void setDefaultNamespace(XmlNamespace namespace)
Sets the default namespace.
void simpleElement(String name, String value)
Emits a simple element (without child elements).
void simpleElement(XmlNamespace namespace, String name, List<XmlWriter.Attribute> attrs, String value)
Emits a simple element (without child elements).
void startElement(XmlNamespace namespace, String name, Collection<XmlWriter.Attribute> attrs, Collection<? extends XmlNamespace> namespaceDecls)
Starts an element.
void startElement(String name)
Starts an element.
void startRepeatingElement()
Indicates that a series of repeating elements are about to be written.
void writeUnescaped(String s)
Writes a string without XML entity escaping.
Protected Methods
XmlWriter.Element createElement(String nsAlias, String nsUri, String name)
Constructs an Element instance that describes an XML element that is about to be written.
XmlWriter.Element currentElement()
Returns the current element, or null if no element is being written.
void endOpenTag()
Ends the start tag for an element.
String ensureNamespace(XmlNamespace namespace)
Ensures the namespace is in scope and returns its alias.
String getNamespaceUri(String nsAlias)
Returns the namespace URI associated with a given namespace alias.
XmlWriter.Element parentElement()
Return parent of current element.
boolean shouldWriteHeaderAndFooter()
Tests whether header and footer should be included in output
void writeAttribute(String name, String value)
Writes an unqualfied XML attribute.
void writeAttribute(String nsAlias, String name, String value)
Writes a namespace-qualified XML attribute.
void writeBeginOutput()
writes beginning of output if any.
void writeCloseTag(String nsAlias, String name)
Writes the closing tag of an element, after all nested elements and value text have been written.
void writeEndOutput()
Writes any closing information to the output writer.
void writeFooter()
Writes footer, if any, that corresponds to the header.
void writeHeader(String enc)
Writes basic XML headers including XML version, standalone, and encoding.
void writeOpenTagEnd()
Writes the end of the opening tag of an element after all attributes have been written.
void writeOpenTagStart(String nsAlias, String name)
Writes the start of the opening tag of an element.
void writeQualifiedName(String nsAlias, String name)
Writes a namespace qualified element or attribute name.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

private static final String INDENTATION_UNIT

Constant Value: " "

Fields

private String defaultNamespace

Current default namespace.

private final Stack<XmlWriter.Element> elementStack

Stack of currently opened elements.

protected String encoding

Encoding of output

protected final Set<XmlWriter.WriterFlags> flags

private String nextDefaultNamespace

private Boolean standalone

protected final Writer writer

The underlying output Writer associated with this XmlWriter.

Public Constructors

public XmlWriter (Writer w, Set<XmlWriter.WriterFlags> f, String encoding, boolean standalone)

Constructor that allows standalone directive to be provided. Please note that using this constructor explicity causes the standalone header value to be written and WRITE_HEADER flag to be set.

Parameters
w Output writer object.
f Writer configuration flags or null for no flags
encoding Charset encoding.
standalone Boolean where true=yes and false=no.
Throws
IOException thrown by the underlying writer
See Also

public XmlWriter (Writer w, Set<XmlWriter.WriterFlags> f, String encoding)

The default namespace that will take effect on the next element transition.

Parameters
w Output writer object.
f Writer configuration flags or null for no flags
encoding Charset encoding. When non-null, implicitly causes the WRITE_HEADER flag to be set.
Throws
IOException thrown by the underlying writer.
See Also

public XmlWriter (Writer w)

Constructs an XmlWriter instance associated that will generate XML content to an underlying Writer.

Parameters
w Output writer object.
Throws
IOException thrown by the underlying writer.

public XmlWriter (Writer w, String encoding)

Constructor that writers header including encoding information.

Parameters
w Output writer object.
encoding Output encoding to use in declaration.
Throws
IOException thrown by the underlying writer.

public XmlWriter (Writer w, boolean includeHeader)

This constructor is deprecated.
see XmlWriter(Writer, Set, String)

Parameters
w
includeHeader
Throws
IOException

Public Methods

public void characters (String s)

Emits character data subject to XML escaping.

Parameters
s String to emit. Can be null.
Throws
IOException thrown by the underlying writer.

public void characters (String s, boolean useCData)

Emits character data subject to either XML escaping or CDATA escaping.

Parameters
s String to emit. Can be null.
useCData CDATA used if true, XML escaping if false
Throws
IOException thrown by the underlying writer.

public void close ()

Closes the XmlWriter and the underlying output writer.

Throws
IOException thrown by the underlying writer.

public void endElement (XmlNamespace namespace, String name)

Ends the current element. It is expected to be on top of the stack.

Parameters
namespace Element namespace.
name Element name.
Throws
IOException

public void endElement ()

Ends the current element. No integrity checking is performed.

Throws
IOException

public void endRepeatingElement ()

Indicates that the series of repeating elements have been completely written.

Throws
IOException

public void flush ()

Flushes the XmlWriter and the underlying output writer.

Throws
IOException thrown by the underlying writer.

public void innerXml (String xml)

Writes inner XML provided as a string. Used to write out XML blobs.

Parameters
xml XML blob string.
Throws
IOException thrown by the underlying writer.

public void setDefaultNamespace (XmlNamespace namespace)

Sets the default namespace. It takes effect on the next element.

Parameters
namespace The new namespace to set as the default at the start of the next element.

public void simpleElement (String name, String value)

Emits a simple element (without child elements).

Parameters
name Element name.
value Element value. Can be null.
Throws
IOException thrown by the underlying writer.

public void simpleElement (XmlNamespace namespace, String name, List<XmlWriter.Attribute> attrs, String value)

Emits a simple element (without child elements).

Parameters
namespace Element namespace.
name Element name.
attrs Attributes. Can be null.
value Element value. Can be null.
Throws
IOException thrown by the underlying writer.

public void startElement (XmlNamespace namespace, String name, Collection<XmlWriter.Attribute> attrs, Collection<? extends XmlNamespace> namespaceDecls)

Starts an element. This element can be a parent to other elements.

Parameters
namespace Element namespace.
name Element name.
attrs Attributes. Can be null.
namespaceDecls Extra namespace declarations. Can be null.
Throws
IOException thrown by the underlying writer.

public void startElement (String name)

Starts an element. This element can be a parent to other elements.

Parameters
name Element name.
Throws
IOException

public void startRepeatingElement ()

Indicates that a series of repeating elements are about to be written.

Throws
IOException

public void writeUnescaped (String s)

Writes a string without XML entity escaping.

Parameters
s The raw content to write without escaping.
Throws
IOException thrown by the underlying writer.

Protected Methods

protected XmlWriter.Element createElement (String nsAlias, String nsUri, String name)

Constructs an Element instance that describes an XML element that is about to be written.

Parameters
nsAlias
nsUri
name

protected XmlWriter.Element currentElement ()

Returns the current element, or null if no element is being written.

protected void endOpenTag ()

Ends the start tag for an element.

Throws
IOException

protected String ensureNamespace (XmlNamespace namespace)

Ensures the namespace is in scope and returns its alias. The top of the stack is assumed to be the current element. If the namespace is not found, it is appended to the current element.

Parameters
namespace
Returns
  • namespace alias or null for the default namespace.

protected String getNamespaceUri (String nsAlias)

Returns the namespace URI associated with a given namespace alias.

Parameters
nsAlias Namespace alias, or null for default namespace.
Returns
  • namespace URI, or null if not found.

protected XmlWriter.Element parentElement ()

Return parent of current element. Stack has a dummy root element so every real element has non-null a parent.

Returns
  • Parent element.

protected boolean shouldWriteHeaderAndFooter ()

Tests whether header and footer should be included in output

Returns
  • true if header and footer should be included in output; false otherwise

protected void writeAttribute (String name, String value)

Writes an unqualfied XML attribute.

Parameters
name The name of the attribute.
value The value of the attribute.
Throws
IOException thrown by the underlying writer.

protected void writeAttribute (String nsAlias, String name, String value)

Writes a namespace-qualified XML attribute.

Parameters
nsAlias Namespace alias prefix for the attribute.
name The name of the attribute.
value The value of the attribute.
Throws
IOException thrown by the underlying writer.

protected void writeBeginOutput ()

writes beginning of output if any.

Throws
IOException

protected void writeCloseTag (String nsAlias, String name)

Writes the closing tag of an element, after all nested elements and value text have been written.

Parameters
nsAlias Namespace alias prefix for the element.
name Tag name for the element.
Throws
IOException thrown by the underlying writer.

protected void writeEndOutput ()

Writes any closing information to the output writer. This is used by subclasses to write anything they need to close out the object. close() should not be used because it closes the underlying stream, which we don't always want to do.

Throws
IOException

protected void writeFooter ()

Writes footer, if any, that corresponds to the header.

Throws
IOException

protected void writeHeader (String enc)

Writes basic XML headers including XML version, standalone, and encoding.

Parameters
enc The XML encoding for the output. Can be null.
Throws
IOException thrown by the underlying writer.

protected void writeOpenTagEnd ()

Writes the end of the opening tag of an element after all attributes have been written.

Throws
IOException thrown by the underlying writer.

protected void writeOpenTagStart (String nsAlias, String name)

Writes the start of the opening tag of an element.

Parameters
nsAlias Namespace alias prefix for the element.
name Tag name for the element.
Throws
IOException thrown by the underlying writer.

protected void writeQualifiedName (String nsAlias, String name)

Writes a namespace qualified element or attribute name.

Parameters
nsAlias Namespace alias prefix.
name Namespace-relative local name.
Throws
IOException thrown by the underlying writer.