com.topologi.diffx.xml
Class NSAwareXMLWriter

java.lang.Object
  com.topologi.diffx.xml.XMLWriterBase
      com.topologi.diffx.xml.NSAwareXMLWriter

All Implemented Interfaces:

XMLWriter

public final class NSAwareXMLWriter

extends com.topologi.diffx.xml.XMLWriterBase

implements XMLWriter

A Namespace-aware writer for XML data.

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.

Version:

5 April 2005

Author:

Christophe Lauret - Allette Systems (Australia)

Constructor Summary

NSAwareXMLWriter(Writer writer)
Creates a new XML writer.

NSAwareXMLWriter(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) Writes an attribute.
void	attribute(String uri, String name, String value) Writes an attribute.
void	close() Close 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() 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) Write a start element tag correctly indented.
void	openElement(String uri, String name, boolean hasChildren) Writes a start element tag correctly indented.
void	setPrefixMapping(String uri, String prefix) Sets a prefix mapping.
void	write(char c) Write the given character directly.
void	write(String s) Write the given string directly.
void	writeChar(char c) Write the given character correctly.
void	writeComment(String comment) Write an XML comment.
void	writePI(String target, String data) Writes an XML processing instruction.
void	writeText(char c) Writes the given text correctly for the encoding of this document.
void	writeText(char[] text, int off, int len) Writes the given text correctly for the encoding of this document.
void	writeText(Object o) Write 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() Write 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

close, element, flush, xmlDecl

Constructor Detail

NSAwareXMLWriter

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

NSAwareXMLWriter

public NSAwareXMLWriter(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

writeComment

public void writeComment(String comment)
                  throws IOException

Write an XML comment.

An XML comment is:

   <!-- comment -->
 

Comments are not indented.

Specified by:

writeComment in interface XMLWriter

Parameters:

comment - the comment to be written

Throws:

IOException - If thrown by the wrapped writer.

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 is occurs.

writeText

public void writeText(char c)
               throws IOException

Description copied from interface: XMLWriter

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:

c - The character to write.

Throws:

IOException - If an I/O exception occurs.

See Also:

XMLWriter.writeText(char)

writeText

public void writeText(String text)
               throws IOException

Description copied from interface: XMLWriter

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

This method turns the string into an array of chars.

Does nothing if the text is null.

Specified by:

writeText in interface XMLWriter

Parameters:

text - The text to write

Throws:

IOException - If thrown by the wrapped writer.

See Also:

XMLWriter.writeText(String)

writeText

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

Writes 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

len - The length to be written

Throws:

IOException - If thrown by the wrapped writer.

See Also:

XMLWriter.writeText(char[], int, int)

writeXML

public void writeXML(String text)
              throws IOException

Description copied from interface: XMLWriter

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

Throws:

IOException

See Also:

XMLWriter.writeXML(java.lang.String)

writeXML

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

Description copied from interface: XMLWriter

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

Throws:

IOException

See Also:

XMLWriter.writeXML(char[], int, int)

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

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.

attribute

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

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.

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

attribute

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

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.

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

attribute

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

Writes an attribute.

Specified by:

attribute in interface XMLWriter

Parameters:

uri - The namespcae 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,
                      IllegalStateException

Writes an attribute.

This method for number does not require escaping.

Specified by:

attribute in interface XMLWriter

Parameters:

uri - The namespcae 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.

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.

xmlDecl

public final void xmlDecl()
                   throws IOException

Write the XML declaration.

Always:

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

followed by a new line character.

Specified by:

xmlDecl in interface XMLWriter

Throws:

IOException - If thrown by the wrapped writer.

writeChar

public void writeChar(char c)
               throws IOException

Write the given character correctly.

• '<' escaped as '&lt;'
• '>' escaped as '&gt;'
• '&' escaped as '&amp;'
• Characters above 255 escaped as a character reference &#decimal_value;
• Control Characters 0 (less than 0x20) ignored, except line feed, carriage return and tabulations.
• Control Characters 1 (between 0x80 and 0x9f) ignored.
• Backspace character 0x7f ignored.

Parameters:

c - the character to write

Throws:

IOException - If thrown by the wrapped writer.

writeText

public final void writeText(Object o)
                     throws IOException

Write the string value of an object.

Do 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(), XMLWriterBase.writeText(java.lang.String)

element

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

Opens element, inserts text node and closes.

The same as:

   openElement(name);
   writeText(text);
   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.

write

public final void write(String s)
                 throws IOException

Write the given string directly.

Parameters:

s - the string to write

Throws:

IOException - If thrown by the wrapped writer.

write

public final void write(char c)
                 throws IOException

Write the given character directly.

Parameters:

c - the character to write

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.

close

public final void close()
                 throws IOException

Close the writer.

Specified by:

close in interface XMLWriter

Throws:

IOException - If thrown by the wrapped writer.