com.topologi.diffx.xml
Class XMLWriterImpl

java.lang.Object
  com.topologi.diffx.xml.XMLWriterImpl

All Implemented Interfaces:

XMLWriter

public final class XMLWriterImpl
extends Object
implements XMLWriter

A simple writer for XML data that does not support namespaces.

Provides methods to generate well-formed XML data easily, wrapping a writer.

This version only supports utf-8 encoding, if writing to a file make sure that the encoding of the file output stream is "utf-8".

The recommended implementation is to use a BufferedWriter to write.

  Writer writer =
     new BufferedWriter(new OutputStreamWriter(new FileOutputStream("foo.out"),"utf-8"));
 

This class is not synchronised and does not support namespaces, and will therefore throw an unsupported operation exception for each call to a method that uses namespaces.

Version:

6 December 2008

Author:

Christophe Lauret

Constructor Summary

XMLWriterImpl(Writer writer)
Creates a new XML writer.

XMLWriterImpl(Writer writer, boolean indent)
Create a new XML writer.

Method Summary

void	attribute(String name, int value) Writes an attribute.
void	attribute(String name, String value) Writes an attribute.
void	attribute(String uri, String name, int value) Not supported.
void	attribute(String uri, String name, String value) Not supported.
void	close() Close the writer.
void	closeElement() Write the end element tag.
void	element(String name, String text) Opens element, inserts text node and closes.
void	emptyElement(String element) Same as emptyElement(null, element);.
void	emptyElement(String uri, String element) Not supported.
void	flush() Flush the writer.
void	openElement(String name) Writes a start element tag correctly indented.
void	openElement(String name, boolean hasChildren) Writes a start element tag correctly indented.
void	openElement(String uri, String name) Not supported.
void	openElement(String uri, String name, boolean hasChildren) Not supported.
void	setEncoding(String encoding) Sets the encoding to use.
void	setIndentChars(String spaces) Sets the string to use for indentation.
void	setPrefixMapping(String uri, String prefix) Not supported.
void	writeCDATA(String data) Writes the given text as a CDATA section.
void	writeComment(String comment) Writes an XML comment.
void	writePI(String target, String data) Writes an XML processing instruction.
void	writeText(char c) Writes the given character correctly for the encoding of this document.
void	writeText(char[] text, int off, int len) Write the given text correctly for the encoding of this document.
void	writeText(Object o) Writes the string value of an object.
void	writeText(String text) Writes the given text correctly for the encoding of this document.
void	writeXML(char[] text, int off, int len) Write the given XML data.
void	writeXML(String text) Writes the given XML data.
void	xmlDecl() Writes the XML declaration.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.topologi.diffx.xml.XMLWriter

attribute, attribute, element, flush, setIndentChars, writeCDATA, writeComment, writePI, writeText, writeText, writeText, writeXML, writeXML, xmlDecl

Constructor Detail

XMLWriterImpl

public XMLWriterImpl(Writer writer)
              throws NullPointerException

Creates a new XML writer.

Sets the depth attribute to 0 and the indentation to true.

Parameters:

writer - Where this writer should write the XML data.

Throws:

NullPointerException - If the writer is null.

XMLWriterImpl

public XMLWriterImpl(Writer writer,
                     boolean indent)
              throws NullPointerException

Create a new XML writer.

Parameters:

writer - Where this writer should write the XML data.

indent - Set the indentation flag.

Throws:

NullPointerException - If the writer is null.

Method Detail

openElement

public void openElement(String name)
                 throws IOException

Writes a start element tag correctly indented.

It is the same as openElement(null, name, false)

Specified by:

openElement in interface XMLWriter

Parameters:

name - The name of the element

Throws:

IOException - If thrown by the wrapped writer.

See Also:

openElement(java.lang.String, java.lang.String, boolean)

openElement

public void openElement(String name,
                        boolean hasChildren)
                 throws IOException

Writes a start element tag correctly indented.

Use the hasChildren parameter to specify whether this element is terminal node or not, which affects the indenting.

The name can contain attributes and should be a valid xml name.

Specified by:

openElement in interface XMLWriter

Parameters:

name - The name of the element.

hasChildren - true if this element has children.

Throws:

IOException - If thrown by the wrapped writer.

closeElement

public void closeElement()
                  throws IOException,
                         IllegalCloseElementException

Write the end element tag.

Specified by:

closeElement in interface XMLWriter

Throws:

IOException - If thrown by the wrapped writer.

IllegalCloseElementException - If there is no element to close

emptyElement

public void emptyElement(String element)
                  throws IOException

Same as emptyElement(null, element);.

It is possible for the element to contain attributes, however, since there is no character escaping, great care must be taken not to introduce invalid characters. For example:

    <example test="yes"/>
 

Specified by:

emptyElement in interface XMLWriter

Parameters:

element - the name of the element

Throws:

IOException - If thrown by the wrapped writer.

openElement

public void openElement(String uri,
                        String name)
                 throws UnsupportedOperationException

Not supported.

Parameters:

uri - This parameter is ignored.

name - This parameter is ignored.

Throws:

UnsupportedOperationException - This class does not handle namespaces.

openElement

public void openElement(String uri,
                        String name,
                        boolean hasChildren)
                 throws UnsupportedOperationException

Not supported.

Specified by:

openElement in interface XMLWriter

Parameters:

uri - This parameter is ignored.

name - This parameter is ignored.

hasChildren - This parameter is ignored.

Throws:

UnsupportedOperationException - This class does not handle namespaces.

emptyElement

public void emptyElement(String uri,
                         String element)
                  throws UnsupportedOperationException

Not supported.

Specified by:

emptyElement in interface XMLWriter

Parameters:

uri - This parameter is ignored.

element - This parameter is ignored.

Throws:

UnsupportedOperationException - This class does not handle namespaces.

setPrefixMapping

public void setPrefixMapping(String uri,
                             String prefix)
                      throws UnsupportedOperationException

Not supported.

Specified by:

setPrefixMapping in interface XMLWriter

Parameters:

uri - This parameter is ignored.

prefix - This parameter is ignored.

Throws:

UnsupportedOperationException - This class does not handle namespaces.

attribute

public void attribute(String uri,
                      String name,
                      String value)
               throws UnsupportedOperationException

Not supported.

Specified by:

attribute in interface XMLWriter

Parameters:

uri - This parameter is ignored.

name - The name of the attribute.

value - The value of the attribute.

Throws:

UnsupportedOperationException - This class does not handle namespaces.

attribute

public void attribute(String uri,
                      String name,
                      int value)
               throws UnsupportedOperationException

Not supported.

Specified by:

attribute in interface XMLWriter

Parameters:

uri - This parameter is ignored.

name - The name of the attribute.

value - The value of the attribute.

Throws:

UnsupportedOperationException - This class does not handle namespaces.

close

public void close()
           throws IOException,
                  UnclosedElementException

Close the writer.

Specified by:

close in interface XMLWriter

Throws:

IOException - If thrown by the wrapped writer.

UnclosedElementException - If an element has been left open.

xmlDecl

public final void xmlDecl()
                   throws IOException

Writes the XML declaration.

Always:

   <?xml version="1.0" encoding="encoding"?>
 

It is followed by a new line character if the indentation is turned on.

Specified by:

xmlDecl in interface XMLWriter

Throws:

IOException - If an I/O exception is thrown by the underlying writer.

setIndentChars

public final void setIndentChars(String spaces)
                          throws IllegalStateException,
                                 IllegalArgumentException

Sets the string to use for indentation.

The string must be only composed of valid spaces characters.

If the string is null then the indentation is turned off.

Specified by:

setIndentChars in interface XMLWriter

Parameters:

spaces - The indentation string to use.

Throws:

IllegalStateException - If the writer has already been used.

IllegalArgumentException - If the indent string is not made of spaces.

See Also:

Character.isSpaceChar(char)

setEncoding

public final void setEncoding(String encoding)
                       throws IllegalStateException,
                              IllegalArgumentException

Sets the encoding to use.

The encoding must match the encoding used if there is an underlying OutputStreamWriter.

Parameters:

encoding - The encoding to use.

Throws:

IllegalArgumentException - If the encoding is not valid.

IllegalStateException - If the writer has already been used.

writeText

public final void writeText(String text)
                     throws IOException

Writes the given text correctly for the encoding of this document.

Does nothing if the text is null.

Specified by:

writeText in interface XMLWriter

Parameters:

text - The text to write

Throws:

IOException - If an I/O exception is thrown by the underlying writer.

writeText

public final void writeText(char[] text,
                            int off,
                            int len)
                     throws IOException

Write the given text correctly for the encoding of this document.

Specified by:

writeText in interface XMLWriter

Parameters:

text - The text to write.

off - The offset where we should start writing the string.

len - The length of the character subarray to write.

Throws:

IOException - If an I/O exception is thrown by the underlying writer.

writeText

public final void writeText(char c)
                     throws IOException

Writes the given character correctly for the encoding of this document.

Specified by:

writeText in interface XMLWriter

Parameters:

c - The character to write.

Throws:

IOException - If an I/O exception is thrown by the underlying writer.

writeText

public final void writeText(Object o)
                     throws IOException

Writes the string value of an object.

Does nothing if the object is null.

Parameters:

o - The object that should be written as text.

Throws:

IOException - If thrown by the wrapped writer.

See Also:

Object.toString(), writeText(java.lang.String)

writeXML

public final void writeXML(String text)
                    throws IOException

Writes the given XML data.

The text is appended as is, therefore it should be escaped properly for the encoding used by the underlying stream writer.

Does nothing if the text is null.

Specified by:

writeXML in interface XMLWriter

Parameters:

text - The text to write.

Throws:

IOException - If an I/O exception is thrown by the underlying writer.

writeXML

public final void writeXML(char[] text,
                           int off,
                           int len)
                    throws IOException

Write the given XML data.

The text is appended as is, therefore it should be escaped properly for the encoding used by the underlying stream writer.

Specified by:

writeXML in interface XMLWriter

Parameters:

text - The text to write.

off - The offset where we should start writing the string.

len - The length of the character subarray to write.

Throws:

IOException - If an I/O exception is thrown by the underlying writer.

writeComment

public final void writeComment(String comment)
                        throws IOException,
                               IllegalArgumentException

Writes an XML comment.

An XML comment is:

   <!-- comment -->
 

Comments are not indented.

Does not write anything if the comment if null.

Specified by:

writeComment in interface XMLWriter

Parameters:

comment - The comment to be written

Throws:

IOException - If thrown by the wrapped writer.

IllegalArgumentException - If the comment contains "--".

writePI

public final void writePI(String target,
                          String data)
                   throws IOException

Writes an XML processing instruction.

An XML processing intruction is:

   <?target data?>
 

Specified by:

writePI in interface XMLWriter

Parameters:

target - The PI's target.

data - The PI's data.

Throws:

IOException - If an I/O exception occurs.

writeCDATA

public final void writeCDATA(String data)
                      throws IOException

Writes the given text as a CDATA section.

Does nothing if the text is null.

Specified by:

writeCDATA in interface XMLWriter

Parameters:

data - The data to write inside the CDATA section.

Throws:

IOException - If an I/O exception is thrown by the underlying writer.

attribute

public final void attribute(String name,
                            String value)
                     throws IOException

Writes an attribute.

Specified by:

attribute in interface XMLWriter

Parameters:

name - The name of the attribute.

value - The value of the attribute.

Throws:

IOException - If thrown by the wrapped writer.

attribute

public final void attribute(String name,
                            int value)
                     throws IOException

Writes an attribute.

This method for number does not require escaping.

Specified by:

attribute in interface XMLWriter

Parameters:

name - The name of the attribute.

value - The value of the attribute.

Throws:

IOException - If thrown by the wrapped writer.

element

public void element(String name,
                    String text)
             throws IOException

Opens element, inserts text node and closes.

This method should behave like:

   this.openElement(name, false);
   this.writeText(text);
   this.closeElement();
 

Specified by:

element in interface XMLWriter

Parameters:

name - The name of the element.

text - The text of the element.

Throws:

IOException - If thrown by the wrapped writer.

flush

public final void flush()
                 throws IOException

Flush the writer.

Specified by:

flush in interface XMLWriter

Throws:

IOException - If thrown by the wrapped writer.