Class XmlWriter
- java.lang.Object
-
- com.ctc.wstx.sw.XmlWriter
-
- Direct Known Subclasses:
BufferingXmlWriter
,EncodingXmlWriter
public abstract class XmlWriter extends java.lang.Object
This is the base class for actual physical xml outputters. These instances will only handle actual writing (possibly including encoding) of the serialized textual xml, and will in general not verify content being output. The exception are the character-by-character checks that are most efficiently done at encoding level (such as character escaping, and checks for illegal character combinations), which are handled at this level.Note that implementations can have different operating modes: specifically, when dealing with illegal content (such as "--" in a comment,
"?>"
in processing instruction, or"]]>"
within CDATA section), implementations can do one of 3 things:- Fix the problem, by splitting the section (which can be done for CDATA sections, and to some degree, comments)
- Stop outputting, and return an index to the illegal piece of data (if there is no easy way to fix the problem: for example, for processing instruction)
- Just output content even though it will not result in well-formed output. This should only be done if the calling application has specifically requested verifications to be disabled.
-
-
Field Summary
Fields Modifier and Type Field Description protected static char
DEFAULT_QUOTE_CHAR
(package private) boolean
mAddSpaceAfterEmptyElem
Whether to add a space after empty element (before closing "/>") or not.protected java.io.Writer
mAttrValueWriter
Optional escaping writer used for escaping characters like '"' '&' and '<' in attribute values.protected boolean
mAutoCloseOutput
Flag that defines whether close() on this writer should call close on the underlying output object (stream, writer)protected boolean
mCheckContent
protected boolean
mCheckNames
protected boolean
mCheckStructure
protected WriterConfig
mConfig
protected java.lang.String
mEncoding
(package private) boolean
mEscapeCR
Whether to escape CR (\r) character.protected boolean
mFixContent
protected int
mLocPastChars
Number of characters output prior to currently buffered outputprotected 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 matchingwriteRaw
methods of this XmlWriter instance.protected XmlWriterWrapper
mTextWrapper
Lazy-constructed wrapper object, which will route all calls to Writer API, to matchingwriteCharacters
methods of this XmlWriter instance.protected java.io.Writer
mTextWriter
Optional escaping writer used for escaping characters like '<' '&' and '>' in textual content.(package private) boolean
mUseDoubleQuotesInXmlDecl
Whether to use double quotes in XML declaration or not.protected boolean
mXml11
Indicates whether output is to be compliant; if false, is to be xml 1.0 compliant, if true, xml 1.1 compliant.protected static int
SURR1_FIRST
protected static int
SURR1_LAST
protected static int
SURR2_FIRST
protected static int
SURR2_LAST
-
Constructor Summary
Constructors Modifier Constructor Description protected
XmlWriter(WriterConfig cfg, java.lang.String encoding, boolean autoclose)
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract void
close(boolean forceRealClose)
Method called to flush the buffer(s), and close the output sink (stream or writer) if enabled (auto-closing) or forced.void
enableXml11()
abstract void
flush()
int
getAbsOffset()
int
getColumn()
protected abstract int
getOutputPtr()
protected abstract java.io.OutputStream
getOutputStream()
int
getRow()
protected abstract java.io.Writer
getWriter()
protected char
handleInvalidChar(int c)
Method called to handle invalid character in textual content requested to be output.protected void
reportNwfContent(java.lang.String msg)
protected void
reportNwfName(java.lang.String msg)
This is the method called when an output method call violates name well-formedness checks andWstxOutputProperties.P_OUTPUT_VALIDATE_NAMES
is is enabled.protected void
throwOutputError(java.lang.String msg)
protected void
throwOutputError(java.lang.String format, java.lang.Object arg)
void
verifyNameValidity(java.lang.String name, boolean checkNs)
Method called to verify that the name is a legal XML name.java.io.Writer
wrapAsRawWriter()
Method that can be called to get a wrapper instance that can be used to essentially call thewriteRaw
method.java.io.Writer
wrapAsTextWriter()
abstract void
writeAttribute(java.lang.String localName, char[] value, int offset, int len)
abstract void
writeAttribute(java.lang.String localName, java.lang.String value)
Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)abstract void
writeAttribute(java.lang.String prefix, java.lang.String localName, char[] value, int offset, int len)
abstract void
writeAttribute(java.lang.String prefix, java.lang.String localName, java.lang.String value)
Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)abstract int
writeCData(char[] cbuf, int offset, int len)
abstract int
writeCData(java.lang.String data)
abstract void
writeCDataEnd()
abstract void
writeCDataStart()
abstract void
writeCharacters(char[] cbuf, int offset, int len)
abstract void
writeCharacters(java.lang.String data)
abstract int
writeComment(java.lang.String data)
Method that will try to output the content as specified.abstract void
writeCommentEnd()
abstract void
writeCommentStart()
abstract void
writeDTD(java.lang.String data)
Older "legacy" output method for outputting DOCTYPE declaration.abstract void
writeDTD(java.lang.String rootName, java.lang.String systemId, java.lang.String publicId, java.lang.String internalSubset)
abstract void
writeEndTag(java.lang.String localName)
abstract void
writeEndTag(java.lang.String prefix, java.lang.String localName)
abstract void
writeEntityReference(java.lang.String name)
abstract int
writePI(java.lang.String target, java.lang.String data)
abstract void
writePIEnd()
abstract void
writePIStart(java.lang.String target, boolean addSpace)
abstract void
writeRaw(char[] cbuf, int offset, int len)
void
writeRaw(java.lang.String str)
abstract void
writeRaw(java.lang.String str, int offset, int len)
abstract void
writeRawAscii(char[] cbuf, int offset, int len)
LikewriteRaw(java.lang.String, int, int)
, but caller guarantees that the contents additionally are known to be in 7-bit ascii range.abstract void
writeStartTagEmptyEnd()
abstract void
writeStartTagEnd()
abstract void
writeStartTagStart(java.lang.String localName)
Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)abstract void
writeStartTagStart(java.lang.String prefix, java.lang.String localName)
Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)abstract void
writeTypedAttribute(java.lang.String prefix, java.lang.String localName, java.lang.String nsURI, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc, org.codehaus.stax2.validation.XMLValidator validator, char[] copyBuffer)
Method similar towriteAttribute(String,String,char[],int,int)
but where is known not to require escaping.abstract void
writeTypedAttribute(java.lang.String prefix, java.lang.String localName, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
Method similar towriteAttribute(String,String,char[],int,int)
but where is known not to require escaping.abstract void
writeTypedAttribute(java.lang.String localName, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
Method similar towriteAttribute(String,String,char[],int,int)
but where is known not to require escaping.abstract void
writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc)
LikewriteRaw(java.lang.String, int, int)
, but caller guarantees that the contents additionally are known to be in 7-bit ascii range, and also passes an encoder object that will encode values only when being handed a buffer to append to.abstract void
writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc, org.codehaus.stax2.validation.XMLValidator validator, char[] copyBuffer)
LikewriteRaw(java.lang.String, int, int)
, but caller guarantees that the contents additionally are known to be in 7-bit ascii range, and also passes an encoder object that will encode values only when being handed a buffer to append to.abstract void
writeXmlDeclaration(java.lang.String version, java.lang.String enc, java.lang.String standalone)
-
-
-
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 java.lang.String mEncoding
-
mNsAware
protected final boolean mNsAware
-
mCheckStructure
protected final boolean mCheckStructure
-
mCheckContent
protected final boolean mCheckContent
-
mCheckNames
protected final boolean mCheckNames
-
mFixContent
protected final boolean mFixContent
-
mEscapeCR
final boolean mEscapeCR
Whether to escape CR (\r) character.
-
mAddSpaceAfterEmptyElem
final boolean mAddSpaceAfterEmptyElem
Whether to add a space after empty element (before closing "/>") or not.
-
mUseDoubleQuotesInXmlDecl
final boolean mUseDoubleQuotesInXmlDecl
Whether to use double quotes in XML declaration or not.
-
mAutoCloseOutput
protected final boolean mAutoCloseOutput
Flag that defines whether close() on this writer should call close on the underlying output object (stream, writer)
-
mTextWriter
protected java.io.Writer mTextWriter
Optional escaping writer used for escaping characters like '<' '&' and '>' in textual content. Constructed if calling code has installed a special escaping writer factory for text content. Null if the default escaper is to be used.
-
mAttrValueWriter
protected java.io.Writer mAttrValueWriter
Optional escaping writer used for escaping characters like '"' '&' and '<' in attribute values. Constructed if calling code has installed a special escaping writer factory for text content. Null if the default escaper is to be used.
-
mXml11
protected boolean mXml11
Indicates whether output is to be compliant; if false, is to be xml 1.0 compliant, if true, xml 1.1 compliant.
-
mRawWrapper
protected XmlWriterWrapper mRawWrapper
Lazy-constructed wrapper object, which will route all calls to Writer API, to matchingwriteRaw
methods of this XmlWriter instance.
-
mTextWrapper
protected XmlWriterWrapper mTextWrapper
Lazy-constructed wrapper object, which will route all calls to Writer API, to matchingwriteCharacters
methods of this XmlWriter instance.
-
mLocPastChars
protected int mLocPastChars
Number of characters output prior to currently buffered output
-
mLocRowNr
protected int mLocRowNr
-
mLocRowStartOffset
protected int mLocRowStartOffset
Offset of the first character on this line. May be negative, if the offset was in a buffer that has been flushed out.
-
-
Constructor Detail
-
XmlWriter
protected XmlWriter(WriterConfig cfg, java.lang.String encoding, boolean autoclose) throws java.io.IOException
- Throws:
java.io.IOException
-
-
Method Detail
-
enableXml11
public void enableXml11()
-
getOutputStream
protected abstract java.io.OutputStream getOutputStream()
- Returns:
- Underlying OutputStream used for physical output, if the writer was constructed using one
-
getWriter
protected abstract java.io.Writer getWriter()
- Returns:
- Underlying Writer used for physical output, if the writer was constructed with one, or one was created to be used with an OutputStream.
-
close
public abstract void close(boolean forceRealClose) throws java.io.IOException
Method called to flush the buffer(s), and close the output sink (stream or writer) if enabled (auto-closing) or forced.- Throws:
java.io.IOException
-
flush
public abstract void flush() throws java.io.IOException
- Throws:
java.io.IOException
-
writeRaw
public abstract void writeRaw(java.lang.String str, int offset, int len) throws java.io.IOException
- Throws:
java.io.IOException
-
writeRaw
public void writeRaw(java.lang.String str) throws java.io.IOException
- Throws:
java.io.IOException
-
writeRaw
public abstract void writeRaw(char[] cbuf, int offset, int len) throws java.io.IOException
- Throws:
java.io.IOException
-
writeRawAscii
public abstract void writeRawAscii(char[] cbuf, int offset, int len) throws java.io.IOException
LikewriteRaw(java.lang.String, int, int)
, but caller guarantees that the contents additionally are known to be in 7-bit ascii range.- Throws:
java.io.IOException
-
writeCDataStart
public abstract void writeCDataStart() throws java.io.IOException
- Throws:
java.io.IOException
-
writeCDataEnd
public abstract void writeCDataEnd() throws java.io.IOException
- Throws:
java.io.IOException
-
writeCommentStart
public abstract void writeCommentStart() throws java.io.IOException
- Throws:
java.io.IOException
-
writeCommentEnd
public abstract void writeCommentEnd() throws java.io.IOException
- Throws:
java.io.IOException
-
writePIStart
public abstract void writePIStart(java.lang.String target, boolean addSpace) throws java.io.IOException
- Throws:
java.io.IOException
-
writePIEnd
public abstract void writePIEnd() throws java.io.IOException
- Throws:
java.io.IOException
-
writeCData
public abstract int writeCData(java.lang.String data) throws java.io.IOException, javax.xml.stream.XMLStreamException
- Parameters:
data
- Contents of the CDATA section to write out- Returns:
- offset of the (first) illegal content segment ("]]>") in passed content and not in repairing mode; or -1 if none or is repairing
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeCData
public abstract int writeCData(char[] cbuf, int offset, int len) throws java.io.IOException, javax.xml.stream.XMLStreamException
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeCharacters
public abstract void writeCharacters(java.lang.String data) throws java.io.IOException
- Throws:
java.io.IOException
-
writeCharacters
public abstract void writeCharacters(char[] cbuf, int offset, int len) throws java.io.IOException
- Throws:
java.io.IOException
-
writeComment
public abstract int writeComment(java.lang.String data) throws java.io.IOException, javax.xml.stream.XMLStreamException
Method that will try to output the content as specified. If the content passed in has embedded "--" in it, it will either add an intervening space between consequtive hyphens (if content fixing is enabled), or return the offset of the first hyphen in multi-hyphen sequence.- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeDTD
public abstract void writeDTD(java.lang.String data) throws java.io.IOException, javax.xml.stream.XMLStreamException
Older "legacy" output method for outputting DOCTYPE declaration. Assumes that the passed-in String contains a complete DOCTYPE declaration properly quoted.- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeDTD
public abstract void writeDTD(java.lang.String rootName, java.lang.String systemId, java.lang.String publicId, java.lang.String internalSubset) throws java.io.IOException, javax.xml.stream.XMLStreamException
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeEntityReference
public abstract void writeEntityReference(java.lang.String name) throws java.io.IOException, javax.xml.stream.XMLStreamException
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writePI
public abstract int writePI(java.lang.String target, java.lang.String data) throws java.io.IOException, javax.xml.stream.XMLStreamException
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeXmlDeclaration
public abstract void writeXmlDeclaration(java.lang.String version, java.lang.String enc, java.lang.String standalone) throws java.io.IOException
- Throws:
java.io.IOException
-
writeStartTagStart
public abstract void writeStartTagStart(java.lang.String localName) throws java.io.IOException, javax.xml.stream.XMLStreamException
Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeStartTagStart
public abstract void writeStartTagStart(java.lang.String prefix, java.lang.String localName) throws java.io.IOException, javax.xml.stream.XMLStreamException
Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeStartTagEnd
public abstract void writeStartTagEnd() throws java.io.IOException
- Throws:
java.io.IOException
-
writeStartTagEmptyEnd
public abstract void writeStartTagEmptyEnd() throws java.io.IOException
- Throws:
java.io.IOException
-
writeEndTag
public abstract void writeEndTag(java.lang.String localName) throws java.io.IOException
- Throws:
java.io.IOException
-
writeEndTag
public abstract void writeEndTag(java.lang.String prefix, java.lang.String localName) throws java.io.IOException
- Throws:
java.io.IOException
-
writeAttribute
public abstract void writeAttribute(java.lang.String localName, java.lang.String value) throws java.io.IOException, javax.xml.stream.XMLStreamException
Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeAttribute
public abstract void writeAttribute(java.lang.String localName, char[] value, int offset, int len) throws java.io.IOException, javax.xml.stream.XMLStreamException
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeAttribute
public abstract void writeAttribute(java.lang.String prefix, java.lang.String localName, java.lang.String value) throws java.io.IOException, javax.xml.stream.XMLStreamException
Note: can throw XMLStreamException, if name checking is enabled, and name is invalid (name check has to be in this writer, not caller, since it depends not only on xml limitations, but also on encoding limitations)
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeAttribute
public abstract void writeAttribute(java.lang.String prefix, java.lang.String localName, char[] value, int offset, int len) throws java.io.IOException, javax.xml.stream.XMLStreamException
- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeTypedElement
public abstract void writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc) throws java.io.IOException
LikewriteRaw(java.lang.String, int, int)
, but caller guarantees that the contents additionally are known to be in 7-bit ascii range, and also passes an encoder object that will encode values only when being handed a buffer to append to.- Parameters:
enc
- Encoder that will produce content- Throws:
java.io.IOException
-
writeTypedElement
public abstract void writeTypedElement(org.codehaus.stax2.ri.typed.AsciiValueEncoder enc, org.codehaus.stax2.validation.XMLValidator validator, char[] copyBuffer) throws java.io.IOException, javax.xml.stream.XMLStreamException
LikewriteRaw(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 contentvalidator
- Validator to use for validating serialized textual content (can not be null)copyBuffer
- Temporary buffer that writer can use for temporary copies as necessary- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeTypedAttribute
public abstract void writeTypedAttribute(java.lang.String localName, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc) throws java.io.IOException, javax.xml.stream.XMLStreamException
Method similar towriteAttribute(String,String,char[],int,int)
but where is known not to require escaping. No validation needs to be performed.- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeTypedAttribute
public abstract void writeTypedAttribute(java.lang.String prefix, java.lang.String localName, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc) throws java.io.IOException, javax.xml.stream.XMLStreamException
Method similar towriteAttribute(String,String,char[],int,int)
but where is known not to require escaping. No validation needs to be performed.- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
writeTypedAttribute
public abstract void writeTypedAttribute(java.lang.String prefix, java.lang.String localName, java.lang.String nsURI, org.codehaus.stax2.ri.typed.AsciiValueEncoder enc, org.codehaus.stax2.validation.XMLValidator validator, char[] copyBuffer) throws java.io.IOException, javax.xml.stream.XMLStreamException
Method similar towriteAttribute(String,String,char[],int,int)
but where is known not to require escaping. Validation of the attribute value must be done by calling given validator appropriately.- Throws:
java.io.IOException
javax.xml.stream.XMLStreamException
-
getOutputPtr
protected abstract int getOutputPtr()
-
getRow
public int getRow()
-
getColumn
public int getColumn()
-
getAbsOffset
public int getAbsOffset()
-
wrapAsRawWriter
public final java.io.Writer wrapAsRawWriter()
Method that can be called to get a wrapper instance that can be used to essentially call thewriteRaw
method.
-
wrapAsTextWriter
public final java.io.Writer wrapAsTextWriter()
-
verifyNameValidity
public final void verifyNameValidity(java.lang.String name, boolean checkNs) throws javax.xml.stream.XMLStreamException
Method called to verify that the name is a legal XML name.- Throws:
javax.xml.stream.XMLStreamException
-
reportNwfName
protected void reportNwfName(java.lang.String msg) throws javax.xml.stream.XMLStreamException
This is the method called when an output method call violates name well-formedness checks andWstxOutputProperties.P_OUTPUT_VALIDATE_NAMES
is is enabled.- Throws:
javax.xml.stream.XMLStreamException
-
reportNwfContent
protected void reportNwfContent(java.lang.String msg) throws javax.xml.stream.XMLStreamException
- Throws:
javax.xml.stream.XMLStreamException
-
throwOutputError
protected void throwOutputError(java.lang.String msg) throws javax.xml.stream.XMLStreamException
- Throws:
javax.xml.stream.XMLStreamException
-
throwOutputError
protected void throwOutputError(java.lang.String format, java.lang.Object arg) throws javax.xml.stream.XMLStreamException
- Throws:
javax.xml.stream.XMLStreamException
-
handleInvalidChar
protected char handleInvalidChar(int c) throws java.io.IOException
Method called to handle invalid character in textual content requested to be output. Content may be part of textual events (CHARACTER, CDATA), attribute value, COMMENT content or PROCESSING_INSTRUCTION data. The default behavior is to just throw an exception, but this can be configured via propertyWstxOutputProperties.P_OUTPUT_INVALID_CHAR_HANDLER
.- Throws:
java.io.IOException
-
-