com.megginson.sax

## Class DataWriter

- java.lang.Object
- - org.xml.sax.helpers.XMLFilterImpl
  - - com.megginson.sax.XMLWriter
    - - com.megginson.sax.DataWriter

- All Implemented Interfaces:
    org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, org.xml.sax.XMLFilter, org.xml.sax.XMLReader

      public class DataWriter
      extends XMLWriter

  Write data- or field-oriented XML.

  This filter pretty-prints field-oriented XML without mixed content. all added indentation and newlines will be passed on down the filter chain (if any).

  In general, all whitespace in an XML document is potentially significant, so a general-purpose XML writing tool like the `XMLWriter` class cannot add newlines or indentation.

  There is, however, a large class of XML documents where information is strictly fielded: each element contains either character data or other elements, but not both. For this special case, it is possible for a writing tool to provide automatic indentation and newlines without requiring extra work from the user. Note that this class will likely not yield appropriate results for document-oriented XML like XHTML pages, which mix character data and elements together.

  This writer will automatically place each start tag on a new line, optionally indented if an indent step is provided (by default, there is no indentation). If an element contains other elements, the end tag will also appear on a new line with leading indentation. Consider, for example, the following code:

       DataWriter w = new DataWriter();

       w.setIndentStep(2);
       w.startDocument();
       w.startElement("Person");
       w.dataElement("name", "Jane Smith");
       w.dataElement("date-of-birth", "1965-05-23");
       w.dataElement("citizenship", "US");
       w.endElement("Person");
       w.endDocument();

  This code will produce the following document:

       <?xml version="1.0" standalone="yes"?>

       <Person>
         <name>Jane Smith</name>
         <date-of-birth>1965-05-23</date-of-birth>
         <citizenship>US</citizenship>
       </Person>

  This class inherits from `XMLWriter`, and provides all of the same support for Namespaces.

  Version:
    0.2
  Author:
    David Megginson, david@megginson.com
  See Also:
    `

    Use system platform end-of-line sequence instead of just \n. Use typed collections. Philip R. Burns. 2007/04/23 .

    `

- - ### Field Summary

    - ### Fields inherited from class com.megginson.sax.XMLWriter

      `LINE_SEPARATOR`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DataWriter()` Create a new data writer for standard output.
    `DataWriter(java.io.Writer writer)` Create a new data writer for the specified output.
    `DataWriter(org.xml.sax.XMLReader xmlreader)` Create a new data writer for standard output.
    `DataWriter(org.xml.sax.XMLReader xmlreader, java.io.Writer writer)` Create a new data writer for the specified output.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `characters(char[] ch, int start, int length)` Write a sequence of characters.
    `void` | `emptyElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)` Write a empty element tag.
    `void` | `endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)` Write an end tag.
    `int` | `getIndentStep()` Return the current indent step.
    `void` | `reset()` Reset the writer so that it can be reused.
    `void` | `setIndentStep(int indentStep)` Set the current indent step.
    `void` | `startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)` Write a start tag.

    - ### Methods inherited from class com.megginson.sax.XMLWriter

      `characters, dataElement, dataElement, dataElement, emptyElement, emptyElement, endDocument, endElement, endElement, flush, forceNSDecl, forceNSDecl, getPrefix, ignorableWhitespace, processingInstruction, setDoctype, setOutput, setOutputCharsAsIs, setPrefix, startDocument, startElement, startElement, write, write, writeEsc`

    - ### Methods inherited from class org.xml.sax.helpers.XMLFilterImpl

      `endPrefixMapping, error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, getProperty, notationDecl, parse, parse, resolveEntity, setContentHandler, setDocumentLocator, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setParent, setProperty, skippedEntity, startPrefixMapping, unparsedEntityDecl, warning`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DataWriter

          public DataWriter()

      Create a new data writer for standard output.

    - #### DataWriter

          public DataWriter(org.xml.sax.XMLReader xmlreader)

      Create a new data writer for standard output.

      Use the XMLReader provided as the source of events.

      Parameters:
        `xmlreader` - The parent in the filter chain.

    - #### DataWriter

          public DataWriter(java.io.Writer writer)

      Create a new data writer for the specified output.
      Parameters:
        `writer` - The character stream where the XML document will be written.

    - #### DataWriter

          public DataWriter(org.xml.sax.XMLReader xmlreader,
                    java.io.Writer writer)

      Create a new data writer for the specified output.

      Use the XMLReader provided as the source of events.

      Parameters:
        `xmlreader` - The parent in the filter chain.
        `writer` - The character stream where the XML document will be written.

  - ### Method Detail

    - #### getIndentStep

          public int getIndentStep()

      Return the current indent step.

      Return the current indent step: each start tag will be indented by this number of spaces times the number of ancestors that the element has.

      Returns:
        The number of spaces in each indentation step, or 0 or less for no indentation.
      See Also:
        `setIndentStep(int)`

    - #### setIndentStep

          public void setIndentStep(int indentStep)

      Set the current indent step.
      Parameters:
        `indentStep` - The new indent step (0 or less for no indentation).
      See Also:
        `getIndentStep()`

    - #### reset

          public void reset()

      Reset the writer so that it can be reused.

      This method is especially useful if the writer failed with an exception the last time through.

      Overrides:
        `reset` in class `XMLWriter`
      See Also:
        `XMLWriter.reset()`

    - #### startElement

          public void startElement(java.lang.String uri,
                          java.lang.String localName,
                          java.lang.String qName,
                          org.xml.sax.Attributes atts)
                            throws org.xml.sax.SAXException

      Write a start tag.

      Each tag will begin on a new line, and will be indented by the current indent step times the number of ancestors that the element has.

      The newline and indentation will be passed on down the filter chain through regular characters events.

      Specified by:
        `startElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startElement` in class `XMLWriter`
      Parameters:
        `uri` - The element's Namespace URI.
        `localName` - The element's local name.
        `qName` - The element's qualified (prefixed) name.
        `atts` - The element's attribute list.
      Throws:
        `org.xml.sax.SAXException` - If there is an error writing the start tag, or if a filter further down the chain raises an exception.
      See Also:
        `XMLWriter.startElement(String, String, String, Attributes)`

    - #### endElement

          public void endElement(java.lang.String uri,
                        java.lang.String localName,
                        java.lang.String qName)
                          throws org.xml.sax.SAXException

      Write an end tag.

      If the element has contained other elements, the tag will appear indented on a new line; otherwise, it will appear immediately following whatever came before.

      The newline and indentation will be passed on down the filter chain through regular characters events.

      Specified by:
        `endElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endElement` in class `XMLWriter`
      Parameters:
        `uri` - The element's Namespace URI.
        `localName` - The element's local name.
        `qName` - The element's qualified (prefixed) name.
      Throws:
        `org.xml.sax.SAXException` - If there is an error writing the end tag, or if a filter further down the chain raises an exception.
      See Also:
        `XMLWriter.endElement(String, String, String)`

    - #### emptyElement

          public void emptyElement(java.lang.String uri,
                          java.lang.String localName,
                          java.lang.String qName,
                          org.xml.sax.Attributes atts)
                            throws org.xml.sax.SAXException

      Write a empty element tag.

      Each tag will appear on a new line, and will be indented by the current indent step times the number of ancestors that the element has.

      The newline and indentation will be passed on down the filter chain through regular characters events.

      Overrides:
        `emptyElement` in class `XMLWriter`
      Parameters:
        `uri` - The element's Namespace URI.
        `localName` - The element's local name.
        `qName` - The element's qualified (prefixed) name.
        `atts` - The element's attribute list.
      Throws:
        `org.xml.sax.SAXException` - If there is an error writing the empty tag, or if a filter further down the chain raises an exception.
      See Also:
        `XMLWriter.emptyElement(String, String, String, Attributes)`

    - #### characters

          public void characters(char[] ch,
                        int start,
                        int length)
                          throws org.xml.sax.SAXException

      Write a sequence of characters.
      Specified by:
        `characters` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `characters` in class `XMLWriter`
      Parameters:
        `ch` - The characters to write.
        `start` - The starting position in the array.
        `length` - The number of characters to use.
      Throws:
        `org.xml.sax.SAXException` - If there is an error writing the characters, or if a filter further down the chain raises an exception.
      See Also:
        `XMLWriter.characters(char[], int, int)`