Package org.restlet.ext.xml

Class XmlWriter

  • 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 final class XmlWriter
extends org.xml.sax.helpers.XMLFilterImpl
    XML writer doing the opposite work of a SAX-based XML reader. The implementation is based on the work of David Megginson, the creator of SAX who placed the original code in the public domain.

    This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XmlWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

    The client creates a document by invoking the methods for standard SAX2 events, always beginning with the startDocument method and ending with the endDocument method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

     w.startElement("foo");

    is equivalent to the regular SAX2 ContentHandler method 

     w.startElement("", "foo", "", new AttributesImpl());

    Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

     XmlWriter w = new XmlWriter();
 
 w.startDocument();
 w.startElement("greeting");
 w.characters("Hello, world!");
 w.endElement("greeting");
 w.endDocument();

    The resulting document will look like this: 

               <?xml version="1.0" standalone='yes'?>
          
           <greeting>Hello, world!</greeting>

    In fact, there is an even simpler convenience method, dataElement, designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

     XmlWriter w = new XmlWriter();
 
 w.startDocument();
 w.dataElement("greeting", "Hello, world!");
 w.endDocument();

    Whitespace

    According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

     w.dataElement("item", "1");
 w.dataElement("item", "2");
 w.dataElement("item", "3");

    you will end up with 

               <item>1</item><item>3</item><item>3</item>

    You need to invoke one of the characters methods explicitly to add newlines or indentation. Alternatively, you can use the data format mode (set the "dataFormat" property) which is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly). See details below.

    Namespace Support

    The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

     w.startDocument();
 w.emptyElement("http://www.foo.com/ns/", "foo");
 w.endDocument();

    The resulting document will look like this: 

               <?xml version="1.0" standalone='yes'?>
          
           <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

    In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

    1. the qualified name
    2. the setPrefix method.

    Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

    Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

     w.setPrefix("http://www.foo.com/ns/", "foo");
 w.startDocument();
 w.emptyElement("http://www.foo.com/ns/", "foo");
 w.endDocument();

    The resulting document will look like this: 

               <?xml version="1.0" standalone='yes'?>
          
           <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

    The default Namespace simply uses an empty string as the prefix: 

     w.setPrefix("http://www.foo.com/ns/", "");
 w.startDocument();
 w.emptyElement("http://www.foo.com/ns/", "foo");
 w.endDocument();

    The resulting document will look like this: 

               <?xml version="1.0" standalone='yes'?>
          
           <foo xmlns="http://www.foo.com/ns/"/>

    By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

               <xml version="1.0" standalone='yes'?>
          
           <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
            <rdf:Description about="http://www.foo.com/ids/books/12345">
             <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
             <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
             <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
            </rdf:Description>
           </rdf:RDF>

    The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

     w.forceNSDecl("http://www.purl.org/dc/");

    Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

               <xml version="1.0" standalone='yes'?>
          
           <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                       xmlns:dc="http://www.purl.org/dc/">
            <rdf:Description about="http://www.foo.com/ids/books/12345">
             <dc:title>A Dark Night</dc:title>
             <dc:creator>Jane Smith</dc:title>
             <dc:date>2000-09-09</dc:title>
            </rdf:Description>
           </rdf:RDF>

    This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

    Data Format

    This mode, enabled by the "dataFormat" property, 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 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 mode 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: 

     XmlWriter w = new XmlWriter();
 w.setDataFormat(true);
 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>
    See Also:
    XMLFilter, ContentHandler

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private boolean dataFormat  
      private int depth  
      private java.util.Map<java.lang.String,​java.lang.String> doneDeclTable
      The document declarations table.
      private int elementLevel
      The element level.
      private org.xml.sax.Attributes EMPTY_ATTS
      Constant representing empty attributes.
      private java.util.Map<java.lang.String,​java.lang.Boolean> forcedDeclTable
      The forced declarations table.
      private int indentStep  
      private org.xml.sax.helpers.NamespaceSupport nsSupport
      The namespace support.
      private java.io.Writer output
      The underlying writer.
      private int prefixCounter
      The prefix counter.
      private java.util.Map<java.lang.String,​java.lang.String> prefixTable
      The prefixes table.
      private static java.lang.Object SEEN_DATA  
      private static java.lang.Object SEEN_ELEMENT  
      private static java.lang.Object SEEN_NOTHING  
      private java.lang.Object state  
      private java.util.Stack<java.lang.Object> stateStack  

    • Constructor Summary

      Constructors 
      Constructor Description
      XmlWriter()
      Create a new XML writer.
      XmlWriter​(java.io.OutputStream out)
      Constructor.
      XmlWriter​(java.io.OutputStream out, java.lang.String charsetName)
      Constructor.
      XmlWriter​(java.io.OutputStream out, java.nio.charset.Charset cs)
      Constructor.
      XmlWriter​(java.io.OutputStream out, java.nio.charset.CharsetEncoder enc)
      Constructor.
      XmlWriter​(java.io.Writer writer)
      Create a new XML writer.
      XmlWriter​(org.xml.sax.XMLReader xmlreader)
      Create a new XML writer.
      XmlWriter​(org.xml.sax.XMLReader xmlreader, java.io.Writer writer)
      Create a new XML writer.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void characters​(boolean dataFormat, char[] ch, int start, int len)
      Write character data.
      private void characters​(boolean dataFormat, java.lang.String data)
      Write a string of character data, with XML escaping.
      void characters​(char[] ch, int start, int len)
      Write character data.
      void characters​(java.lang.String data)
      Write a string of character data, with XML escaping.
      void dataElement​(java.lang.String localName, java.lang.String content)
      Write an element with character data content but no attributes or Namespace URI.
      void dataElement​(java.lang.String uri, java.lang.String localName, java.lang.String content)
      Write an element with character data content but no attributes.
      void dataElement​(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts, java.lang.String content)
      Write an element with character data content.
      private void doIndent()
      Print indentation for the current level.
      private java.lang.String doPrefix​(java.lang.String uri, java.lang.String qName, boolean isElement)
      Determine the prefix for an element or attribute name.
      void emptyElement​(java.lang.String localName)
      Add an empty element without a Namespace URI, qname or attributes.
      void emptyElement​(java.lang.String uri, java.lang.String localName)
      Add an empty element without a qname or attributes.
      void emptyElement​(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)
      Write an empty element.
      void endDocument()
      Write a newline at the end of the document.
      void endElement​(java.lang.String localName)
      End an element without a Namespace URI or qname.
      void endElement​(java.lang.String uri, java.lang.String localName)
      End an element without a qname.
      void endElement​(java.lang.String uri, java.lang.String localName, java.lang.String qName)
      Write an end tag.
      void flush()
      Flush the output.
      void forceNSDecl​(java.lang.String uri)
      Force a Namespace to be declared on the root element.
      void forceNSDecl​(java.lang.String uri, java.lang.String prefix)
      Force a Namespace declaration with a preferred prefix.
      private void forceNSDecls()
      Force all Namespaces to be declared.
      int getIndentStep()
      Return the current indent step.
      java.lang.String getPrefix​(java.lang.String uri)
      Get the current or preferred prefix for a Namespace URI.
      java.io.Writer getWriter()
      Returns the underlying writer.
      void ignorableWhitespace​(char[] ch, int start, int length)
      Write ignorable whitespace.
      private void init​(java.io.Writer writer)
      Internal initialization method.
      boolean isDataFormat()  
      void processingInstruction​(java.lang.String target, java.lang.String data)
      Write a processing instruction.
      void reset()
      Reset the writer.
      void setDataFormat​(boolean dataFormat)  
      void setIndentStep​(int indentStep)
      Set the current indent step.
      void setOutput​(java.io.Writer writer)
      Set a new output destination for the document.
      void setPrefix​(java.lang.String uri, java.lang.String prefix)
      Specify a preferred prefix for a Namespace URI.
      void startDocument()
      Write the XML declaration at the beginning of the document.
      void startElement​(java.lang.String localName)
      Start a new element without a qname, attributes or a Namespace URI.
      void startElement​(java.lang.String uri, java.lang.String localName)
      Start a new element without a qname or attributes.
      void startElement​(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)
      Write a start tag.
      private void write​(char c)
      Write a raw character.
      private void write​(java.lang.String s)
      Write a raw string.
      private void writeAttributes​(org.xml.sax.Attributes atts)
      Write out an attribute list, escaping values.
      private void writeEsc​(char[] ch, int start, int length, boolean isAttVal)
      Write an array of data characters with escaping.
      private void writeName​(java.lang.String uri, java.lang.String localName, java.lang.String qName, boolean isElement)
      Write an element or attribute name.
      private void writeNSDecls()
      Write out the list of Namespace declarations.

      • 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

    • Field Detail

      • SEEN_DATA

        private static final java.lang.Object SEEN_DATA

      • SEEN_ELEMENT

        private static final java.lang.Object SEEN_ELEMENT

      • SEEN_NOTHING

        private static final java.lang.Object SEEN_NOTHING

      • dataFormat

        private volatile boolean dataFormat

      • depth

        private volatile int depth

      • doneDeclTable

        private volatile java.util.Map<java.lang.String,​java.lang.String> doneDeclTable
        The document declarations table.

      • elementLevel

        private volatile int elementLevel
        The element level.

      • EMPTY_ATTS

        private final org.xml.sax.Attributes EMPTY_ATTS
        Constant representing empty attributes.

      • forcedDeclTable

        private volatile java.util.Map<java.lang.String,​java.lang.Boolean> forcedDeclTable
        The forced declarations table.

      • indentStep

        private volatile int indentStep

      • nsSupport

        private volatile org.xml.sax.helpers.NamespaceSupport nsSupport
        The namespace support.

      • output

        private volatile java.io.Writer output
        The underlying writer.

      • prefixCounter

        private volatile int prefixCounter
        The prefix counter.

      • prefixTable

        private volatile java.util.Map<java.lang.String,​java.lang.String> prefixTable
        The prefixes table.

      • state

        private volatile java.lang.Object state

      • stateStack

        private volatile java.util.Stack<java.lang.Object> stateStack

    • Constructor Detail

      • XmlWriter

        public XmlWriter()
        Create a new XML writer.

        Write to standard output.

      • XmlWriter

        public XmlWriter​(java.io.OutputStream out)
        Constructor.
        Parameters:
        out - The underlying output stream.

      • XmlWriter

        public XmlWriter​(java.io.OutputStream out,
                 java.nio.charset.Charset cs)
        Constructor.
        Parameters:
        out - The underlying output stream.

      • XmlWriter

        public XmlWriter​(java.io.OutputStream out,
                 java.nio.charset.CharsetEncoder enc)
        Constructor.
        Parameters:
        out - The underlying output stream.

      • XmlWriter

        public XmlWriter​(java.io.OutputStream out,
                 java.lang.String charsetName)
          throws java.io.UnsupportedEncodingException
        Constructor.
        Parameters:
        out - The underlying output stream.
        Throws:
        java.io.UnsupportedEncodingException

      • XmlWriter

        public XmlWriter​(java.io.Writer writer)
        Create a new XML writer.

        Write to the writer provided.

        Parameters:
        writer - The output destination, or null to use standard output.

      • XmlWriter

        public XmlWriter​(org.xml.sax.XMLReader xmlreader)
        Create a new XML writer.

        Use the specified XML reader as the parent.

        Parameters:
        xmlreader - The parent in the filter chain, or null for no parent.

      • XmlWriter

        public XmlWriter​(org.xml.sax.XMLReader xmlreader,
                 java.io.Writer writer)
        Create a new XML writer.

        Use the specified XML reader as the parent, and write to the specified writer.

        Parameters:
        xmlreader - The parent in the filter chain, or null for no parent.
        writer - The output destination, or null to use standard output.

    • Method Detail

      • characters

        private void characters​(boolean dataFormat,
                        char[] ch,
                        int start,
                        int len)
                 throws org.xml.sax.SAXException
        Write character data. Pass the event on down the filter chain for further processing.
        Parameters:
        ch - The array of characters to write.
        start - The starting position in the array.
        len - The number of characters to write.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the characters, or if a restlet further down the filter chain raises an exception.
        See Also:
        ContentHandler.characters(char[], int, int)

      • characters

        private void characters​(boolean dataFormat,
                        java.lang.String data)
                 throws org.xml.sax.SAXException
        Write a string of character data, with XML escaping.

        This is a convenience method that takes an XML String, converts it to a character array, then invokes characters(char[], int, int).

        Parameters:
        data - The character data.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the string, or if a restlet further down the filter chain raises an exception.
        See Also:
        characters(char[], int, int)

      • characters

        public void characters​(char[] ch,
                       int start,
                       int len)
                throws org.xml.sax.SAXException
        Write character data. Pass the event on down the filter chain for further processing.
        Specified by:
        characters in interface org.xml.sax.ContentHandler
        Overrides:
        characters in class org.xml.sax.helpers.XMLFilterImpl
        Parameters:
        ch - The array of characters to write.
        start - The starting position in the array.
        len - The number of characters to write.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the characters, or if a restlet further down the filter chain raises an exception.
        See Also:
        ContentHandler.characters(char[], int, int)

      • characters

        public void characters​(java.lang.String data)
                throws org.xml.sax.SAXException
        Write a string of character data, with XML escaping.

        This is a convenience method that takes an XML String, converts it to a character array, then invokes characters(char[], int, int).

        Parameters:
        data - The character data.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the string, or if a restlet further down the filter chain raises an exception.
        See Also:
        characters(char[], int, int)

      • doIndent

        private void doIndent()
               throws org.xml.sax.SAXException
        Print indentation for the current level.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the indentation characters, or if a filter further down the chain raises an exception.

      • doPrefix

        private java.lang.String doPrefix​(java.lang.String uri,
                                  java.lang.String qName,
                                  boolean isElement)
        Determine the prefix for an element or attribute name. TODO: this method probably needs some cleanup.
        Parameters:
        uri - The Namespace URI.
        qName - The qualified name (optional); this will be used to indicate the preferred prefix if none is currently bound.
        isElement - true if this is an element name, false if it is an attribute name (which cannot use the default Namespace).

      • emptyElement

        public void emptyElement​(java.lang.String localName)
                  throws org.xml.sax.SAXException
        Add an empty element without a Namespace URI, qname or attributes.

        This method will supply an empty string for the qname, and empty string for the Namespace URI, and an empty attribute list. It invokes emptyElement(String, String, String, Attributes) directly.

        Parameters:
        localName - The element's local name.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the empty tag, or if a restlet further down the filter chain raises an exception.
        See Also:
        emptyElement(String, String, String, Attributes)

      • emptyElement

        public void emptyElement​(java.lang.String uri,
                         java.lang.String localName)
                  throws org.xml.sax.SAXException
        Add an empty element without a qname or attributes.

        This method will supply an empty string for the qname and an empty attribute list. It invokes emptyElement(String, String, String, Attributes) directly.

        Parameters:
        uri - The element's Namespace URI.
        localName - The element's local name.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the empty tag, or if a restlet further down the filter chain raises an exception.
        See Also:
        emptyElement(String, String, String, Attributes)

      • 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 an empty element. This method writes an empty element tag rather than a start tag followed by an end tag. Both a startElement and an endElement event will be passed on down the filter chain.
        Parameters:
        uri - The element's Namespace URI, or the empty string if the element has no Namespace or if Namespace processing is not being performed.
        localName - The element's local name (without prefix). This parameter must be provided.
        qName - The element's qualified name (with prefix), or the empty string if none is available. This parameter is strictly advisory: the writer may or may not use the prefix attached.
        atts - The element's attribute list.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the empty tag, or if a restlet further down the filter chain raises an exception.
        See Also:
        startElement(java.lang.String), endElement(java.lang.String)

      • endDocument

        public void endDocument()
                 throws org.xml.sax.SAXException
        Write a newline at the end of the document. Pass the event on down the filter chain for further processing.
        Specified by:
        endDocument in interface org.xml.sax.ContentHandler
        Overrides:
        endDocument in class org.xml.sax.helpers.XMLFilterImpl
        Throws:
        org.xml.sax.SAXException - If there is an error writing the newline, or if a restlet further down the filter chain raises an exception.
        See Also:
        ContentHandler.endDocument()

      • endElement

        public void endElement​(java.lang.String localName)
                throws org.xml.sax.SAXException
        End an element without a Namespace URI or qname.

        This method will supply an empty string for the qName and an empty string for the Namespace URI. It invokes endElement(String, String, String) directly.

        Parameters:
        localName - The element's local name.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the end tag, or if a restlet further down the filter chain raises an exception.
        See Also:
        endElement(String, String, String)

      • endElement

        public void endElement​(java.lang.String uri,
                       java.lang.String localName)
                throws org.xml.sax.SAXException
        End an element without a qname.

        This method will supply an empty string for the qName. It invokes endElement(String, String, String) directly.

        Parameters:
        uri - The element's Namespace URI.
        localName - The element's local name.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the end tag, or if a restlet further down the filter chain raises an exception.
        See Also:
        endElement(String, String, String)

      • 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. Pass the event on down the filter chain for further processing.
        Specified by:
        endElement in interface org.xml.sax.ContentHandler
        Overrides:
        endElement in class org.xml.sax.helpers.XMLFilterImpl
        Parameters:
        uri - The Namespace URI, or the empty string if none is available.
        localName - The element's local (unprefixed) name (required).
        qName - The element's qualified (prefixed) name, or the empty string is none is available. This method will use the qName as a template for generating a prefix if necessary, but it is not guaranteed to use the same qName.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the end tag, or if a restlet further down the filter chain raises an exception.
        See Also:
        ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)

      • flush

        public void flush()
           throws java.io.IOException
        Flush the output.

        This method flushes the output stream. It is especially useful when you need to make certain that the entire document has been written to output but do not want to close the output stream.

        This method is invoked automatically by the endDocument method after writing a document.

        Throws:
        java.io.IOException
        See Also:
        reset()

      • forceNSDecl

        public void forceNSDecl​(java.lang.String uri)
        Force a Namespace to be declared on the root element.

        By default, the XMLWriter will declare only the Namespaces needed for an element; as a result, a Namespace may be declared many places in a document if it is not used on the root element.

        This method forces a Namespace to be declared on the root element even if it is not used there, and reduces the number of xmlns attributes in the document.

        Parameters:
        uri - The Namespace URI to declare.
        See Also:
        forceNSDecl(java.lang.String,java.lang.String), setPrefix(java.lang.String, java.lang.String)

      • forceNSDecls

        private void forceNSDecls()
        Force all Namespaces to be declared. This method is used on the root element to ensure that the predeclared Namespaces all appear.

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

      • getPrefix

        public java.lang.String getPrefix​(java.lang.String uri)
        Get the current or preferred prefix for a Namespace URI.
        Parameters:
        uri - The Namespace URI.
        Returns:
        The preferred prefix, or "" for the default Namespace.
        See Also:
        setPrefix(java.lang.String, java.lang.String)

      • getWriter

        public java.io.Writer getWriter()
        Returns the underlying writer.
        Returns:
        The underlying writer.

      • ignorableWhitespace

        public void ignorableWhitespace​(char[] ch,
                                int start,
                                int length)
                         throws org.xml.sax.SAXException
        Write ignorable whitespace. Pass the event on down the filter chain for further processing.
        Specified by:
        ignorableWhitespace in interface org.xml.sax.ContentHandler
        Overrides:
        ignorableWhitespace in class org.xml.sax.helpers.XMLFilterImpl
        Parameters:
        ch - The array of characters to write.
        start - The starting position in the array.
        length - The number of characters to write.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the whitespace, or if a restlet further down the filter chain raises an exception.
        See Also:
        ContentHandler.ignorableWhitespace(char[], int, int)

      • init

        private void init​(java.io.Writer writer)
        Internal initialization method.

        All of the public constructors invoke this method.

        Parameters:
        writer - The output destination, or null to use standard output.

      • isDataFormat

        public boolean isDataFormat()

      • processingInstruction

        public void processingInstruction​(java.lang.String target,
                                  java.lang.String data)
                           throws org.xml.sax.SAXException
        Write a processing instruction. Pass the event on down the filter chain for further processing.
        Specified by:
        processingInstruction in interface org.xml.sax.ContentHandler
        Overrides:
        processingInstruction in class org.xml.sax.helpers.XMLFilterImpl
        Parameters:
        target - The PI target.
        data - The PI data.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the PI, or if a restlet further down the filter chain raises an exception.
        See Also:
        ContentHandler.processingInstruction(java.lang.String, java.lang.String)

      • reset

        public void reset()
        Reset the writer.

        This method is especially useful if the writer throws an exception before it is finished, and you want to reuse the writer for a new document. It is usually a good idea to invoke flush before resetting the writer, to make sure that no output is lost.

        This method is invoked automatically by the startDocument method before writing a new document.

        Note: this method will not clear the prefix or URI information in the writer or the selected output writer.

        See Also:
        flush()

      • setDataFormat

        public void setDataFormat​(boolean dataFormat)

      • setIndentStep

        public void setIndentStep​(int indentStep)
        Set the current indent step.
        Parameters:
        indentStep - The new indent step (0 or less for no indentation).

      • setOutput

        public void setOutput​(java.io.Writer writer)
        Set a new output destination for the document.
        Parameters:
        writer - The output destination, or null to use standard output.
        See Also:
        flush()

      • startDocument

        public void startDocument()
                   throws org.xml.sax.SAXException
        Write the XML declaration at the beginning of the document. Pass the event on down the filter chain for further processing.
        Specified by:
        startDocument in interface org.xml.sax.ContentHandler
        Overrides:
        startDocument in class org.xml.sax.helpers.XMLFilterImpl
        Throws:
        org.xml.sax.SAXException - If there is an error writing the XML declaration, or if a restlet further down the filter chain raises an exception.
        See Also:
        ContentHandler.startDocument()

      • startElement

        public void startElement​(java.lang.String localName)
                  throws org.xml.sax.SAXException
        Start a new element without a qname, attributes or a Namespace URI.

        This method will provide an empty string for the Namespace URI, and empty string for the qualified name, and a default empty attribute list. It invokes #startElement(String, String, String, Attributes)} directly.

        Parameters:
        localName - The element's local name.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the start tag, or if a restlet further down the filter chain raises an exception.
        See Also:
        startElement(String, String, String, Attributes)

      • startElement

        public void startElement​(java.lang.String uri,
                         java.lang.String localName)
                  throws org.xml.sax.SAXException
        Start a new element without a qname or attributes.

        This method will provide a default empty attribute list and an empty string for the qualified name. It invokes startElement(String, String, String, Attributes) directly.

        Parameters:
        uri - The element's Namespace URI.
        localName - The element's local name.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the start tag, or if a restlet further down the filter chain raises an exception.
        See Also:
        startElement(String, String, String, Attributes)

      • 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. Pass the event on down the filter chain for further processing.
        Specified by:
        startElement in interface org.xml.sax.ContentHandler
        Overrides:
        startElement in class org.xml.sax.helpers.XMLFilterImpl
        Parameters:
        uri - The Namespace URI, or the empty string if none is available.
        localName - The element's local (unprefixed) name (required).
        qName - The element's qualified (prefixed) name, or the empty string is none is available. This method will use the qName as a template for generating a prefix if necessary, but it is not guaranteed to use the same qName.
        atts - The element's attribute list (must not be null).
        Throws:
        org.xml.sax.SAXException - If there is an error writing the start tag, or if a restlet further down the filter chain raises an exception.
        See Also:
        ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

      • write

        private void write​(char c)
            throws org.xml.sax.SAXException
        Write a raw character.
        Parameters:
        c - The character to write.
        Throws:
        org.xml.sax.SAXException - If there is an error writing the character, this method will throw an IOException wrapped in a SAXException.

      • write

        private void write​(java.lang.String s)
            throws org.xml.sax.SAXException
        Write a raw string.
        Parameters:
        s -
        Throws:
        org.xml.sax.SAXException - If there is an error writing the string, this method will throw an IOException wrapped in a SAXException

      • writeAttributes

        private void writeAttributes​(org.xml.sax.Attributes atts)
                      throws org.xml.sax.SAXException
        Write out an attribute list, escaping values. The names will have prefixes added to them.
        Parameters:
        atts - The attribute list to write.
        Throws:
        org.xml.SAXException - If there is an error writing the attribute list, this method will throw an IOException wrapped in a SAXException.
        org.xml.sax.SAXException

      • writeEsc

        private void writeEsc​(char[] ch,
                      int start,
                      int length,
                      boolean isAttVal)
               throws org.xml.sax.SAXException
        Write an array of data characters with escaping.
        Parameters:
        ch - The array of characters.
        start - The starting position.
        length - The number of characters to use.
        isAttVal - true if this is an attribute value literal.
        Throws:
        org.xml.SAXException - If there is an error writing the characters, this method will throw an IOException wrapped in a SAXException.
        org.xml.sax.SAXException

      • writeName

        private void writeName​(java.lang.String uri,
                       java.lang.String localName,
                       java.lang.String qName,
                       boolean isElement)
                throws org.xml.sax.SAXException
        Write an element or attribute name.
        Parameters:
        uri - The Namespace URI.
        localName - The local name.
        qName - The prefixed name, if available, or the empty string.
        isElement - true if this is an element name, false if it is an attribute name.
        Throws:
        org.xml.sax.SAXException - This method will throw an IOException wrapped in a SAXException if there is an error writing the name.

      • writeNSDecls

        private void writeNSDecls()
                   throws org.xml.sax.SAXException
        Write out the list of Namespace declarations.
        Throws:
        org.xml.sax.SAXException - This method will throw an IOException wrapped in a SAXException if there is an error writing the Namespace declarations.