Package com.topologi.diffx.xml

Interface XMLWriter

All Known Subinterfaces:
DOMWriter
All Known Implementing Classes:
DOMWriterImpl, XMLStringWriter, XMLWriterBase, XMLWriterImpl, XMLWriterNSImpl, XMLWriterSAX
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:
11 December 2011

  • Method Details

    • xmlDecl

      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.

      Throws:
      IOException - If an I/O exception is thrown by the underlying writer.
      IllegalStateException - If this method is called after the writer has started writing elements nodes.

    • setIndentChars

      void setIndentChars(String spaces)
      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.

      Parameters:
      spaces - The indentation string to use.
      Throws:
      IllegalArgumentException - If the indent string is not made of spaces.
      IllegalStateException - If the writer has already been used.
      See Also:

    • writeText

      void writeText(char c) throws IOException
      Writes the given character correctly for the encoding of this document.
      Parameters:
      c - The character to write.
      Throws:
      IOException - If an I/O exception is thrown by the underlying writer.

    • writeText

      void writeText(String text) throws IOException
      Writes the given text correctly for the encoding of this document.

      Does nothing if the text is null.

      Parameters:
      text - The text to write
      Throws:
      IOException - If an I/O exception is thrown by the underlying writer.

    • writeText

      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 is thrown by the underlying writer.

    • writeCDATA

      void writeCDATA(String data) throws IOException
      Writes the given text as a CDATA section.

      Does nothing if the text is null.

      Parameters:
      data - The data to write inside the CDATA section.
      Throws:
      IOException - If an I/O exception is thrown by the underlying writer.
      IllegalArgumentException - If the implementation does not support CDATA nesting

    • writeXML

      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 is thrown by the underlying writer.

    • writeXML

      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 is thrown by the underlying writer.

    • writeComment

      void writeComment(String comment) throws IOException
      Writes an XML comment.

      An XML comment is:

         <!-- comment -->

      Comments are not indented.

      Does not write anything if the comment if null.

      Parameters:
      comment - The comment to be written
      Throws:
      IOException - If thrown by the wrapped writer.
      IllegalArgumentException - If the comment contains "--".

    • writePI

      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

      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

      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

      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.

      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

      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

      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();
      Parameters:
      name - The name of the element.
      text - The text of the element.
      Throws:
      IOException - If thrown by the wrapped writer.

    • emptyElement

      void emptyElement(String element) throws IOException
      Writes 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

      void emptyElement(String uri, String element) throws IOException
      Writes 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

      void attribute(String name, String value) throws IOException
      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

      void attribute(String name, int value) throws IOException
      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

      void attribute(String uri, String name, String value) throws IOException
      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

      void attribute(String uri, String name, int value) throws IOException
      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

      void setPrefixMapping(String uri, String prefix)
      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

      void flush() throws IOException
      Flush the writer.
      Throws:
      IOException - If thrown by the wrapped writer.

    • close

      void close() throws IOException
      Close the writer.
      Throws:
      IOException - If thrown by the wrapped writer.
      UnclosedElementException - If there is still an open element.