Package 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

  • Field Details

    • DEBUG

      private static final boolean DEBUG
      Set to true to show debug info.
      See Also:

    • DEFAULT_NS

      private static final XMLWriterSAX.PrefixMapping DEFAULT_NS
      The default namespace mapped to the empty prefix.

    • ROOT

      private static final XMLWriterSAX.Element ROOT
      The root node.

    • NEW_LINE

      private static final char[] NEW_LINE
      The new line constant.

    • handler

      private final ContentHandler handler
      Where the XML data goes.

    • indent

      private boolean indent
      Indicates whether the xml should be indented or not.

      The default is true (indented).

      The indentation is 2 white-spaces.

    • indentChars

      private char[] indentChars
      The default indentation spaces used.

    • depth

      private transient int depth
      Level of the depth of the xml document currently produced.

      This attribute changes depending on the state of the instance.

    • isNude

      private transient boolean isNude
      Flag to indicate that the element open tag is not finished yet.

    • prefixMapping

      private transient Hashtable<String,String> prefixMapping
      The current prefix mapping.

    • tempMapping

      private transient List<XMLWriterSAX.PrefixMapping> tempMapping
      The list of prefix mappings to be associated with the next element.

    • elements

      private transient List<XMLWriterSAX.Element> elements
      A stack of elements to close the elements automatically.

    • attributes

      private transient XMLWriterSAX.AttributesImpl attributes
      The attributes attached to the current open element.

      This variable can be null and should be set to null, after the startElementMethod has been invoked.

  • Constructor Details

  • Method Details

    • 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:

    • 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:

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

    • deNude

      private void deNude() throws SAXException
      Writes the angle bracket if the element open tag is not finished.
      Throws:
      SAXException - If thrown by the content handler

    • 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

      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

      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

    • indent

      private void indent() throws SAXException
      Insert the correct amount of space characters depending on the depth and if the indent flag is set to true.
      Throws:
      SAXException - If thrown by the SAX handler.

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

    • peekElement

      private XMLWriterSAX.Element peekElement()
      Returns the last element in the list.
      Returns:
      The current element.

    • popElement

      private XMLWriterSAX.Element popElement()
      Removes the last element in the list.
      Returns:
      The current element.

    • 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:

    • getQName

      private String getQName(String uri, String name) throws UndeclaredNamespaceException
      Returns the qualified name for this element using the specified namespace URI.
      Parameters:
      uri - The namespace URI for the element.
      name - The name of the element or attribute.
      Returns:
      The qualified element name.
      Throws:
      UndeclaredNamespaceException - If the uri has not being previously declared.

    • restorePrefixMapping

      private void restorePrefixMapping(XMLWriterSAX.Element elt)
      Restores the prefix mapping after closing an element.

      This costly operation need only to be done if the method XMLWriterNSImpl.setPrefixMapping(String, String) have been used immediately before, therefore it should not happen often.

      Parameters:
      elt - The element that had some new mappings.

    • removeIfNeeded

      private void removeIfNeeded(String prefix)
      Removes the mapping associated to the specified prefix.
      Parameters:
      prefix - The prefix which mapping should be removed.

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

    • newLine

      private void newLine() throws SAXException
      Generates a new line as an ignorable white space event
      Throws:
      SAXException - If thrown by the handler.

    • handleEx

      private void handleEx(SAXException ex) throws IOException
      Handles the SAX Exception.
      Parameters:
      ex - A SAXException thrown by the content handler.
      Throws:
      IOException - If thrown by the handler.