com.google.gdata.util.common.xml

Class XmlWriter

java.lang.Object

com.google.gdata.util.common.xml.XmlWriter

public class XmlWriter
extends Object

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>

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	XmlWriter.Attribute The Attribute class represents an XML attribute.
protected static class	XmlWriter.Element The Element class contains information about an XML element.
static class	XmlWriter.Namespace Deprecated. Use the XmlNamespace class instead.
static class	XmlWriter.WriterFlags Enumeration type that can be used to configure the XmlWriter behavior.

Field Summary

Fields

Modifier and Type	Field and Description
protected String	encoding Encoding of output
protected Set<XmlWriter.WriterFlags>	flags
protected Writer	writer The underlying output Writer associated with this XmlWriter.

Constructor Summary

Constructors

Constructor and Description
XmlWriter(Writer w) Constructs an XmlWriter instance associated that will generate XML content to an underlying Writer.
XmlWriter(Writer w, boolean includeHeader) Deprecated. see XmlWriter(Writer, Set, String)
XmlWriter(Writer w, Set<XmlWriter.WriterFlags> f, String encoding) The default namespace that will take effect on the next element transition.
XmlWriter(Writer w, Set<XmlWriter.WriterFlags> f, String encoding, boolean standalone) Constructor that allows standalone directive to be provided.
XmlWriter(Writer w, String encoding) Constructor that writers header including encoding information.

Method Summary

Methods

Modifier and Type	Method and Description
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.
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.
protected XmlWriter.Element	currentElement() Returns the current element, or null if no element is being written.
void	endElement() Ends the current element.
void	endElement(XmlNamespace namespace, String name) Ends the current element.
protected void	endOpenTag() Ends the start tag for an element.
void	endRepeatingElement() Indicates that the series of repeating elements have been completely written.
protected String	ensureNamespace(XmlNamespace namespace) Ensures the namespace is in scope and returns its alias.
void	flush() Flushes the XmlWriter and the underlying output writer.
protected String	getNamespaceUri(String nsAlias) Returns the namespace URI associated with a given namespace alias.
void	innerXml(String xml) Writes inner XML provided as a string.
protected XmlWriter.Element	parentElement() Return parent of current element.
void	setDefaultNamespace(XmlNamespace namespace) Sets the default namespace.
protected boolean	shouldWriteHeaderAndFooter() Tests whether header and footer should be included in output
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(String name) Starts an element.
void	startElement(XmlNamespace namespace, String name, Collection<XmlWriter.Attribute> attrs, Collection<? extends XmlNamespace> namespaceDecls) Starts an element.
void	startRepeatingElement() Indicates that a series of repeating elements are about to be written.
protected void	writeAttribute(String name, String value) Writes an unqualfied XML attribute.
protected void	writeAttribute(String nsAlias, String name, String value) Writes a namespace-qualified XML attribute.
protected void	writeBeginOutput() writes beginning of output if any.
protected void	writeCloseTag(String nsAlias, String name) Writes the closing tag of an element, after all nested elements and value text have been written.
protected void	writeEndOutput() Writes any closing information to the output writer.
protected void	writeFooter() Writes footer, if any, that corresponds to the header.
protected void	writeHeader(String enc) Writes basic XML headers including XML version, standalone, and encoding.
protected void	writeOpenTagEnd() Writes the end of the opening tag of an element after all attributes have been written.
protected void	writeOpenTagStart(String nsAlias, String name) Writes the start of the opening tag of an element.
protected void	writeQualifiedName(String nsAlias, String name) Writes a namespace qualified element or attribute name.
void	writeUnescaped(String s) Writes a string without XML entity escaping.

Methods inherited from class java.lang.Object

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

Field Detail

flags

protected final Set<XmlWriter.WriterFlags> flags

writer

protected final Writer writer

The underlying output Writer associated with this XmlWriter.

encoding

protected String encoding

Encoding of output

Constructor Detail

XmlWriter

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

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:

XmlWriter.WriterFlags

XmlWriter

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

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:

XmlWriter.WriterFlags

XmlWriter

public XmlWriter(Writer w)
          throws IOException

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.

XmlWriter

public XmlWriter(Writer w,
         String encoding)
          throws IOException

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.

XmlWriter

@Deprecated
public XmlWriter(Writer w,
                    boolean includeHeader)
          throws IOException

Deprecated. see XmlWriter(Writer, Set, String)

Throws:

IOException

Method Detail

close

public void close()
           throws IOException

Closes the XmlWriter and the underlying output writer.

Throws:

IOException - thrown by the underlying writer.

flush

public void flush()
           throws IOException

Flushes the XmlWriter and the underlying output writer.

Throws:

IOException - thrown by the underlying writer.

setDefaultNamespace

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.

createElement

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.

currentElement

protected XmlWriter.Element currentElement()

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

parentElement

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.

startElement

public void startElement(String name)
                  throws IOException

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

Parameters:

name - element name.

Throws:

IOException

startElement

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

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.

shouldWriteHeaderAndFooter

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

endOpenTag

protected void endOpenTag()
                   throws IOException

Ends the start tag for an element.

Throws:

IOException

endElement

public void endElement(XmlNamespace namespace,
              String name)
                throws IOException

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

Parameters:

namespace - element namespace.

name - element name.

Throws:

IOException

endElement

public void endElement()
                throws IOException

Ends the current element. No integrity checking is performed.

Throws:

IOException

simpleElement

public void simpleElement(String name,
                 String value)
                   throws IOException

Emits a simple element (without child elements).

Parameters:

name - element name.

value - element value. Can be null.

Throws:

IOException - thrown by the underlying writer.

startRepeatingElement

public void startRepeatingElement()
                           throws IOException

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

Throws:

IOException

endRepeatingElement

public void endRepeatingElement()
                         throws IOException

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

Throws:

IOException

simpleElement

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

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.

ensureNamespace

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.

Returns:

namespace alias or null for the default namespace.

getNamespaceUri

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.

writeBeginOutput

protected void writeBeginOutput()
                         throws IOException

writes beginning of output if any.

Throws:

IOException

writeEndOutput

protected void writeEndOutput()
                       throws IOException

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

writeHeader

protected void writeHeader(String enc)
                    throws IOException

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.

writeFooter

protected void writeFooter()
                    throws IOException

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

Throws:

IOException

writeQualifiedName

protected void writeQualifiedName(String nsAlias,
                      String name)
                           throws IOException

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.

writeOpenTagStart

protected void writeOpenTagStart(String nsAlias,
                     String name)
                          throws IOException

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.

writeOpenTagEnd

protected void writeOpenTagEnd()
                        throws IOException

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

Throws:

IOException - thrown by the underlying writer.

writeCloseTag

protected void writeCloseTag(String nsAlias,
                 String name)
                      throws IOException

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.

writeAttribute

protected void writeAttribute(String name,
                  String value)
                       throws IOException

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.

writeAttribute

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

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.

characters

public void characters(String s)
                throws IOException

Emits character data subject to XML escaping.

Parameters:

s - string to emit. Can be null.

Throws:

IOException - thrown by the underlying writer.

characters

public void characters(String s,
              boolean useCData)
                throws IOException

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.

innerXml

public void innerXml(String xml)
              throws IOException

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.

writeUnescaped

public void writeUnescaped(String s)
                    throws IOException

Writes a string without XML entity escaping.

Parameters:

s - the raw content to write without escaping.

Throws:

IOException - thrown by the underlying writer.