Class EncodingXmlWriter

java.lang.Object

com.ctc.wstx.sw.XmlWriter

com.ctc.wstx.sw.EncodingXmlWriter

Direct Known Subclasses:

AsciiXmlWriter, ISOLatin1XmlWriter

public abstract class EncodingXmlWriter
extends XmlWriter

Intermediate base class used when outputting to streams that use an encoding that is compatible with 7-bit single-byte Ascii encoding. That means it can be used for UTF-8, ISO-Latin1 and pure Ascii.

Implementation notes:

Parts of surrogate handling are implemented here in the base class: storage for the first part of a split surrogate (only possible when character content is output split in multiple calls) is within base class. Also, simple checks for unmatched surrogate pairs are in writeAscii method, since it is the most convenient place to catch cases where a text segment ends with an unmatched surrogate pair half.

Field Summary

Fields

Modifier and Type	Field	Description
(package private) static final byte	BYTE_A
(package private) static final byte	BYTE_AMP
(package private) static final byte	BYTE_APOS
(package private) static final byte	BYTE_COLON
(package private) static final byte	BYTE_EQ
(package private) static final byte	BYTE_G
(package private) static final byte	BYTE_GT
(package private) static final byte	BYTE_HASH
(package private) static final byte	BYTE_HYPHEN
(package private) static final byte	BYTE_L
(package private) static final byte	BYTE_LBRACKET
(package private) static final byte	BYTE_LT
(package private) static final byte	BYTE_M
(package private) static final byte	BYTE_O
(package private) static final byte	BYTE_P
(package private) static final byte	BYTE_Q
(package private) static final byte	BYTE_QMARK
(package private) static final byte	BYTE_QUOT
(package private) static final byte	BYTE_RBRACKET
(package private) static final byte	BYTE_S
(package private) static final byte	BYTE_SEMICOLON
(package private) static final byte	BYTE_SLASH
(package private) static final byte	BYTE_SPACE
(package private) static final byte	BYTE_T
(package private) static final byte	BYTE_U
(package private) static final byte	BYTE_X
(package private) 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.
private final OutputStream	mOut	Actual output stream to use for outputting encoded content as bytes.
protected byte[]	mOutputBuffer
protected int	mOutputPtr
protected int	mSurrogate	In case a split surrogate pair is output (which can only successfully occur with either writeRaw or writeCharacters), the first part is temporarily stored within this member variable.

Fields inherited from class XmlWriter

DEFAULT_QUOTE_CHAR, mAddSpaceAfterEmptyElem, mAttrValueWriter, mAutoCloseOutput, mCheckContent, mCheckNames, mCheckStructure, mConfig, mEncoding, mEscapeCR, mFixContent, mLocPastChars, mLocRowNr, mLocRowStartOffset, mNsAware, mRawWrapper, mTextWrapper, mTextWriter, mUseDoubleQuotesInXmlDecl, mXml11, SURR1_FIRST, SURR1_LAST, SURR2_FIRST, SURR2_LAST

Constructor Summary

Constructors

Constructor	Description
EncodingXmlWriter(OutputStream out, WriterConfig cfg, String encoding, boolean autoclose)

Method Summary

Modifier and Type	Method	Description
protected final int	calcSurrogate(int secondSurr)
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.
final void	flush()
protected final void	flushBuffer()
protected int	getOutputPtr()	This method is needed by the super class, to calculate hard byte/char offsets.
protected final OutputStream	getOutputStream()
protected final Writer	getWriter()
protected final void	throwUnpairedSurrogate()
protected final void	throwUnpairedSurrogate(int code)
protected final void	writeAscii(byte b)
protected final void	writeAscii(byte b1, byte b2)
protected final void	writeAscii(String str)
protected final int	writeAsEntity(int c)	Entity writing can be optimized quite nicely, since it only needs to output ascii characters.
void	writeAttribute(String localName, char[] value, int offset, int len)
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 len)
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)
protected abstract void	writeAttrValue(char[] value, int offset, int len)
protected abstract void	writeAttrValue(String data)
int	writeCData(char[] cbuf, int offset, int len)
int	writeCData(String data)
protected abstract int	writeCDataContent(char[] cbuf, int start, int len)
protected abstract int	writeCDataContent(String data)
final void	writeCDataEnd()
final void	writeCDataStart()
final void	writeCharacters(char[] cbuf, int offset, int len)
final void	writeCharacters(String data)
int	writeComment(String data)	Method that will try to output the content as specified.
protected abstract int	writeCommentContent(String data)
final void	writeCommentEnd()
final 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)
protected final void	writeName(String name)
protected final void	writeNameUnchecked(String name)
int	writePI(String target, String data)
protected abstract int	writePIData(String data)
final void	writePIEnd()
final void	writePIStart(String target, boolean addSpace)
abstract void	writeRaw(char[] cbuf, int offset, int len)
abstract void	writeRaw(String str, int offset, int len)
final void	writeRawAscii(char[] buf, int offset, int len)	Like XmlWriter.writeRaw(String, int, int), but caller guarantees that the contents additionally are known to be in 7-bit ascii range.
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)
protected abstract void	writeTextContent(char[] cbuf, int start, int len)
protected abstract void	writeTextContent(String data)
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	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 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.
final void	writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)	Non-validating version of typed write method
final void	writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc, org.codehaus.stax2.validation.XMLValidator validator, char[] copyBuffer)	Validating version of typed write method
void	writeXmlDeclaration(String version, String encoding, String standalone)

Methods inherited from class XmlWriter

enableXml11, getAbsOffset, getColumn, getRow, handleInvalidChar, reportNwfContent, reportNwfName, throwOutputError, throwOutputError, verifyNameValidity, wrapAsRawWriter, wrapAsTextWriter, writeRaw

Methods inherited from class Object

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

Field Details

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. 4k should be close enough to a physical page to work out acceptably, without causing excessive (if temporary) memory usage.

See Also:

• Constant Field Values

BYTE_SPACE

static final byte BYTE_SPACE

See Also:

• Constant Field Values

BYTE_COLON

static final byte BYTE_COLON

See Also:

• Constant Field Values

BYTE_SEMICOLON

static final byte BYTE_SEMICOLON

See Also:

• Constant Field Values

BYTE_LBRACKET

static final byte BYTE_LBRACKET

See Also:

• Constant Field Values

BYTE_RBRACKET

static final byte BYTE_RBRACKET

See Also:

• Constant Field Values

BYTE_QMARK

static final byte BYTE_QMARK

See Also:

• Constant Field Values

BYTE_EQ

static final byte BYTE_EQ

See Also:

• Constant Field Values

BYTE_SLASH

static final byte BYTE_SLASH

See Also:

• Constant Field Values

BYTE_HASH

static final byte BYTE_HASH

See Also:

• Constant Field Values

BYTE_HYPHEN

static final byte BYTE_HYPHEN

See Also:

• Constant Field Values

BYTE_LT

static final byte BYTE_LT

See Also:

• Constant Field Values

BYTE_GT

static final byte BYTE_GT

See Also:

• Constant Field Values

BYTE_AMP

static final byte BYTE_AMP

See Also:

• Constant Field Values

BYTE_QUOT

static final byte BYTE_QUOT

See Also:

• Constant Field Values

BYTE_APOS

static final byte BYTE_APOS

See Also:

• Constant Field Values

BYTE_A

static final byte BYTE_A

See Also:

• Constant Field Values

BYTE_G

static final byte BYTE_G

See Also:

• Constant Field Values

BYTE_L

static final byte BYTE_L

See Also:

• Constant Field Values

BYTE_M

static final byte BYTE_M

See Also:

• Constant Field Values

BYTE_O

static final byte BYTE_O

See Also:

• Constant Field Values

BYTE_P

static final byte BYTE_P

See Also:

• Constant Field Values

BYTE_Q

static final byte BYTE_Q

See Also:

• Constant Field Values

BYTE_S

static final byte BYTE_S

See Also:

• Constant Field Values

BYTE_T

static final byte BYTE_T

See Also:

• Constant Field Values

BYTE_U

static final byte BYTE_U

See Also:

• Constant Field Values

BYTE_X

static final byte BYTE_X

See Also:

• Constant Field Values

mOut

private final OutputStream mOut

Actual output stream to use for outputting encoded content as bytes.

mOutputBuffer

protected byte[] mOutputBuffer

mOutputPtr

protected int mOutputPtr

mSurrogate

protected int mSurrogate

In case a split surrogate pair is output (which can only successfully occur with either writeRaw or writeCharacters), the first part is temporarily stored within this member variable.

Constructor Details

EncodingXmlWriter

public EncodingXmlWriter(OutputStream out,
 WriterConfig cfg,
 String encoding,
 boolean autoclose)
                  throws IOException

Throws:

IOException

Method Details

getOutputPtr

protected int getOutputPtr()

This method is needed by the super class, to calculate hard byte/char offsets.

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 abstract void writeRaw(char[] cbuf,
 int offset,
 int len)
                       throws IOException

Specified by:

writeRaw in class XmlWriter

Throws:

IOException

writeRaw

public abstract 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 final void writeCharacters(String data)
                           throws IOException

Specified by:

writeCharacters in class XmlWriter

Throws:

IOException

writeCharacters

public final 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 len)
                    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 len)
                    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

Non-validating version of typed write method

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

Validating version of typed write method

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

flushBuffer

protected final void flushBuffer()
                          throws IOException

Throws:

IOException

writeAscii

protected final void writeAscii(byte b)
                         throws IOException

Throws:

IOException

writeAscii

protected final void writeAscii(byte b1,
 byte b2)
                         throws IOException

Throws:

IOException

writeAscii

protected final void writeAscii(String str)
                         throws IOException

Throws:

IOException

writeRawAscii

public final void writeRawAscii(char[] buf,
 int offset,
 int len)
                         throws IOException

Description copied from class: XmlWriter

Like XmlWriter.writeRaw(String, int, int), but caller guarantees that the contents additionally are known to be in 7-bit ascii range.

Specified by:

writeRawAscii in class XmlWriter

Throws:

IOException

writeAsEntity

protected final int writeAsEntity(int c)
                           throws IOException

Entity writing can be optimized quite nicely, since it only needs to output ascii characters.

Returns:

New value of mOutputPtr

Throws:

IOException

writeName

protected final void writeName(String name)
                        throws IOException,
XMLStreamException

Throws:

IOException

XMLStreamException

writeNameUnchecked

protected final void writeNameUnchecked(String name)
                                 throws IOException

Throws:

IOException

calcSurrogate

protected final int calcSurrogate(int secondSurr)
                           throws IOException

Throws:

IOException

throwUnpairedSurrogate

protected final void throwUnpairedSurrogate()
                                     throws IOException

Throws:

IOException

throwUnpairedSurrogate

protected final void throwUnpairedSurrogate(int code)
                                     throws IOException

Throws:

IOException

writeAttrValue

protected abstract void writeAttrValue(String data)
                                throws IOException

Throws:

IOException

writeAttrValue

protected abstract void writeAttrValue(char[] value,
 int offset,
 int len)
                                throws IOException

Throws:

IOException

writeCDataContent

protected abstract int writeCDataContent(String data)
                                  throws IOException

Throws:

IOException

writeCDataContent

protected abstract int writeCDataContent(char[] cbuf,
 int start,
 int len)
                                  throws IOException

Throws:

IOException

writeCommentContent

protected abstract int writeCommentContent(String data)
                                    throws IOException

Throws:

IOException

writePIData

protected abstract int writePIData(String data)
                            throws IOException,
XMLStreamException

Throws:

IOException

XMLStreamException

writeTextContent

protected abstract void writeTextContent(String data)
                                  throws IOException

Throws:

IOException

writeTextContent

protected abstract void writeTextContent(char[] cbuf,
 int start,
 int len)
                                  throws IOException

Throws:

IOException