com.ctc.wstx.sw
Class XmlWriter

java.lang.Object
  extended by 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:


Field Summary
protected static char DEFAULT_QUOTE_CHAR
           
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
           
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  java.io.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
protected XmlWriter(WriterConfig cfg, java.lang.String encoding, boolean autoclose)
           
 
Method Summary
abstract  void close()
          Method called to flush the buffer(s), and close the output sink (stream or writer).
 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  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 and WstxOutputProperties.P_OUTPUT_VALIDATE_NAMES is is enabled.
protected  void reportNwfName(java.lang.String msg, java.lang.Object arg)
           
protected  void throwInvalidChar(int c)
           
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 the writeRaw 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 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 writeXmlDeclaration(java.lang.String version, java.lang.String enc, java.lang.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 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

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 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,
                    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()
                    throws java.io.IOException
Method called to flush the buffer(s), and close the output sink (stream or writer).

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

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, if not in repairing mode; or -1 if none
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

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 the writeRaw 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 and WstxOutputProperties.P_OUTPUT_VALIDATE_NAMES is is enabled.

Throws:
javax.xml.stream.XMLStreamException

reportNwfName

protected void reportNwfName(java.lang.String msg,
                             java.lang.Object arg)
                      throws javax.xml.stream.XMLStreamException
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

throwInvalidChar

protected void throwInvalidChar(int c)
                         throws java.io.IOException
Throws:
java.io.IOException