Class BufferingXmlWriter

  • All Implemented Interfaces:
    javax.xml.stream.XMLStreamConstants

    public final class BufferingXmlWriter
    extends XmlWriter
    implements javax.xml.stream.XMLStreamConstants
    Concrete implementation of XmlWriter that will dispatch writes to another writer (of type Writer, and will NOT handle encoding. It will, however, do basic buffering such that the underlying Writer need (and thus, should) not do buffering.

    One design goal for this class is to avoid unnecessary buffering: since there will be another Writer doing the actual encoding, amount of buffering needed should still be limited. To this end, a threshold is used to define what's the threshold of writes that we do want to coalesce, ie. buffer. Writes bigger than this should in general proceed without buffering.

    • Field Detail

      • DEFAULT_BUFFER_SIZE

        static final int DEFAULT_BUFFER_SIZE
        Let's use a typical default to have a compromise between large enough chunks to output, and minimizing memory overhead. Compared to encoding writers, buffer size can be bit smaller since there's one more level of processing (at encoding), which may use bigger buffering.
        See Also:
        Constant Field Values
      • DEFAULT_SMALL_SIZE

        static final int DEFAULT_SMALL_SIZE
        Choosing threshold for 'small size' is a compromise between excessive buffering (high small size), and too many fragmented calls to the underlying writer (low small size). Let's just use about 1/4 of the full buffer size.
        See Also:
        Constant Field Values
      • HIGHEST_ENCODABLE_ATTR_CHAR

        protected static final int HIGHEST_ENCODABLE_ATTR_CHAR
        Highest valued character that may need to be encoded (minus charset encoding requirements) when writing attribute values.
        See Also:
        Constant Field Values
      • HIGHEST_ENCODABLE_TEXT_CHAR

        protected static final int HIGHEST_ENCODABLE_TEXT_CHAR
        Highest valued character that may need to be encoded (minus charset encoding requirements) when writing attribute values.
        See Also:
        Constant Field Values
      • QUOTABLE_TEXT_CHARS

        protected static final int[] QUOTABLE_TEXT_CHARS
      • mOut

        protected final java.io.Writer mOut
        Actual Writer to use for outputting buffered data as appropriate.
      • mOutputBuffer

        protected char[] mOutputBuffer
      • mSmallWriteSize

        protected final int mSmallWriteSize
        This is the threshold used to check what is considered a "small" write; small writes will be buffered until resulting size will be above the threshold.
      • mOutputPtr

        protected int mOutputPtr
      • mOutputBufLen

        protected int mOutputBufLen
      • mUnderlyingStream

        protected final java.io.OutputStream mUnderlyingStream
        Actual physical stream that the writer is using, if known. Not used for actual output, only needed so that calling application may (try to) figure out the original source.
      • mEncHighChar

        private final int mEncHighChar
        First Unicode character (one with lowest value) after (and including) which character entities have to be used. For
      • mEncQuoteChar

        final char mEncQuoteChar
        Character that is considered to be the enclosing quote character; for XML either single or double quote.
      • mEncQuoteEntity

        final java.lang.String mEncQuoteEntity
        Entity String to use for escaping the quote character.
    • Constructor Detail

      • BufferingXmlWriter

        public BufferingXmlWriter​(java.io.Writer out,
                                  WriterConfig cfg,
                                  java.lang.String enc,
                                  boolean autoclose,
                                  java.io.OutputStream outs,
                                  int bitsize)
                           throws java.io.IOException
        Parameters:
        outs - Underlying OutputStream that the writer (out) is using, if known. Needed to support (optional) access to the underlying stream
        Throws:
        java.io.IOException
    • Method Detail

      • getOutputStream

        protected final java.io.OutputStream getOutputStream()
        Specified by:
        getOutputStream in class XmlWriter
        Returns:
        Underlying OutputStream used for physical output, if the writer was constructed using one
      • getWriter

        protected final java.io.Writer getWriter()
        Specified by:
        getWriter in class XmlWriter
        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 void close​(boolean forceRealClose)
                   throws java.io.IOException
        Description copied from class: XmlWriter
        Method called to flush the buffer(s), and close the output sink (stream or writer) if enabled (auto-closing) or forced.
        Specified by:
        close in class XmlWriter
        Throws:
        java.io.IOException
      • flush

        public final void flush()
                         throws java.io.IOException
        Specified by:
        flush in class XmlWriter
        Throws:
        java.io.IOException
      • writeRaw

        public void writeRaw​(char[] cbuf,
                             int offset,
                             int len)
                      throws java.io.IOException
        Specified by:
        writeRaw in class XmlWriter
        Throws:
        java.io.IOException
      • writeRawAscii

        public final void writeRawAscii​(char[] cbuf,
                                        int offset,
                                        int len)
                                 throws java.io.IOException
        Method called to output typed values (int, long, double, float etc) that are known not to contain any escapable characters, or anything else beyond 7-bit ascii range.
        Specified by:
        writeRawAscii in class XmlWriter
        Throws:
        java.io.IOException
      • writeRaw

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

        public void writeRaw​(java.lang.String str,
                             int offset,
                             int len)
                      throws java.io.IOException
        Specified by:
        writeRaw in class XmlWriter
        Throws:
        java.io.IOException
      • writeCDataStart

        public final void writeCDataStart()
                                   throws java.io.IOException
        Specified by:
        writeCDataStart in class XmlWriter
        Throws:
        java.io.IOException
      • writeCDataEnd

        public final void writeCDataEnd()
                                 throws java.io.IOException
        Specified by:
        writeCDataEnd in class XmlWriter
        Throws:
        java.io.IOException
      • writeCommentStart

        public final void writeCommentStart()
                                     throws java.io.IOException
        Specified by:
        writeCommentStart in class XmlWriter
        Throws:
        java.io.IOException
      • writeCommentEnd

        public final void writeCommentEnd()
                                   throws java.io.IOException
        Specified by:
        writeCommentEnd in class XmlWriter
        Throws:
        java.io.IOException
      • writePIStart

        public final void writePIStart​(java.lang.String target,
                                       boolean addSpace)
                                throws java.io.IOException
        Specified by:
        writePIStart in class XmlWriter
        Throws:
        java.io.IOException
      • writePIEnd

        public final void writePIEnd()
                              throws java.io.IOException
        Specified by:
        writePIEnd in class XmlWriter
        Throws:
        java.io.IOException
      • writeCData

        public int writeCData​(java.lang.String data)
                       throws java.io.IOException
        Specified by:
        writeCData in class XmlWriter
        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
      • writeCData

        public int writeCData​(char[] cbuf,
                              int offset,
                              int len)
                       throws java.io.IOException
        Specified by:
        writeCData in class XmlWriter
        Throws:
        java.io.IOException
      • writeCharacters

        public void writeCharacters​(java.lang.String text)
                             throws java.io.IOException
        Specified by:
        writeCharacters in class XmlWriter
        Throws:
        java.io.IOException
      • writeCharacters

        public void writeCharacters​(char[] cbuf,
                                    int offset,
                                    int len)
                             throws java.io.IOException
        Specified by:
        writeCharacters in class XmlWriter
        Throws:
        java.io.IOException
      • writeComment

        public int writeComment​(java.lang.String data)
                         throws java.io.IOException
        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.
        Specified by:
        writeComment in class XmlWriter
        Throws:
        java.io.IOException
      • writeDTD

        public void writeDTD​(java.lang.String data)
                      throws java.io.IOException
        Description copied from class: XmlWriter
        Older "legacy" output method for outputting DOCTYPE declaration. Assumes that the passed-in String contains a complete DOCTYPE declaration properly quoted.
        Specified by:
        writeDTD in class XmlWriter
        Throws:
        java.io.IOException
      • writeDTD

        public 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
        Specified by:
        writeDTD in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeEntityReference

        public void writeEntityReference​(java.lang.String name)
                                  throws java.io.IOException,
                                         javax.xml.stream.XMLStreamException
        Specified by:
        writeEntityReference in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeXmlDeclaration

        public void writeXmlDeclaration​(java.lang.String version,
                                        java.lang.String encoding,
                                        java.lang.String standalone)
                                 throws java.io.IOException
        Specified by:
        writeXmlDeclaration in class XmlWriter
        Throws:
        java.io.IOException
      • writePI

        public int writePI​(java.lang.String target,
                           java.lang.String data)
                    throws java.io.IOException,
                           javax.xml.stream.XMLStreamException
        Specified by:
        writePI in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeStartTagStart

        public void writeStartTagStart​(java.lang.String localName)
                                throws java.io.IOException,
                                       javax.xml.stream.XMLStreamException
        Description copied from class: XmlWriter

        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)

        Specified by:
        writeStartTagStart in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeStartTagStart

        public void writeStartTagStart​(java.lang.String prefix,
                                       java.lang.String localName)
                                throws java.io.IOException,
                                       javax.xml.stream.XMLStreamException
        Description copied from class: XmlWriter

        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)

        Specified by:
        writeStartTagStart in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeStartTagEnd

        public void writeStartTagEnd()
                              throws java.io.IOException
        Specified by:
        writeStartTagEnd in class XmlWriter
        Throws:
        java.io.IOException
      • writeStartTagEmptyEnd

        public void writeStartTagEmptyEnd()
                                   throws java.io.IOException
        Specified by:
        writeStartTagEmptyEnd in class XmlWriter
        Throws:
        java.io.IOException
      • writeEndTag

        public void writeEndTag​(java.lang.String localName)
                         throws java.io.IOException
        Specified by:
        writeEndTag in class XmlWriter
        Throws:
        java.io.IOException
      • writeEndTag

        public void writeEndTag​(java.lang.String prefix,
                                java.lang.String localName)
                         throws java.io.IOException
        Specified by:
        writeEndTag in class XmlWriter
        Throws:
        java.io.IOException
      • writeAttribute

        public void writeAttribute​(java.lang.String localName,
                                   java.lang.String value)
                            throws java.io.IOException,
                                   javax.xml.stream.XMLStreamException
        Description copied from class: XmlWriter

        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)

        Specified by:
        writeAttribute in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeAttribute

        public void writeAttribute​(java.lang.String localName,
                                   char[] value,
                                   int offset,
                                   int vlen)
                            throws java.io.IOException,
                                   javax.xml.stream.XMLStreamException
        Specified by:
        writeAttribute in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeAttribute

        public void writeAttribute​(java.lang.String prefix,
                                   java.lang.String localName,
                                   java.lang.String value)
                            throws java.io.IOException,
                                   javax.xml.stream.XMLStreamException
        Description copied from class: XmlWriter

        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)

        Specified by:
        writeAttribute in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeAttribute

        public void writeAttribute​(java.lang.String prefix,
                                   java.lang.String localName,
                                   char[] value,
                                   int offset,
                                   int vlen)
                            throws java.io.IOException,
                                   javax.xml.stream.XMLStreamException
        Specified by:
        writeAttribute in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeAttrValue

        private final void writeAttrValue​(java.lang.String value,
                                          int len)
                                   throws java.io.IOException
        Throws:
        java.io.IOException
      • writeAttrValue

        private final void writeAttrValue​(char[] value,
                                          int offset,
                                          int len)
                                   throws java.io.IOException
        Throws:
        java.io.IOException
      • writeTypedElement

        public final void writeTypedElement​(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
                                     throws java.io.IOException
        Description copied from class: XmlWriter
        Like XmlWriter.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.
        Specified by:
        writeTypedElement in class XmlWriter
        Parameters:
        enc - Encoder that will produce content
        Throws:
        java.io.IOException
      • writeTypedElement

        public final 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
        Description copied from class: XmlWriter
        Like XmlWriter.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.
        Specified by:
        writeTypedElement in class XmlWriter
        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 void writeTypedAttribute​(java.lang.String localName,
                                        org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
                                 throws java.io.IOException,
                                        javax.xml.stream.XMLStreamException
        Description copied from class: XmlWriter
        Method similar to XmlWriter.writeAttribute(String,String,char[],int,int) but where is known not to require escaping. No validation needs to be performed.
        Specified by:
        writeTypedAttribute in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeTypedAttribute

        public 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
        Description copied from class: XmlWriter
        Method similar to XmlWriter.writeAttribute(String,String,char[],int,int) but where is known not to require escaping. No validation needs to be performed.
        Specified by:
        writeTypedAttribute in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writeTypedAttribute

        public 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
        Description copied from class: XmlWriter
        Method similar to XmlWriter.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.
        Specified by:
        writeTypedAttribute in class XmlWriter
        Throws:
        java.io.IOException
        javax.xml.stream.XMLStreamException
      • writePrefixedName

        protected final void writePrefixedName​(java.lang.String prefix,
                                               java.lang.String localName)
                                        throws java.io.IOException
        Throws:
        java.io.IOException
      • flushBuffer

        private final void flushBuffer()
                                throws java.io.IOException
        Throws:
        java.io.IOException
      • fastWriteRaw

        private final void fastWriteRaw​(char c)
                                 throws java.io.IOException
        Throws:
        java.io.IOException
      • fastWriteRaw

        private final void fastWriteRaw​(char c1,
                                        char c2)
                                 throws java.io.IOException
        Throws:
        java.io.IOException
      • fastWriteRaw

        private final void fastWriteRaw​(java.lang.String str)
                                 throws java.io.IOException
        Throws:
        java.io.IOException
      • verifyCDataContent

        protected int verifyCDataContent​(java.lang.String content)
        Returns:
        Index at which a problem was found, if any; -1 if there's no problem.
      • verifyCDataContent

        protected int verifyCDataContent​(char[] c,
                                         int start,
                                         int end)
      • verifyCommentContent

        protected int verifyCommentContent​(java.lang.String content)
      • writeSegmentedCData

        protected void writeSegmentedCData​(java.lang.String content,
                                           int index)
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • writeSegmentedCData

        protected void writeSegmentedCData​(char[] c,
                                           int start,
                                           int len,
                                           int index)
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • writeSegmentedComment

        protected void writeSegmentedComment​(java.lang.String content,
                                             int index)
                                      throws java.io.IOException
        Throws:
        java.io.IOException
      • guessEncodingBitSize

        public static int guessEncodingBitSize​(java.lang.String enc)
        Method used to figure out which part of the Unicode char set the encoding can natively support. Values returned are 7, 8 and 16, to indicate (respectively) "ascii", "ISO-Latin" and "native Unicode". These just best guesses, but should work ok for the most common encodings.
      • writeAsEntity

        protected final void writeAsEntity​(int c)
                                    throws java.io.IOException
        Throws:
        java.io.IOException