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

java.lang.Object
  extended by com.google.gdata.util.common.xml.XmlWriter

public class XmlWriter
extends java.lang.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
static class XmlWriter.Attribute
          The Attribute class represents an XML attribute.
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.
 
Constructor Summary
XmlWriter(java.io.Writer w)
          Constructs an XmlWriter instance associated that will generate XML content to an underlying Writer.
XmlWriter(java.io.Writer w, boolean includeHeader)
          Deprecated. see XmlWriter(Writer, Set, String)
XmlWriter(java.io.Writer w, java.util.Set<XmlWriter.WriterFlags> f, java.lang.String encoding)
          The default namespace that will take effect on the next element transition.
XmlWriter(java.io.Writer w, java.util.Set<XmlWriter.WriterFlags> f, java.lang.String encoding, boolean standalone)
          Constructor that allows standalone directive to be provided.
XmlWriter(java.io.Writer w, java.lang.String encoding)
          Constructor that writers header including encoding information.
 
Method Summary
 void characters(java.lang.String s)
          Emits character data subject to XML escaping.
 void characters(java.lang.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()
          Ends the current element.
 void endElement(XmlNamespace namespace, java.lang.String name)
          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(java.lang.String xml)
          Writes inner XML provided as a string.
 void setDefaultNamespace(XmlNamespace namespace)
          Sets the default namespace.
 void simpleElement(java.lang.String name, java.lang.String value)
          Emits a simple element (without child elements).
 void simpleElement(XmlNamespace namespace, java.lang.String name, java.util.List<XmlWriter.Attribute> attrs, java.lang.String value)
          Emits a simple element (without child elements).
 void startElement(java.lang.String name)
          Starts an element.
 void startElement(XmlNamespace namespace, java.lang.String name, java.util.Collection<XmlWriter.Attribute> attrs, java.util.Collection<? extends XmlNamespace> namespaceDecls)
          Starts an element.
 void startRepeatingElement()
          Indicates that a series of repeating elements are about to be written.
 void writeUnescaped(java.lang.String s)
          Writes a string without XML entity escaping.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlWriter

public XmlWriter(java.io.Writer w,
                 java.util.Set<XmlWriter.WriterFlags> f,
                 java.lang.String encoding,
                 boolean standalone)
          throws java.io.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:
java.io.IOException - thrown by the underlying writer
See Also:
XmlWriter.WriterFlags

XmlWriter

public XmlWriter(java.io.Writer w,
                 java.util.Set<XmlWriter.WriterFlags> f,
                 java.lang.String encoding)
          throws java.io.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:
java.io.IOException - thrown by the underlying writer.
See Also:
XmlWriter.WriterFlags

XmlWriter

public XmlWriter(java.io.Writer w)
          throws java.io.IOException
Constructs an XmlWriter instance associated that will generate XML content to an underlying Writer.

Parameters:
w - output writer object.
Throws:
java.io.IOException - thrown by the underlying writer.

XmlWriter

public XmlWriter(java.io.Writer w,
                 java.lang.String encoding)
          throws java.io.IOException
Constructor that writers header including encoding information.

Parameters:
w - Output writer object.
encoding - output encoding to use in declaration.
Throws:
java.io.IOException - thrown by the underlying writer.

XmlWriter

@Deprecated
public XmlWriter(java.io.Writer w,
                            boolean includeHeader)
          throws java.io.IOException
Deprecated. see XmlWriter(Writer, Set, String)

Throws:
java.io.IOException
Method Detail

close

public void close()
           throws java.io.IOException
Closes the XmlWriter and the underlying output writer.

Throws:
java.io.IOException - thrown by the underlying writer.

flush

public void flush()
           throws java.io.IOException
Flushes the XmlWriter and the underlying output writer.

Throws:
java.io.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.

startElement

public void startElement(java.lang.String name)
                  throws java.io.IOException
Starts an element. This element can be a parent to other elements.

Parameters:
name - element name.
Throws:
java.io.IOException

startElement

public void startElement(XmlNamespace namespace,
                         java.lang.String name,
                         java.util.Collection<XmlWriter.Attribute> attrs,
                         java.util.Collection<? extends XmlNamespace> namespaceDecls)
                  throws java.io.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:
java.io.IOException - thrown by the underlying writer.

endElement

public void endElement(XmlNamespace namespace,
                       java.lang.String name)
                throws java.io.IOException
Ends the current element. It is expected to be on top of the stack.

Parameters:
namespace - element namespace.
name - element name.
Throws:
java.io.IOException

endElement

public void endElement()
                throws java.io.IOException
Ends the current element. No integrity checking is performed.

Throws:
java.io.IOException

simpleElement

public void simpleElement(java.lang.String name,
                          java.lang.String value)
                   throws java.io.IOException
Emits a simple element (without child elements).

Parameters:
name - element name.
value - element value. Can be null.
Throws:
java.io.IOException - thrown by the underlying writer.

startRepeatingElement

public void startRepeatingElement()
                           throws java.io.IOException
Indicates that a series of repeating elements are about to be written.

Throws:
java.io.IOException

endRepeatingElement

public void endRepeatingElement()
                         throws java.io.IOException
Indicates that the series of repeating elements have been completely written.

Throws:
java.io.IOException

simpleElement

public void simpleElement(XmlNamespace namespace,
                          java.lang.String name,
                          java.util.List<XmlWriter.Attribute> attrs,
                          java.lang.String value)
                   throws java.io.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:
java.io.IOException - thrown by the underlying writer.

characters

public void characters(java.lang.String s)
                throws java.io.IOException
Emits character data subject to XML escaping.

Parameters:
s - string to emit. Can be null.
Throws:
java.io.IOException - thrown by the underlying writer.

characters

public void characters(java.lang.String s,
                       boolean useCData)
                throws java.io.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:
java.io.IOException - thrown by the underlying writer.

innerXml

public void innerXml(java.lang.String xml)
              throws java.io.IOException
Writes inner XML provided as a string. Used to write out XML blobs.

Parameters:
xml - XML blob string.
Throws:
java.io.IOException - thrown by the underlying writer.

writeUnescaped

public void writeUnescaped(java.lang.String s)
                    throws java.io.IOException
Writes a string without XML entity escaping.

Parameters:
s - the raw content to write without escaping.
Throws:
java.io.IOException - thrown by the underlying writer.