com.topologi.diffx.xml.sax
Class XMLWriterSAX

java.lang.Object
  com.topologi.diffx.xml.sax.XMLWriterSAX

All Implemented Interfaces:

XMLWriter

public final class XMLWriterSAX
extends Object
implements XMLWriter

An XML writer that generates SAX2 events.

Provides methods to generate well-formed XML data easily through SAX events by wrapping a content handler.

This XML writer provides an efficient way to process XML bypassing the need to create an XML stream. Instead, this class will wrap a ContentHandler and invoke the SAX2 methods.

  ContentHandler myContentHandler = ...;
  XMLWriter saxWriter = new XMLWriterSAX(myContentHandler);
 

This SAX event writer as the following features:

• http://xml.org/sax/features/namespaces set to true
• http://xml.org/sax/features/namespace-prefixes set to false

Consequently, the attributes will not contain attributes used for namespace declarations (xmlns* attributes).

This implementation does not provide qualified names, and will always return "".

The ContentHandler's startDocument and endDocument methods have to be called externally.

Note that the write methods do not necessarily correspond to the content handler methods or at least they may not be invoked at the same time. For example, the attribute methods will not generate any event until it is possible to invoke the ContentHandler#startElement method.

Version:

15 January 2007

Author:

Christophe Lauret

Constructor Summary

XMLWriterSAX(ContentHandler handler)
Creates 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) Writes an attribute.
void	attribute(String uri, String name, String value) Writes an attribute.
void	close() Closes the writer.
void	closeElement() Write an 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) Write an empty element.
void	flush() Does nothing.
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) Write a start element tag correctly indented.
void	openElement(String uri, String name, boolean hasChildren) Writes a start element tag correctly indented.
void	setIndentChars(String spaces) Sets the string to use for indentation.
void	setPrefixMapping(String uri, String prefix) Sets a prefix mapping.
void	writeCDATA(String data) Writes the given text as a CDATA section.
void	writeComment(String comment) Does nothing as SAX content handler do not handle comments.
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) Always throw an UnsupportedOperationException exception.
void	writeXML(String text) Always throw an UnsupportedOperationException exception.
void	xmlDecl() Does nothing.

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLWriterSAX

public XMLWriterSAX(ContentHandler handler)
             throws NullPointerException

Creates a new XML writer.

Parameters:

handler - The SAX2 content handler to use.

Throws:

NullPointerException - If the handler is null.

Method Detail

xmlDecl

public void xmlDecl()

Does nothing.

Specified by:

xmlDecl in interface XMLWriter

setIndentChars

public 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)

writeText

public 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 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 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 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)

writeCDATA

public void writeCDATA(String data)
                throws IOException

Description copied from interface: XMLWriter

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.

writeXML

public void writeXML(String text)
              throws UnsupportedOperationException

Always throw an UnsupportedOperationException exception. 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:

UnsupportedOperationException

writeXML

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

Always throw an UnsupportedOperationException exception. 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:

UnsupportedOperationException

writeComment

public void writeComment(String comment)

Does nothing as SAX content handler do not handle comments. 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

writePI

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

attribute

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

attribute

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

Writes an attribute.

Specified by:

attribute in interface XMLWriter

Parameters:

uri - The namespace URI this attribute belongs to.

name - The name of the attribute.

value - The value of the attribute.

Throws:

IOException - If thrown by the wrapped writer.

IllegalStateException - If there is no open element or text has been written.

attribute

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

Writes an attribute.

This method for number does not require escaping.

Specified by:

attribute in interface XMLWriter

Parameters:

uri - The namespace URI this attribute belongs to.

name - The name of the attribute.

value - The value of the attribute.

Throws:

IOException - If thrown by the wrapped writer.

IllegalStateException - If there is no open element or text has been written.

openElement

public void openElement(String name)
                 throws IOException

Writes a start element tag correctly indented.

It is the same as openElement("", 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 uri,
                        String name)
                 throws IOException

Write a start element tag correctly indented.

It is the same as openElement(name, false)

Parameters:

uri - The namespace URI of this element.

name - The name of the element.

Throws:

IOException - If thrown by the wrapped writer.

See Also:

openElement(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, note: this affects the indenting. To produce correctly indented XML, you should use the same value for this flag when closing the element.

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.

openElement

public void openElement(String uri,
                        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, note: this affects the indenting. To produce correctly indented XML, you should use the same value for this flag when closing the element.

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

Specified by:

openElement in interface XMLWriter

Parameters:

uri - The namespace URI of this element.

name - The name of the element.

hasChildren - true if this element has children.

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 void flush()

Does nothing.

Specified by:

flush in interface XMLWriter

closeElement

public void closeElement()
                  throws IOException

Write an end element tag.

Specified by:

closeElement in interface XMLWriter

Throws:

IOException - If thrown by the wrapped writer.

emptyElement

public void emptyElement(String element)
                  throws IOException

Same as emptyElement(null, element);.

Specified by:

emptyElement in interface XMLWriter

Parameters:

element - the name of the element

Throws:

IOException - If thrown by the wrapped writer.

emptyElement

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

Write an empty 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:

uri - The namespace URI for this element.

element - The name of the element.

Throws:

IOException - If thrown by the wrapped writer.

setPrefixMapping

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

Description copied from interface: XMLWriter

Sets a prefix mapping.

Specified by:

setPrefixMapping in interface XMLWriter

Parameters:

uri - The full namespace URI.

prefix - The prefix for the namespace uri.

Throws:

NullPointerException - if the prefix is null.

See Also:

This implementation does not keep a history of the prefix mappings so it needs to be reset. If a prefix is already being used it is overridden.

close

public void close()
           throws IOException,
                  UnclosedElementException

Closes the writer.

This method only checks that it is possible to 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.