com.ctc.wstx.sw
Class BufferingXmlWriter

java.lang.Object
  extended by com.ctc.wstx.sw.XmlWriter
      extended by com.ctc.wstx.sw.BufferingXmlWriter
All Implemented Interfaces:
XMLStreamConstants

public final class BufferingXmlWriter
extends XmlWriter
implements 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 Summary
protected static int HIGHEST_ENCODABLE_ATTR_CHAR
          Highest valued character that may need to be encoded (minus charset encoding requirements) when writing attribute values.
protected static int HIGHEST_ENCODABLE_TEXT_CHAR
          Highest valued character that may need to be encoded (minus charset encoding requirements) when writing attribute values.
protected  Writer mOut
          Actual Writer to use for outputting buffered data as appropriate.
protected  char[] mOutputBuffer
           
protected  int mOutputBufLen
           
protected  int mOutputPtr
           
protected  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.
protected  OutputStream mUnderlyingStream
          Actual physical stream that the writer is using, if known.
 
Fields inherited from class com.ctc.wstx.sw.XmlWriter
DEFAULT_QUOTE_CHAR, mAttrValueWriter, mAutoCloseOutput, mCheckContent, mCheckNames, mCheckStructure, mConfig, mEncoding, mFixContent, mLocPastChars, mLocRowNr, mLocRowStartOffset, mNsAware, mRawWrapper, mTextWrapper, mTextWriter, mXml11, SURR1_FIRST, SURR1_LAST, SURR2_FIRST, SURR2_LAST
 
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
 
Constructor Summary
BufferingXmlWriter(Writer out, WriterConfig cfg, String enc, boolean autoclose, OutputStream outs, int bitsize)
           
 
Method Summary
 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 flush()
           
protected  int getOutputPtr()
           
protected  OutputStream getOutputStream()
           
protected  Writer getWriter()
           
static int guessEncodingBitSize(String enc)
          Method used to figure out which part of the Unicode char set the encoding can natively support.
protected  int verifyCDataContent(char[] c, int start, int end)
           
protected  int verifyCDataContent(String content)
           
protected  int verifyCommentContent(String content)
           
protected  void writeAsEntity(int c)
           
 void writeAttribute(String localName, char[] value, int offset, int vlen)
           
 void writeAttribute(String localName, 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)
 void writeAttribute(String prefix, String localName, char[] value, int offset, int vlen)
           
 void writeAttribute(String prefix, String localName, 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)
 int writeCData(char[] cbuf, int offset, int len)
           
 int writeCData(String data)
           
 void writeCDataEnd()
           
 void writeCDataStart()
           
 void writeCharacters(char[] cbuf, int offset, int len)
           
 void writeCharacters(String text)
           
 int writeComment(String data)
          Method that will try to output the content as specified.
 void writeCommentEnd()
           
 void writeCommentStart()
           
 void writeDTD(String data)
          Older "legacy" output method for outputting DOCTYPE declaration.
 void writeDTD(String rootName, String systemId, String publicId, String internalSubset)
           
 void writeEndTag(String localName)
           
 void writeEndTag(String prefix, String localName)
           
 void writeEntityReference(String name)
           
 int writePI(String target, String data)
           
 void writePIEnd()
           
 void writePIStart(String target, boolean addSpace)
           
protected  void writePrefixedName(String prefix, String localName)
           
 void writeRaw(char[] cbuf, int offset, int len)
           
 void writeRaw(String str)
           
 void writeRaw(String str, int offset, int len)
           
 void writeRawAscii(char[] cbuf, int offset, int len)
          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.
protected  void writeSegmentedCData(char[] c, int start, int len, int index)
           
protected  void writeSegmentedCData(String content, int index)
           
protected  void writeSegmentedComment(String content, int index)
           
 void writeStartTagEmptyEnd()
           
 void writeStartTagEnd()
           
 void writeStartTagStart(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)
 void writeStartTagStart(String prefix, 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)
 void writeTypedAttribute(String localName, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
          Method similar to XmlWriter.writeAttribute(String,String,char[],int,int) but where is known not to require escaping.
 void writeTypedAttribute(String prefix, String localName, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
          Method similar to XmlWriter.writeAttribute(String,String,char[],int,int) but where is known not to require escaping.
 void writeTypedAttribute(String prefix, String localName, String nsURI, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc, org.codehaus.stax2.validation.XMLValidator validator, char[] copyBuffer)
          Method similar to XmlWriter.writeAttribute(String,String,char[],int,int) but where is known not to require escaping.
 void writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
          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.
 void writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc, org.codehaus.stax2.validation.XMLValidator validator, char[] copyBuffer)
          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.
 void writeXmlDeclaration(String version, String encoding, String standalone)
           
 
Methods inherited from class com.ctc.wstx.sw.XmlWriter
enableXml11, getAbsOffset, getColumn, getRow, handleInvalidChar, reportNwfContent, reportNwfName, reportNwfName, throwOutputError, throwOutputError, verifyNameValidity, wrapAsRawWriter, wrapAsTextWriter
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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

mOut

protected final 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 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.

Constructor Detail

BufferingXmlWriter

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

getOutputPtr

protected int getOutputPtr()
Specified by:
getOutputPtr in class XmlWriter

getOutputStream

protected final 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 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 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:
IOException

flush

public final void flush()
                 throws IOException
Specified by:
flush in class XmlWriter
Throws:
IOException

writeRaw

public void writeRaw(char[] cbuf,
                     int offset,
                     int len)
              throws IOException
Specified by:
writeRaw in class XmlWriter
Throws:
IOException

writeRawAscii

public final void writeRawAscii(char[] cbuf,
                                int offset,
                                int len)
                         throws 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:
IOException

writeRaw

public void writeRaw(String str)
              throws IOException
Overrides:
writeRaw in class XmlWriter
Throws:
IOException

writeRaw

public void writeRaw(String str,
                     int offset,
                     int len)
              throws IOException
Specified by:
writeRaw in class XmlWriter
Throws:
IOException

writeCDataStart

public final void writeCDataStart()
                           throws IOException
Specified by:
writeCDataStart in class XmlWriter
Throws:
IOException

writeCDataEnd

public final void writeCDataEnd()
                         throws IOException
Specified by:
writeCDataEnd in class XmlWriter
Throws:
IOException

writeCommentStart

public final void writeCommentStart()
                             throws IOException
Specified by:
writeCommentStart in class XmlWriter
Throws:
IOException

writeCommentEnd

public final void writeCommentEnd()
                           throws IOException
Specified by:
writeCommentEnd in class XmlWriter
Throws:
IOException

writePIStart

public final void writePIStart(String target,
                               boolean addSpace)
                        throws IOException
Specified by:
writePIStart in class XmlWriter
Throws:
IOException

writePIEnd

public final void writePIEnd()
                      throws IOException
Specified by:
writePIEnd in class XmlWriter
Throws:
IOException

writeCData

public int writeCData(String data)
               throws 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:
IOException

writeCData

public int writeCData(char[] cbuf,
                      int offset,
                      int len)
               throws IOException
Specified by:
writeCData in class XmlWriter
Throws:
IOException

writeCharacters

public void writeCharacters(String text)
                     throws IOException
Specified by:
writeCharacters in class XmlWriter
Throws:
IOException

writeCharacters

public void writeCharacters(char[] cbuf,
                            int offset,
                            int len)
                     throws IOException
Specified by:
writeCharacters in class XmlWriter
Throws:
IOException

writeComment

public int writeComment(String data)
                 throws 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:
IOException

writeDTD

public void writeDTD(String data)
              throws 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:
IOException

writeDTD

public void writeDTD(String rootName,
                     String systemId,
                     String publicId,
                     String internalSubset)
              throws IOException,
                     XMLStreamException
Specified by:
writeDTD in class XmlWriter
Throws:
IOException
XMLStreamException

writeEntityReference

public void writeEntityReference(String name)
                          throws IOException,
                                 XMLStreamException
Specified by:
writeEntityReference in class XmlWriter
Throws:
IOException
XMLStreamException

writeXmlDeclaration

public void writeXmlDeclaration(String version,
                                String encoding,
                                String standalone)
                         throws IOException
Specified by:
writeXmlDeclaration in class XmlWriter
Throws:
IOException

writePI

public int writePI(String target,
                   String data)
            throws IOException,
                   XMLStreamException
Specified by:
writePI in class XmlWriter
Throws:
IOException
XMLStreamException

writeStartTagStart

public void writeStartTagStart(String localName)
                        throws IOException,
                               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:
IOException
XMLStreamException

writeStartTagStart

public void writeStartTagStart(String prefix,
                               String localName)
                        throws IOException,
                               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:
IOException
XMLStreamException

writeStartTagEnd

public void writeStartTagEnd()
                      throws IOException
Specified by:
writeStartTagEnd in class XmlWriter
Throws:
IOException

writeStartTagEmptyEnd

public void writeStartTagEmptyEnd()
                           throws IOException
Specified by:
writeStartTagEmptyEnd in class XmlWriter
Throws:
IOException

writeEndTag

public void writeEndTag(String localName)
                 throws IOException
Specified by:
writeEndTag in class XmlWriter
Throws:
IOException

writeEndTag

public void writeEndTag(String prefix,
                        String localName)
                 throws IOException
Specified by:
writeEndTag in class XmlWriter
Throws:
IOException

writeAttribute

public void writeAttribute(String localName,
                           String value)
                    throws IOException,
                           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:
IOException
XMLStreamException

writeAttribute

public void writeAttribute(String localName,
                           char[] value,
                           int offset,
                           int vlen)
                    throws IOException,
                           XMLStreamException
Specified by:
writeAttribute in class XmlWriter
Throws:
IOException
XMLStreamException

writeAttribute

public void writeAttribute(String prefix,
                           String localName,
                           String value)
                    throws IOException,
                           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:
IOException
XMLStreamException

writeAttribute

public void writeAttribute(String prefix,
                           String localName,
                           char[] value,
                           int offset,
                           int vlen)
                    throws IOException,
                           XMLStreamException
Specified by:
writeAttribute in class XmlWriter
Throws:
IOException
XMLStreamException

writeTypedElement

public final void writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
                             throws 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:
IOException

writeTypedElement

public final void writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc,
                                    org.codehaus.stax2.validation.XMLValidator validator,
                                    char[] copyBuffer)
                             throws IOException,
                                    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:
IOException
XMLStreamException

writeTypedAttribute

public void writeTypedAttribute(String localName,
                                org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
                         throws IOException,
                                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:
IOException
XMLStreamException

writeTypedAttribute

public void writeTypedAttribute(String prefix,
                                String localName,
                                org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
                         throws IOException,
                                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:
IOException
XMLStreamException

writeTypedAttribute

public void writeTypedAttribute(String prefix,
                                String localName,
                                String nsURI,
                                org.codehaus.stax2.ri.typed.AsciiValueEncoder enc,
                                org.codehaus.stax2.validation.XMLValidator validator,
                                char[] copyBuffer)
                         throws IOException,
                                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:
IOException
XMLStreamException

writePrefixedName

protected final void writePrefixedName(String prefix,
                                       String localName)
                                throws IOException
Throws:
IOException

verifyCDataContent

protected int verifyCDataContent(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(String content)

writeSegmentedCData

protected void writeSegmentedCData(String content,
                                   int index)
                            throws IOException
Throws:
IOException

writeSegmentedCData

protected void writeSegmentedCData(char[] c,
                                   int start,
                                   int len,
                                   int index)
                            throws IOException
Throws:
IOException

writeSegmentedComment

protected void writeSegmentedComment(String content,
                                     int index)
                              throws IOException
Throws:
IOException

guessEncodingBitSize

public static int guessEncodingBitSize(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 IOException
Throws:
IOException


Copyright © 2011 Codehaus. All Rights Reserved.