java.lang.Object
- com.ctc.wstx.sw.XmlWriter

Direct Known Subclasses:

BufferingXmlWriter, EncodingXmlWriter
```
public abstract class XmlWriter
extends 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`
`protected 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 String`	`mEncoding`
`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 Writer`	`mTextWriter`	Optional escaping writer used for escaping characters like '<' '&' and '>' in textual content.
`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, 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 OutputStream`	`getOutputStream()`
`int`	`getRow()`
`protected abstract Writer`	`getWriter()`
`protected char`	`handleInvalidChar(int c)`	Method called to handle invalid character in textual content requested to be output.
`protected void`	`reportNwfContent(String msg)`
`protected void`	`reportNwfName(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`	`reportNwfName(String msg, Object arg)`
`protected void`	`throwOutputError(String msg)`
`protected void`	`throwOutputError(String format, Object arg)`
`void`	`verifyNameValidity(String name, boolean checkNs)`	Method called to verify that the name is a legal XML name.
`Writer`	`wrapAsRawWriter()`	Method that can be called to get a wrapper instance that can be used to essentially call the `writeRaw` method.
`Writer`	`wrapAsTextWriter()`
`abstract void`	`writeAttribute(String localName, char[] value, int offset, int len)`
`abstract 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)
`abstract void`	`writeAttribute(String prefix, String localName, char[] value, int offset, int len)`
`abstract 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)
`abstract int`	`writeCData(char[] cbuf, int offset, int len)`
`abstract int`	`writeCData(String data)`
`abstract void`	`writeCDataEnd()`
`abstract void`	`writeCDataStart()`
`abstract void`	`writeCharacters(char[] cbuf, int offset, int len)`
`abstract void`	`writeCharacters(String data)`
`abstract int`	`writeComment(String data)`	Method that will try to output the content as specified.
`abstract void`	`writeCommentEnd()`
`abstract void`	`writeCommentStart()`
`abstract void`	`writeDTD(String data)`	Older "legacy" output method for outputting DOCTYPE declaration.
`abstract void`	`writeDTD(String rootName, String systemId, String publicId, String internalSubset)`
`abstract void`	`writeEndTag(String localName)`
`abstract void`	`writeEndTag(String prefix, String localName)`
`abstract void`	`writeEntityReference(String name)`
`abstract int`	`writePI(String target, String data)`
`abstract void`	`writePIEnd()`
`abstract void`	`writePIStart(String target, boolean addSpace)`
`abstract void`	`writeRaw(char[] cbuf, int offset, int len)`
`void`	`writeRaw(String str)`
`abstract void`	`writeRaw(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(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(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)
`abstract void`	`writeTypedAttribute(String prefix, String localName, String nsURI, AsciiValueEncoder enc, XMLValidator validator, char[] copyBuffer)`	Method similar to `writeAttribute(String,String,char[],int,int)` but where is known not to require escaping.
`abstract void`	`writeTypedAttribute(String prefix, String localName, AsciiValueEncoder enc)`	Method similar to `writeAttribute(String,String,char[],int,int)` but where is known not to require escaping.
`abstract void`	`writeTypedAttribute(String localName, AsciiValueEncoder enc)`	Method similar to `writeAttribute(String,String,char[],int,int)` but where is known not to require escaping.
`abstract void`	`writeTypedElement(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(AsciiValueEncoder enc, 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(String version, String enc, String standalone)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- SURR1_FIRST
```
protected static final int SURR1_FIRST
```
  See Also:
  
  Constant Field Values
- SURR1_LAST
```
protected static final int SURR1_LAST
```
  See Also:
  
  Constant Field Values
- SURR2_FIRST
```
protected static final int SURR2_FIRST
```
  See Also:
  
  Constant Field Values
- SURR2_LAST
```
protected static final int SURR2_LAST
```
  See Also:
  
  Constant Field Values
- DEFAULT_QUOTE_CHAR
```
protected static final char DEFAULT_QUOTE_CHAR
```
  See Also:
  
  Constant Field Values
- mConfig
```
protected final WriterConfig mConfig
```
- mEncoding
```
protected final 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
```
- 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 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 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,
                    String encoding,
                    boolean autoclose)
             throws IOException

Throws:: IOException

Method Detail

enableXml11
```
public void enableXml11()
```

getOutputStream
```
protected abstract OutputStream getOutputStream()
```
Returns:

Underlying OutputStream used for physical output, if the writer was constructed using one

getWriter
```
protected abstract 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 IOException
```
Method called to flush the buffer(s), and close the output sink (stream or writer) if enabled (auto-closing) or forced.

Throws:

IOException

flush

public abstract void flush()
                    throws IOException

Throws:: IOException

writeRaw

public abstract void writeRaw(String str,
                              int offset,
                              int len)
                       throws IOException

Throws:: IOException

writeRaw

public void writeRaw(String str)
              throws IOException

Throws:: IOException

writeRaw

public abstract void writeRaw(char[] cbuf,
                              int offset,
                              int len)
                       throws IOException

Throws:: IOException

writeRawAscii

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

writeCDataStart

public abstract void writeCDataStart()
                              throws IOException

Throws:: IOException

writeCDataEnd

public abstract void writeCDataEnd()
                            throws IOException

Throws:: IOException

writeCommentStart

public abstract void writeCommentStart()
                                throws IOException

Throws:: IOException

writeCommentEnd

public abstract void writeCommentEnd()
                              throws IOException

Throws:: IOException

writePIStart

public abstract void writePIStart(String target,
                                  boolean addSpace)
                           throws IOException

Throws:: IOException

writePIEnd

public abstract void writePIEnd()
                         throws IOException

Throws:: IOException

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

IOException

XMLStreamException

writeCData

public abstract int writeCData(char[] cbuf,
                               int offset,
                               int len)
                        throws IOException,
                               XMLStreamException

Throws:: IOException; XMLStreamException

writeCharacters

public abstract void writeCharacters(String data)
                              throws IOException

Throws:: IOException

writeCharacters

public abstract void writeCharacters(char[] cbuf,
                                     int offset,
                                     int len)
                              throws IOException

Throws:: IOException

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

IOException

XMLStreamException

writeDTD
```
public abstract void writeDTD(String data)
                       throws IOException,
                              XMLStreamException
```
Older "legacy" output method for outputting DOCTYPE declaration. Assumes that the passed-in String contains a complete DOCTYPE declaration properly quoted.

Throws:

IOException

XMLStreamException

writeDTD

public abstract void writeDTD(String rootName,
                              String systemId,
                              String publicId,
                              String internalSubset)
                       throws IOException,
                              XMLStreamException

Throws:: IOException; XMLStreamException

writeEntityReference

public abstract void writeEntityReference(String name)
                                   throws IOException,
                                          XMLStreamException

Throws:: IOException; XMLStreamException

writePI

public abstract int writePI(String target,
                            String data)
                     throws IOException,
                            XMLStreamException

Throws:: IOException; XMLStreamException

writeXmlDeclaration

public abstract void writeXmlDeclaration(String version,
                                         String enc,
                                         String standalone)
                                  throws IOException

Throws:: IOException

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

IOException

XMLStreamException

writeStartTagStart

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

writeStartTagEnd

public abstract void writeStartTagEnd()
                               throws IOException

Throws:: IOException

writeStartTagEmptyEnd

public abstract void writeStartTagEmptyEnd()
                                    throws IOException

Throws:: IOException

writeEndTag

public abstract void writeEndTag(String localName)
                          throws IOException

Throws:: IOException

writeEndTag

public abstract void writeEndTag(String prefix,
                                 String localName)
                          throws IOException

Throws:: IOException

writeAttribute

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

writeAttribute

public abstract void writeAttribute(String localName,
                                    char[] value,
                                    int offset,
                                    int len)
                             throws IOException,
                                    XMLStreamException

Throws:: IOException; XMLStreamException

writeAttribute

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

writeAttribute

public abstract void writeAttribute(String prefix,
                                    String localName,
                                    char[] value,
                                    int offset,
                                    int len)
                             throws IOException,
                                    XMLStreamException

Throws:: IOException; XMLStreamException

writeTypedElement
```
public abstract void writeTypedElement(AsciiValueEncoder enc)
                                throws 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:

IOException

writeTypedElement
```
public abstract void writeTypedElement(AsciiValueEncoder enc,
                                       XMLValidator validator,
                                       char[] copyBuffer)
                                throws IOException,
                                       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:

IOException

XMLStreamException

writeTypedAttribute

public abstract void writeTypedAttribute(String localName,
                                         AsciiValueEncoder enc)
                                  throws IOException,
                                         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:: IOException; XMLStreamException

writeTypedAttribute

public abstract void writeTypedAttribute(String prefix,
                                         String localName,
                                         AsciiValueEncoder enc)
                                  throws IOException,
                                         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:: IOException; XMLStreamException

writeTypedAttribute

public abstract void writeTypedAttribute(String prefix,
                                         String localName,
                                         String nsURI,
                                         AsciiValueEncoder enc,
                                         XMLValidator validator,
                                         char[] copyBuffer)
                                  throws IOException,
                                         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:: IOException; XMLStreamException

getOutputPtr
```
protected abstract int getOutputPtr()
```

getRow
```
public int getRow()
```

getColumn
```
public int getColumn()
```

getAbsOffset
```
public int getAbsOffset()
```

wrapAsRawWriter
```
public final 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 Writer wrapAsTextWriter()

verifyNameValidity

public final void verifyNameValidity(String name,
                                     boolean checkNs)
                              throws XMLStreamException

Method called to verify that the name is a legal XML name.

Throws:: XMLStreamException

reportNwfName
```
protected void reportNwfName(String msg)
                      throws 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:

XMLStreamException

reportNwfName

protected void reportNwfName(String msg,
                             Object arg)
                      throws XMLStreamException

Throws:: XMLStreamException

reportNwfContent

protected void reportNwfContent(String msg)
                         throws XMLStreamException

Throws:: XMLStreamException

throwOutputError

protected void throwOutputError(String msg)
                         throws XMLStreamException

Throws:: XMLStreamException

throwOutputError

protected void throwOutputError(String format,
                                Object arg)
                         throws XMLStreamException

Throws:: XMLStreamException

handleInvalidChar
```
protected char handleInvalidChar(int c)
                          throws 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:

IOException

Class XmlWriter

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SURR1_FIRST

SURR1_LAST

SURR2_FIRST

SURR2_LAST

DEFAULT_QUOTE_CHAR

mConfig

mEncoding

mNsAware

mCheckStructure

mCheckContent

mCheckNames

mFixContent

mAutoCloseOutput

mTextWriter

mAttrValueWriter

mXml11

mRawWrapper

mTextWrapper

mLocPastChars

mLocRowNr

mLocRowStartOffset

Constructor Detail

XmlWriter

Method Detail

enableXml11

getOutputStream

getWriter

close

flush

writeRaw

writeRaw

writeRaw

writeRawAscii

writeCDataStart

writeCDataEnd

writeCommentStart

writeCommentEnd

writePIStart

writePIEnd

writeCData

writeCData

writeCharacters

writeCharacters

writeComment

writeDTD

writeDTD

writeEntityReference

writePI

writeXmlDeclaration

writeStartTagStart

writeStartTagStart

writeStartTagEnd

writeStartTagEmptyEnd

writeEndTag

writeEndTag

writeAttribute

writeAttribute

writeAttribute

writeAttribute

writeTypedElement

writeTypedElement

writeTypedAttribute

writeTypedAttribute

writeTypedAttribute

getOutputPtr

getRow

getColumn

getAbsOffset

wrapAsRawWriter

wrapAsTextWriter

verifyNameValidity

reportNwfName

reportNwfName

reportNwfContent