com.topologi.diffx.xml
Interface XMLWriter

All Known Implementing Classes:

NSAwareXMLWriter, SimpleXMLWriter, com.topologi.diffx.xml.XMLWriterBase

public interface XMLWriter

Defines a writer for XML data.

This interface provides simple methods to write XML data onto a writer.

Most implementation should wrap a writer or an output stream. Implementations can be focused on performance, reliability, error reporting, etc...

For improved performance, the most efficient solution will generally to have an implementation write on a buffered writer since the memory usage will generally be restricted little more than the size of the buffer, and this will keep the I/O operation to a minimum.

Other implementations might want to wrap a SAX content handler.

Version:

17 March 2005

Author:

Christophe Lauret (Allette Systems)

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() Close the element automatically.
void	element(String name, String text) Opens element, inserts text node and closes.
void	emptyElement(String element) Write an empty 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, boolean hasChildren) Writes a start element tag correctly indented.
void	setPrefixMapping(String uri, String prefix) Sets a prefix mapping.
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 text 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(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.

Method Detail

writeText

public void writeText(char c)
               throws IOException

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

Does nothing if the text is null.

Parameters:

c - The character to write.

Throws:

IOException - If an I/O exception occurs.

writeText

public void writeText(String text)
               throws IOException

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.

Parameters:

text - The text to write.

Throws:

IOException - If an I/O exception occurs.

writeText

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

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

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

writeXML

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

Parameters:

text - The text to write.

Throws:

IOException - If an I/O exception occurs.

writeXML

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

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

xmlDecl

public void xmlDecl()
             throws IOException,
                    IllegalStateException

Writes the XML declaration.

Always:

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

followed by a new line character.

Throws:

IOException - If an I/O exception occurs.

IllegalStateException - If this method is called after the writer has started writing elements nodes.

writeComment

public void writeComment(String comment)
                  throws IOException

Writes an XML comment.

An XML comment is:

   <!-- comment -->
 

Parameters:

comment - The comment to be written.

Throws:

IOException - If an I/O exception occurs.

writePI

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

Writes an XML processing instruction.

An XML processing intruction is:

   <?target data?>
 

Parameters:

target - The PI's target.

data - The PI's data.

Throws:

IOException - If an I/O exception occurs.

openElement

public void openElement(String name)
                 throws IOException

Writes a start element tag correctly indented.

It is the same as openElement(name, false)

Parameters:

name - the name of the element

Throws:

IOException - If an I/O exception occurs.

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.

Parameters:

name - The name of the element

hasChildren - true if this element has children

Throws:

IOException - If an I/O exception occurs.

openElement

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

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.

Parameters:

uri - The namespace URI of the element.

name - The name of the element.

hasChildren - true if this element has children.

Throws:

IOException - If an I/O exception occurs.

UnsupportedOperationException - If the implementing class does not handle namespace.

closeElement

public void closeElement()
                  throws IOException

Close the element automatically.

The element is closed symmetrically to the openElement(String, String, boolean) method if the XML writer is namespace aware or the openElement(String, boolean)method.

Throws:

IOException - If an I/O exception occurs.

element

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

Opens element, inserts text node and closes.

Parameters:

name - The name of the element.

text - The text of the element.

Throws:

IOException - If thrown by the wrapped writer.

emptyElement

public void emptyElement(String element)
                  throws IOException,
                         UnsupportedOperationException

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"/>
 

Parameters:

element - the name of the element

Throws:

IOException - If an I/O exception occurs.

UnsupportedOperationException - If the implementing class does not handle namespace.

emptyElement

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

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"/>
 

Parameters:

uri - The namespace URI of the element.

element - The name of the element.

Throws:

IOException - If an I/O exception occurs.

UnsupportedOperationException - If the implementing class does not handle namespace.

attribute

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

Writes an attribute.

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.

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,
                      UnsupportedOperationException

Writes an attribute.

Parameters:

uri - The uri of the attribute.

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.

UnsupportedOperationException - If the implementing class does not handle namespace.

attribute

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

Writes an attribute.

This method for number does not require escaping.

Parameters:

uri - The uri of the attribute.

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.

UnsupportedOperationException - If the implementing class does not handle namespace.

setPrefixMapping

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

Sets a prefix mapping.

Parameters:

uri - The namespace URI.

prefix - The new prefix for the namespace URI.

Throws:

UnsupportedOperationException - If the implementing class does not handle namespace.

flush

public void flush()
           throws IOException

Flush the writer.

Throws:

IOException - If thrown by the wrapped writer.

close

public void close()
           throws IOException

Close the writer.

Throws:

IOException - If thrown by the wrapped writer.