Class XmlWriter

  • Direct Known Subclasses:
    BufferingXmlWriter, EncodingXmlWriter

    public abstract class XmlWriter
    extends java.lang.Object
    This is the base class for actual physical xml outputters. These instances will only handle actual writing (possibly including encoding) of the serialized textual xml, and will in general not verify content being output. The exception are the character-by-character checks that are most efficiently done at encoding level (such as character escaping, and checks for illegal character combinations), which are handled at this level.

    Note that implementations can have different operating modes: specifically, when dealing with illegal content (such as "--" in a comment, "?>" in processing instruction, or "]]>" within CDATA section), implementations can do one of 3 things:

    • Fix the problem, by splitting the section (which can be done for CDATA sections, and to some degree, comments)
    • Stop outputting, and return an index to the illegal piece of data (if there is no easy way to fix the problem: for example, for processing instruction)
    • Just output content even though it will not result in well-formed output. This should only be done if the calling application has specifically requested verifications to be disabled.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static char DEFAULT_QUOTE_CHAR  
      (package private) boolean mAddSpaceAfterEmptyElem
      Whether to add a space after empty element (before closing "/>") or not.
      protected java.io.Writer mAttrValueWriter
      Optional escaping writer used for escaping characters like '"' '&' and '<' in attribute values.
      protected boolean mAutoCloseOutput
      Flag that defines whether close() on this writer should call close on the underlying output object (stream, writer)
      protected boolean mCheckContent  
      protected boolean mCheckNames  
      protected boolean mCheckStructure  
      protected WriterConfig mConfig  
      protected java.lang.String mEncoding  
      (package private) boolean mEscapeCR
      Whether to escape CR (\r) character.
      protected boolean mFixContent  
      protected int mLocPastChars
      Number of characters output prior to currently buffered output
      protected int mLocRowNr  
      protected int mLocRowStartOffset
      Offset of the first character on this line.
      protected boolean mNsAware  
      protected XmlWriterWrapper mRawWrapper
      Lazy-constructed wrapper object, which will route all calls to Writer API, to matching writeRaw methods of this XmlWriter instance.
      protected XmlWriterWrapper mTextWrapper
      Lazy-constructed wrapper object, which will route all calls to Writer API, to matching writeCharacters methods of this XmlWriter instance.
      protected java.io.Writer mTextWriter
      Optional escaping writer used for escaping characters like '<' '&' and '>' in textual content.
      (package private) boolean mUseDoubleQuotesInXmlDecl
      Whether to use double quotes in XML declaration or not.
      protected boolean mXml11
      Indicates whether output is to be compliant; if false, is to be xml 1.0 compliant, if true, xml 1.1 compliant.
      protected static int SURR1_FIRST  
      protected static int SURR1_LAST  
      protected static int SURR2_FIRST  
      protected static int SURR2_LAST  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected XmlWriter​(WriterConfig cfg, java.lang.String encoding, boolean autoclose)  
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract void close​(boolean forceRealClose)
      Method called to flush the buffer(s), and close the output sink (stream or writer) if enabled (auto-closing) or forced.
      void enableXml11()  
      abstract void flush()  
      int getAbsOffset()  
      int getColumn()  
      protected abstract int getOutputPtr()  
      protected abstract java.io.OutputStream getOutputStream()  
      int getRow()  
      protected abstract java.io.Writer getWriter()  
      protected char handleInvalidChar​(int c)
      Method called to handle invalid character in textual content requested to be output.
      protected void reportNwfContent​(java.lang.String msg)  
      protected void reportNwfName​(java.lang.String msg)
      This is the method called when an output method call violates name well-formedness checks and WstxOutputProperties.P_OUTPUT_VALIDATE_NAMES is is enabled.
      protected void throwOutputError​(java.lang.String msg)  
      protected void throwOutputError​(java.lang.String format, java.lang.Object arg)  
      void verifyNameValidity​(java.lang.String name, boolean checkNs)
      Method called to verify that the name is a legal XML name.
      java.io.Writer wrapAsRawWriter()
      Method that can be called to get a wrapper instance that can be used to essentially call the writeRaw method.
      java.io.Writer wrapAsTextWriter()  
      abstract void writeAttribute​(java.lang.String localName, char[] value, int offset, int len)  
      abstract void writeAttribute​(java.lang.String localName, java.lang.String value)
      Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)
      abstract void writeAttribute​(java.lang.String prefix, java.lang.String localName, char[] value, int offset, int len)  
      abstract void writeAttribute​(java.lang.String prefix, java.lang.String localName, java.lang.String value)
      Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)
      abstract int writeCData​(char[] cbuf, int offset, int len)  
      abstract int writeCData​(java.lang.String data)  
      abstract void writeCDataEnd()  
      abstract void writeCDataStart()  
      abstract void writeCharacters​(char[] cbuf, int offset, int len)  
      abstract void writeCharacters​(java.lang.String data)  
      abstract int writeComment​(java.lang.String data)
      Method that will try to output the content as specified.
      abstract void writeCommentEnd()  
      abstract void writeCommentStart()  
      abstract void writeDTD​(java.lang.String data)
      Older "legacy" output method for outputting DOCTYPE declaration.
      abstract void writeDTD​(java.lang.String rootName, java.lang.String systemId, java.lang.String publicId, java.lang.String internalSubset)  
      abstract void writeEndTag​(java.lang.String localName)  
      abstract void writeEndTag​(java.lang.String prefix, java.lang.String localName)  
      abstract void writeEntityReference​(java.lang.String name)  
      abstract int writePI​(java.lang.String target, java.lang.String data)  
      abstract void writePIEnd()  
      abstract void writePIStart​(java.lang.String target, boolean addSpace)  
      abstract void writeRaw​(char[] cbuf, int offset, int len)  
      void writeRaw​(java.lang.String str)  
      abstract void writeRaw​(java.lang.String str, int offset, int len)  
      abstract void writeRawAscii​(char[] cbuf, int offset, int len)
      Like writeRaw(java.lang.String, int, int), but caller guarantees that the contents additionally are known to be in 7-bit ascii range.
      abstract void writeStartTagEmptyEnd()  
      abstract void writeStartTagEnd()  
      abstract void writeStartTagStart​(java.lang.String localName)
      Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)
      abstract void writeStartTagStart​(java.lang.String prefix, java.lang.String localName)
      Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)
      abstract void writeTypedAttribute​(java.lang.String prefix, java.lang.String localName, java.lang.String nsURI, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc, org.codehaus.stax2.validation.XMLValidator validator, char[] copyBuffer)
      Method similar to writeAttribute(String,String,char[],int,int) but where is known not to require escaping.
      abstract void writeTypedAttribute​(java.lang.String prefix, java.lang.String localName, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
      Method similar to writeAttribute(String,String,char[],int,int) but where is known not to require escaping.
      abstract void writeTypedAttribute​(java.lang.String localName, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
      Method similar to writeAttribute(String,String,char[],int,int) but where is known not to require escaping.
      abstract void writeTypedElement​(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
      Like writeRaw(java.lang.String, int, int), but caller guarantees that the contents additionally are known to be in 7-bit ascii range, and also passes an encoder object that will encode values only when being handed a buffer to append to.
      abstract void writeTypedElement​(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc, org.codehaus.stax2.validation.XMLValidator validator, char[] copyBuffer)
      Like writeRaw(java.lang.String, int, int), but caller guarantees that the contents additionally are known to be in 7-bit ascii range, and also passes an encoder object that will encode values only when being handed a buffer to append to.
      abstract void writeXmlDeclaration​(java.lang.String version, java.lang.String enc, java.lang.String standalone)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • mEncoding

        protected final java.lang.String mEncoding
      • mNsAware

        protected final boolean mNsAware
      • mCheckStructure

        protected final boolean mCheckStructure
      • mCheckContent

        protected final boolean mCheckContent
      • mCheckNames

        protected final boolean mCheckNames
      • mFixContent

        protected final boolean mFixContent
      • mEscapeCR

        final boolean mEscapeCR
        Whether to escape CR (\r) character.
      • mAddSpaceAfterEmptyElem

        final boolean mAddSpaceAfterEmptyElem
        Whether to add a space after empty element (before closing "/>") or not.
      • mUseDoubleQuotesInXmlDecl

        final boolean mUseDoubleQuotesInXmlDecl
        Whether to use double quotes in XML declaration or not.
      • mAutoCloseOutput

        protected final boolean mAutoCloseOutput
        Flag that defines whether close() on this writer should call close on the underlying output object (stream, writer)
      • mTextWriter

        protected java.io.Writer mTextWriter
        Optional escaping writer used for escaping characters like '<' '&' and '>' in textual content. Constructed if calling code has installed a special escaping writer factory for text content. Null if the default escaper is to be used.
      • mAttrValueWriter

        protected java.io.Writer mAttrValueWriter
        Optional escaping writer used for escaping characters like '"' '&' and '<' in attribute values. Constructed if calling code has installed a special escaping writer factory for text content. Null if the default escaper is to be used.
      • mXml11

        protected boolean mXml11
        Indicates whether output is to be compliant; if false, is to be xml 1.0 compliant, if true, xml 1.1 compliant.
      • mRawWrapper

        protected XmlWriterWrapper mRawWrapper
        Lazy-constructed wrapper object, which will route all calls to Writer API, to matching writeRaw methods of this XmlWriter instance.
      • mTextWrapper

        protected XmlWriterWrapper mTextWrapper
        Lazy-constructed wrapper object, which will route all calls to Writer API, to matching writeCharacters methods of this XmlWriter instance.
      • mLocPastChars

        protected int mLocPastChars
        Number of characters output prior to currently buffered output
      • mLocRowNr

        protected int mLocRowNr
      • mLocRowStartOffset

        protected int mLocRowStartOffset
        Offset of the first character on this line. May be negative, if the offset was in a buffer that has been flushed out.
    • Constructor Detail

      • XmlWriter

        protected XmlWriter​(WriterConfig cfg,
                            java.lang.String encoding,
                            boolean autoclose)
                     throws java.io.IOException
        Throws:
        java.io.IOException
    • Method Detail

      • enableXml11

        public void enableXml11()
      • getOutputStream

        protected abstract java.io.OutputStream getOutputStream()
        Returns:
        Underlying OutputStream used for physical output, if the writer was constructed using one
      • getWriter

        protected abstract java.io.Writer getWriter()
        Returns:
        Underlying Writer used for physical output, if the writer was constructed with one, or one was created to be used with an OutputStream.
      • close

        public abstract void close​(boolean forceRealClose)
                            throws java.io.IOException
        Method called to flush the buffer(s), and close the output sink (stream or writer) if enabled (auto-closing) or forced.
        Throws:
        java.io.IOException
      • flush

        public abstract void flush()
                            throws java.io.IOException
        Throws:
        java.io.IOException
      • writeRaw

        public abstract void writeRaw​(java.lang.String str,
                                      int offset,
                                      int len)
                               throws java.io.IOException
        Throws:
        java.io.IOException
      • writeRaw

        public void writeRaw​(java.lang.String str)
                      throws java.io.IOException
        Throws:
        java.io.IOException
      • writeRaw

        public abstract void writeRaw​(char[] cbuf,
                                      int offset,
                                      int len)
                               throws java.io.IOException
        Throws:
        java.io.IOException
      • writeRawAscii

        public abstract void writeRawAscii​(char[] cbuf,
                                           int offset,
                                           int len)
                                    throws java.io.IOException
        Like writeRaw(java.lang.String, int, int), but caller guarantees that the contents additionally are known to be in 7-bit ascii range.
        Throws:
        java.io.IOException
      • writeCDataStart

        public abstract void writeCDataStart()
                                      throws java.io.IOException
        Throws:
        java.io.IOException
      • writeCDataEnd

        public abstract void writeCDataEnd()
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • writeCommentStart

        public abstract void writeCommentStart()
                                        throws java.io.IOException
        Throws:
        java.io.IOException
      • writeCommentEnd

        public abstract void writeCommentEnd()
                                      throws java.io.IOException
        Throws:
        java.io.IOException
      • writePIStart

        public abstract void writePIStart​(java.lang.String target,
                                          boolean addSpace)
                                   throws java.io.IOException
        Throws:
        java.io.IOException
      • writePIEnd

        public abstract void writePIEnd()
                                 throws java.io.IOException
        Throws:
        java.io.IOException
      • writeCData

        public abstract int writeCData​(java.lang.String data)
                                throws java.io.IOException,
                                       javax.xml.stream.XMLStreamException
        Parameters:
        data - Contents of the CDATA section to write out
        Returns:
        offset of the (first) illegal content segment ("]]>") in passed content and not in repairing mode; or -1 if none or is repairing
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeCData

        public abstract int writeCData​(char[] cbuf,
                                       int offset,
                                       int len)
                                throws java.io.IOException,
                                       javax.xml.stream.XMLStreamException
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeCharacters

        public abstract void writeCharacters​(java.lang.String data)
                                      throws java.io.IOException
        Throws:
        java.io.IOException
      • writeCharacters

        public abstract void writeCharacters​(char[] cbuf,
                                             int offset,
                                             int len)
                                      throws java.io.IOException
        Throws:
        java.io.IOException
      • writeComment

        public abstract int writeComment​(java.lang.String data)
                                  throws java.io.IOException,
                                         javax.xml.stream.XMLStreamException
        Method that will try to output the content as specified. If the content passed in has embedded "--" in it, it will either add an intervening space between consequtive hyphens (if content fixing is enabled), or return the offset of the first hyphen in multi-hyphen sequence.
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeDTD

        public abstract void writeDTD​(java.lang.String data)
                               throws java.io.IOException,
                                      javax.xml.stream.XMLStreamException
        Older "legacy" output method for outputting DOCTYPE declaration. Assumes that the passed-in String contains a complete DOCTYPE declaration properly quoted.
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeDTD

        public abstract void writeDTD​(java.lang.String rootName,
                                      java.lang.String systemId,
                                      java.lang.String publicId,
                                      java.lang.String internalSubset)
                               throws java.io.IOException,
                                      javax.xml.stream.XMLStreamException
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeEntityReference

        public abstract void writeEntityReference​(java.lang.String name)
                                           throws java.io.IOException,
                                                  javax.xml.stream.XMLStreamException
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writePI

        public abstract int writePI​(java.lang.String target,
                                    java.lang.String data)
                             throws java.io.IOException,
                                    javax.xml.stream.XMLStreamException
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeXmlDeclaration

        public abstract void writeXmlDeclaration​(java.lang.String version,
                                                 java.lang.String enc,
                                                 java.lang.String standalone)
                                          throws java.io.IOException
        Throws:
        java.io.IOException
      • writeStartTagStart

        public abstract void writeStartTagStart​(java.lang.String localName)
                                         throws java.io.IOException,
                                                javax.xml.stream.XMLStreamException

        Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)

        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeStartTagStart

        public abstract void writeStartTagStart​(java.lang.String prefix,
                                                java.lang.String localName)
                                         throws java.io.IOException,
                                                javax.xml.stream.XMLStreamException

        Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)

        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeStartTagEnd

        public abstract void writeStartTagEnd()
                                       throws java.io.IOException
        Throws:
        java.io.IOException
      • writeStartTagEmptyEnd

        public abstract void writeStartTagEmptyEnd()
                                            throws java.io.IOException
        Throws:
        java.io.IOException
      • writeEndTag

        public abstract void writeEndTag​(java.lang.String localName)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
      • writeEndTag

        public abstract void writeEndTag​(java.lang.String prefix,
                                         java.lang.String localName)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
      • writeAttribute

        public abstract void writeAttribute​(java.lang.String localName,
                                            java.lang.String value)
                                     throws java.io.IOException,
                                            javax.xml.stream.XMLStreamException

        Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)

        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeAttribute

        public abstract void writeAttribute​(java.lang.String localName,
                                            char[] value,
                                            int offset,
                                            int len)
                                     throws java.io.IOException,
                                            javax.xml.stream.XMLStreamException
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeAttribute

        public abstract void writeAttribute​(java.lang.String prefix,
                                            java.lang.String localName,
                                            java.lang.String value)
                                     throws java.io.IOException,
                                            javax.xml.stream.XMLStreamException

        Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)

        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeAttribute

        public abstract void writeAttribute​(java.lang.String prefix,
                                            java.lang.String localName,
                                            char[] value,
                                            int offset,
                                            int len)
                                     throws java.io.IOException,
                                            javax.xml.stream.XMLStreamException
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeTypedElement

        public abstract void writeTypedElement​(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
                                        throws java.io.IOException
        Like writeRaw(java.lang.String, int, int), but caller guarantees that the contents additionally are known to be in 7-bit ascii range, and also passes an encoder object that will encode values only when being handed a buffer to append to.
        Parameters:
        enc - Encoder that will produce content
        Throws:
        java.io.IOException
      • writeTypedElement

        public abstract void writeTypedElement​(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc,
                                               org.codehaus.stax2.validation.XMLValidator validator,
                                               char[] copyBuffer)
                                        throws java.io.IOException,
                                               javax.xml.stream.XMLStreamException
        Like writeRaw(java.lang.String, int, int), but caller guarantees that the contents additionally are known to be in 7-bit ascii range, and also passes an encoder object that will encode values only when being handed a buffer to append to.
        Parameters:
        enc - Encoder that will produce content
        validator - Validator to use for validating serialized textual content (can not be null)
        copyBuffer - Temporary buffer that writer can use for temporary copies as necessary
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeTypedAttribute

        public abstract void writeTypedAttribute​(java.lang.String localName,
                                                 org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
                                          throws java.io.IOException,
                                                 javax.xml.stream.XMLStreamException
        Method similar to writeAttribute(String,String,char[],int,int) but where is known not to require escaping. No validation needs to be performed.
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeTypedAttribute

        public abstract void writeTypedAttribute​(java.lang.String prefix,
                                                 java.lang.String localName,
                                                 org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
                                          throws java.io.IOException,
                                                 javax.xml.stream.XMLStreamException
        Method similar to writeAttribute(String,String,char[],int,int) but where is known not to require escaping. No validation needs to be performed.
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeTypedAttribute

        public abstract void writeTypedAttribute​(java.lang.String prefix,
                                                 java.lang.String localName,
                                                 java.lang.String nsURI,
                                                 org.codehaus.stax2.ri.typed.AsciiValueEncoder enc,
                                                 org.codehaus.stax2.validation.XMLValidator validator,
                                                 char[] copyBuffer)
                                          throws java.io.IOException,
                                                 javax.xml.stream.XMLStreamException
        Method similar to writeAttribute(String,String,char[],int,int) but where is known not to require escaping. Validation of the attribute value must be done by calling given validator appropriately.
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • getOutputPtr

        protected abstract int getOutputPtr()
      • getRow

        public int getRow()
      • getColumn

        public int getColumn()
      • getAbsOffset

        public int getAbsOffset()
      • wrapAsRawWriter

        public final java.io.Writer wrapAsRawWriter()
        Method that can be called to get a wrapper instance that can be used to essentially call the writeRaw method.
      • wrapAsTextWriter

        public final java.io.Writer wrapAsTextWriter()
      • verifyNameValidity

        public final void verifyNameValidity​(java.lang.String name,
                                             boolean checkNs)
                                      throws javax.xml.stream.XMLStreamException
        Method called to verify that the name is a legal XML name.
        Throws:
        javax.xml.stream.XMLStreamException
      • reportNwfName

        protected void reportNwfName​(java.lang.String msg)
                              throws javax.xml.stream.XMLStreamException
        This is the method called when an output method call violates name well-formedness checks and WstxOutputProperties.P_OUTPUT_VALIDATE_NAMES is is enabled.
        Throws:
        javax.xml.stream.XMLStreamException
      • reportNwfContent

        protected void reportNwfContent​(java.lang.String msg)
                                 throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • throwOutputError

        protected void throwOutputError​(java.lang.String msg)
                                 throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • throwOutputError

        protected void throwOutputError​(java.lang.String format,
                                        java.lang.Object arg)
                                 throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • handleInvalidChar

        protected char handleInvalidChar​(int c)
                                  throws java.io.IOException
        Method called to handle invalid character in textual content requested to be output. Content may be part of textual events (CHARACTER, CDATA), attribute value, COMMENT content or PROCESSING_INSTRUCTION data. The default behavior is to just throw an exception, but this can be configured via property WstxOutputProperties.P_OUTPUT_INVALID_CHAR_HANDLER.
        Throws:
        java.io.IOException