org.apache.commons.xmlio.out
Class XMLWriter

java.lang.Object
  extended by java.io.Writer
      extended by java.io.FilterWriter
          extended by org.apache.commons.xmlio.out.XMLWriter
All Implemented Interfaces:
Closeable, Flushable, Appendable
Direct Known Subclasses:
XMLOutputStreamWriter, XMLStringWriter

public class XMLWriter
extends FilterWriter

FilterWriter adding formatted and encoded XML export functionality to the underlying writer. Formatting and encoding is done as straight forward as possible.
Everything you know better than this class must be done by you, e.g. you will have to tell XMLWriter where you wish to have newlines.In effect, no unexpected so called intelligent behavior is to be feared. Another effect is high speed.

A simple example: Suppose your XMLWriter object is xmlWriter. The following sequence of code

  xmlWriter.writeStartTag("<root>");
  xmlWriter.writeStartTag("<next1>", false);
  xmlWriter.writeEmptyTag("<emptyTag/>", false);
  xmlWriter.writeEndTag("</next1>");
  xmlWriter.writeStartTag("</root>");

will write this to the underlying writer

<root>
  <next1><emptyTag/></next1>
</root>


Caution: Do not forget to call FilterWriter.flush() at the end of your exporting process as otherwise no data might be written.


Field Summary
protected  int depth
          Current depth of the tree.
protected  int indent
          Current indentation.
static boolean NEWLINE
           
protected  boolean nlAfterEmptyTag
           
protected  boolean nlAfterEndTag
           
protected  boolean nlAfterStartTag
           
static boolean NO_NEWLINE
           
protected  boolean prettyPrintMode
           
protected  int tabWidth
           
protected  boolean xmlDeclWritten
          Flag indicating if the XML declaration has already been writter.
 
Fields inherited from class java.io.FilterWriter
out
 
Fields inherited from class java.io.Writer
lock
 
Constructor Summary
XMLWriter(Writer writer)
          Creates a new filter writer for XML export.
 
Method Summary
static String createEmptyTag(String tagName)
          Convenience method for creating an empty tag having no attributes.
static String createEmptyTag(String tagName, Attributes attributes)
          Convenience method for creating an empty tag.
static String createEmptyTag(String tagName, String[][] attrPairs)
          Convenience method for creating an empty tag.
static String createEmptyTag(String tagName, String[] attrNames, String[] attrValues)
          Convenience method for creating an empty tag.
static String createEmptyTag(String tagName, String attrName, String attrValue)
          Convenience method for creating an empty tag.
static String createEndTag(String tagName)
          Convenience method for creating an end tag.
static String createStartTag(String tagName)
          Convenience method for creating a start tag having no attributes.
static String createStartTag(String tagName, Attributes attributes)
          Convenience method for creating a start tag.
static String createStartTag(String tagName, Attributes attributes, boolean isEmpty)
          Convenience method for creating a start tag.
static String createStartTag(String tagName, Attributes attributes, boolean isEmpty, boolean encodeAttrs, char quoteChar)
          Convenience method for creating a start tag.
static String createStartTag(String tagName, String[][] attrPairs)
          Convenience method for creating a non empty start tag.
static String createStartTag(String tagName, String[][] attrPairs, boolean isEmpty)
          Convenience method for creating a start tag.
static String createStartTag(String tagName, String[][] attrPairs, boolean isEmpty, boolean encodeAttrs, char quoteChar)
          Convenience method for creating a start tag.
static String createStartTag(String tagName, String[] attrNames, String[] attrValues)
          Convenience method for creating a non empty start tag.
static String createStartTag(String tagName, String[] attrNames, String[] attrValues, boolean isEmpty)
          Convenience method for creating a start tag.
static String createStartTag(String tagName, String[] attrNames, String[] attrValues, boolean isEmpty, boolean encodeAttrs, char quoteChar)
          Convenience method for creating a start tag.
static String createStartTag(String tagName, String attrName, String attrValue)
          Convenience method for creating a non empty start tag.
static String createStartTag(String tagName, String attrName, String attrValue, boolean isEmpty)
          Convenience method for creating a start tag.
static void generateAndWriteElementWithCData(XMLWriter xmlWriter, String tagName, String[][] attrPairs, String cData)
          Convenience method for creating and writing a whole element.
static void generateAndWriteElementWithCData(XMLWriter xmlWriter, String tagName, String[] attrNames, String[] attrValues, String cData)
          Convenience method for creating and writing a whole element.
 boolean getNlAfterEmptyTag()
          Gets property described in setNlAfterEmptyTag(boolean).
 boolean getNlAfterEndTag()
          Gets property described in setNlAfterEndTag(boolean).
 boolean getNlAfterStartTag()
          Gets property described in setNlAfterStartTag(boolean).
 boolean getPrettyPrintMode()
          Gets property described in setPrettyPrintMode(boolean).
 int getTabWidth()
          Gets property described in setTabWidth(int).
 boolean isXMLDeclarationWritten()
          Indicates whether the XML declaration has been written, yet.
 void setNlAfterEmptyTag(boolean nlAfterEmptyTag)
          Sets if a newline is inserted after an empty start element by default.
 void setNlAfterEndTag(boolean nlAfterEndTag)
          Sets if a newline is inserted after an end tag by default.
 void setNlAfterStartTag(boolean nlAfterStartTag)
          Sets if a newline is inserted after a non empty start tag by default.
 void setPrettyPrintMode(boolean prettyPrintMode)
          Switches on/off pretty print mode.
 void setTabWidth(int tabWidth)
          Sets the amount of spaces to increase indentation with element level.
 void setXMLDeclarationWritten(boolean xmlDeclWritten)
          Manually sets or resets whether XML declaration has been written.
 void writeCData(String cData)
          Writes character data with encoding.
 void writeComment(String comment)
          Writes comment encoded as comment.
 void writeElementWithCData(String startTag, String cData, String endTag)
          Writes a full element consisting of a start tag, character data and an end tag.
 void writeElementWithPCData(String startTag, String pcData, String endTag)
          Writes a full element consisting of a start tag, character data and an end tag.
 void writeEmptyElement(String emptyTag)
          Writes an empty element.
 void writeEmptyElement(String emptyTag, boolean nl)
          Writes an empty element.
 void writeEndTag(String endTag)
          Writes an end tag.
 void writeEndTag(String endTag, boolean nl)
          Writes an end tag.
 void writeNl()
          Writes a single newline.
 void writePCData(String pcData)
          Writes character data without encoding.
 void writePI(String target, String data)
          Writes a processing instruction.
 void writeProlog(String prolog)
          Writes prolog data like doctype delcaration and DTD parts followed by a newline.
 void writeStartTag(String startTag)
          Writes a start tag.
 void writeStartTag(String startTag, boolean nl)
          Writes a start tag.
 void writeXMLDeclaration()
          Writes XML declaration.
 
Methods inherited from class java.io.FilterWriter
close, flush, write, write, write
 
Methods inherited from class java.io.Writer
append, append, append, append, append, append, write, write
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NEWLINE

public static final boolean NEWLINE
See Also:
Constant Field Values

NO_NEWLINE

public static final boolean NO_NEWLINE
See Also:
Constant Field Values

tabWidth

protected int tabWidth

depth

protected int depth
Current depth of the tree. Do not know what this is good for, but who knows...


indent

protected int indent
Current indentation. Depth does not contain sufficient information as tabWidth may change during output (should not).


prettyPrintMode

protected boolean prettyPrintMode

nlAfterEmptyTag

protected boolean nlAfterEmptyTag

nlAfterStartTag

protected boolean nlAfterStartTag

nlAfterEndTag

protected boolean nlAfterEndTag

xmlDeclWritten

protected boolean xmlDeclWritten
Flag indicating if the XML declaration has already been writter. Check this using isXMLDeclarationWritten(). It might be useful to avoid writing twice or more times in different contexts writing to same writer.
Caution: If you subclass, be sure to set this in writeXMLDeclaration().

Constructor Detail

XMLWriter

public XMLWriter(Writer writer)
Creates a new filter writer for XML export.

Parameters:
writer - the underlying writer the formatted XML is exported to
Method Detail

createEndTag

public static final String createEndTag(String tagName)
Convenience method for creating an end tag.

Parameters:
tagName - name of the end tag

createStartTag

public static final String createStartTag(String tagName)
Convenience method for creating a start tag having no attributes.

Parameters:
tagName - name of the start tag

createEmptyTag

public static final String createEmptyTag(String tagName)
Convenience method for creating an empty tag having no attributes. E.g. <tagName/>.

Parameters:
tagName - name of the tag

createStartTag

public static final String createStartTag(String tagName,
                                          String[] attrNames,
                                          String[] attrValues,
                                          boolean isEmpty)
Convenience method for creating a start tag.

Parameters:
tagName - name of the start tag
attrNames - names of attributes to be included into start tag
attrValues - values of attributes to be included into start tag - there should be just as many entries as in attrNames, if a value is null corresponding attribute will not be included
isEmpty - decides wheter this is start tag is for an empty element

createStartTag

public static final String createStartTag(String tagName,
                                          String[] attrNames,
                                          String[] attrValues)
Convenience method for creating a non empty start tag.

Parameters:
tagName - name of the start tag
attrNames - names of attributes to be included into start tag
attrValues - values of attributes to be included into start tag - there should be just as many entries as in attrNames, if a value is null corresponding attribute will not be included

createEmptyTag

public static final String createEmptyTag(String tagName,
                                          String[] attrNames,
                                          String[] attrValues)
Convenience method for creating an empty tag.

Parameters:
tagName - name of the tag
attrNames - names of attributes to be included into tag
attrValues - values of attributes to be included into tag - there should be just as many entries as in attrNames, if a value is null corresponding attribute will not be included
See Also:
createEmptyTag(String)

createStartTag

public static final String createStartTag(String tagName,
                                          String attrName,
                                          String attrValue,
                                          boolean isEmpty)
Convenience method for creating a start tag.

Parameters:
tagName - name of the start tag
attrName - name of attribute to be included into start tag
attrValue - value of attribute to be included into start tag, if attrValue is null attribute will not be included
isEmpty - decides wheter this is start tag is for an empty element

createStartTag

public static final String createStartTag(String tagName,
                                          String attrName,
                                          String attrValue)
Convenience method for creating a non empty start tag.

Parameters:
tagName - name of the start tag
attrName - name of attribute to be included into start tag
attrValue - value of attribute to be included into start tag, if attrValue is null attribute will not be included

createEmptyTag

public static final String createEmptyTag(String tagName,
                                          String attrName,
                                          String attrValue)
Convenience method for creating an empty tag.

Parameters:
tagName - name of the tag
attrName - name of attribute to be included into tag
attrValue - value of attribute to be included into tag, if attrValue is null attribute will not be included
See Also:
createEmptyTag(String)

createStartTag

public static final String createStartTag(String tagName,
                                          String[] attrNames,
                                          String[] attrValues,
                                          boolean isEmpty,
                                          boolean encodeAttrs,
                                          char quoteChar)
Convenience method for creating a start tag.

Parameters:
tagName - name of the start tag
attrNames - names of attributes to be included into start tag
attrValues - values of attributes to be included into start tag - there should be just as many entries as in attrNames, if a value is null corresponding attribute will not be included
isEmpty - decides wheter this is start tag is for an empty element
encodeAttrs - set this to have your attribute values encoded for XML
quoteChar - if you choose encoding this is the char that quotes your attributes

createStartTag

public static final String createStartTag(String tagName,
                                          String[][] attrPairs,
                                          boolean isEmpty)
Convenience method for creating a start tag.

Parameters:
tagName - name of the start tag
attrPairs - name/value pairs of attributes to be included into start tag - if a value is null corresponding attribute will not be included
isEmpty - decides wheter this is start tag is for an empty element

createStartTag

public static final String createStartTag(String tagName,
                                          String[][] attrPairs)
Convenience method for creating a non empty start tag.

Parameters:
tagName - name of the start tag
attrPairs - name/value pairs of attributes to be included into start tag - if a value is null corresponding attribute will not be included

createEmptyTag

public static final String createEmptyTag(String tagName,
                                          String[][] attrPairs)
Convenience method for creating an empty tag.

Parameters:
tagName - name of the tag
attrPairs - name/value pairs of attributes to be included into tag - if a value is null corresponding attribute will not be included
See Also:
createEmptyTag(String)

createStartTag

public static final String createStartTag(String tagName,
                                          String[][] attrPairs,
                                          boolean isEmpty,
                                          boolean encodeAttrs,
                                          char quoteChar)
Convenience method for creating a start tag.

Parameters:
tagName - name of the start tag
attrPairs - name/value pairs of attributes to be included into start tag - if a value is null corresponding attribute will not be included
isEmpty - decides wheter this is start tag is for an empty element
encodeAttrs - set this to have your attribute values encoded for XML
quoteChar - if you choose encoding this is the char that quotes your attributes

createEmptyTag

public static final String createEmptyTag(String tagName,
                                          Attributes attributes)
Convenience method for creating an empty tag.

Parameters:
tagName - name of the tag
attributes - SAX attributes to be included into start tag
See Also:
createEmptyTag(String)

createStartTag

public static final String createStartTag(String tagName,
                                          Attributes attributes)
Convenience method for creating a start tag.

Parameters:
tagName - name of the start tag
attributes - SAX attributes to be included into start tag

createStartTag

public static final String createStartTag(String tagName,
                                          Attributes attributes,
                                          boolean isEmpty)
Convenience method for creating a start tag.

Parameters:
tagName - name of the start tag
attributes - SAX attributes to be included into start tag
isEmpty - decides wheter this is start tag is for an empty element

createStartTag

public static final String createStartTag(String tagName,
                                          Attributes attributes,
                                          boolean isEmpty,
                                          boolean encodeAttrs,
                                          char quoteChar)
Convenience method for creating a start tag.

Parameters:
tagName - name of the start tag
attributes - SAX attributes to be included into start tag
isEmpty - decides wheter this is start tag is for an empty element
encodeAttrs - set this to have your attribute values encoded for XML
quoteChar - if you choose encoding this is the char that quotes your attributes

generateAndWriteElementWithCData

public static final void generateAndWriteElementWithCData(XMLWriter xmlWriter,
                                                          String tagName,
                                                          String[][] attrPairs,
                                                          String cData)
                                                   throws IOException
Convenience method for creating and writing a whole element. Added to normal non-static write methods purely for my own laziness.
It is non-static as it differs from all other write methods as it combines generating and writing. This is normally avoided to keep every everything simple, clear and fast.

You can write
XMLOutputStreamWriter.generateAndWriteElementWithCData(writer, "tag", "cdata");

to generate
<tag>cdata</tag>

Parameters:
xmlWriter - writer to write generated stuff to
tagName - name of the element
attrPairs - name/value pairs of attributes to be included into start tag - if a value is null corresponding attribute will not be included
cData - the character data of the element
Throws:
IOException
See Also:
writeElementWithCData(String, String, String), createStartTag(String, String[][]), createEndTag(String)

generateAndWriteElementWithCData

public static final void generateAndWriteElementWithCData(XMLWriter xmlWriter,
                                                          String tagName,
                                                          String[] attrNames,
                                                          String[] attrValues,
                                                          String cData)
                                                   throws IOException
Convenience method for creating and writing a whole element.

Parameters:
xmlWriter - writer to write generated stuff to
tagName - name of the element
attrNames - names of attributes to be included into start tag
attrValues - values of attributes to be included into start tag - there should be just as many entries as in attrNames, if a value is null corresponding attribute will not be included
cData - the character data of the element
Throws:
IOException
See Also:
generateAndWriteElementWithCData(XMLWriter, String, String[][], String), writeElementWithCData(String, String, String), createStartTag(String, String[], String[]), createEndTag(String)

setPrettyPrintMode

public void setPrettyPrintMode(boolean prettyPrintMode)
Switches on/off pretty print mode.
Having it switched on (which is the default) makes output pretty as newlines after tags and indentataion is done. Unfortunately, if your application is sensible to whitespace in CDATA this might lead to unwanted additional spaces and newlines.
If it is switched off the output is guaranteed to be correct, but looks pretty funny. After before markup close (> or />) a newline is inserted as otherwise you may get extremely long output lines.


getPrettyPrintMode

public boolean getPrettyPrintMode()
Gets property described in setPrettyPrintMode(boolean).


setTabWidth

public void setTabWidth(int tabWidth)
Sets the amount of spaces to increase indentation with element level.
This only takes effect when setPrettyPrintMode(boolean) is set to true.
Caution: You should better avoid to change this property while exporting as this may result in unexpected output.


getTabWidth

public int getTabWidth()
Gets property described in setTabWidth(int).


setNlAfterEmptyTag

public void setNlAfterEmptyTag(boolean nlAfterEmptyTag)
Sets if a newline is inserted after an empty start element by default.


getNlAfterEmptyTag

public boolean getNlAfterEmptyTag()
Gets property described in setNlAfterEmptyTag(boolean).


setNlAfterEndTag

public void setNlAfterEndTag(boolean nlAfterEndTag)
Sets if a newline is inserted after an end tag by default.


getNlAfterEndTag

public boolean getNlAfterEndTag()
Gets property described in setNlAfterEndTag(boolean).


setNlAfterStartTag

public void setNlAfterStartTag(boolean nlAfterStartTag)
Sets if a newline is inserted after a non empty start tag by default.


getNlAfterStartTag

public boolean getNlAfterStartTag()
Gets property described in setNlAfterStartTag(boolean).


writeXMLDeclaration

public void writeXMLDeclaration()
                         throws IOException
Writes XML declaration. XML declaration will be written using version 1.0 and no encoding defaulting to standard encoding (supports UTF-8 and UTF-16):
<?xml version="1.0"?>
If you want to have a different encoding or the standalone declaration use writeProlog(String).
This sets xmlDeclWritten to true.

Throws:
IOException

isXMLDeclarationWritten

public boolean isXMLDeclarationWritten()
Indicates whether the XML declaration has been written, yet. As it may only be written once, you can check this when writing in different contexts to same writer.


setXMLDeclarationWritten

public void setXMLDeclarationWritten(boolean xmlDeclWritten)
Manually sets or resets whether XML declaration has been written. This is done implicly by writeXMLDeclaration(), but to give you the full freedom, this can be done here as well. Use isXMLDeclarationWritten() to check it.


writeProlog

public void writeProlog(String prolog)
                 throws IOException
Writes prolog data like doctype delcaration and DTD parts followed by a newline.
Do not misuse this to write plain text, but rather - if you really have to - use the standard FilterWriter.write(int) methods.

Throws:
IOException

writeNl

public void writeNl()
             throws IOException
Writes a single newline.

Throws:
IOException

writeComment

public void writeComment(String comment)
                  throws IOException
Writes comment encoded as comment.

Throws:
IOException

writePI

public void writePI(String target,
                    String data)
             throws IOException
Writes a processing instruction.

Throws:
IOException

writeStartTag

public void writeStartTag(String startTag,
                          boolean nl)
                   throws IOException
Writes a start tag.

Parameters:
startTag - the complete start tag, e.g. <start>
nl - decides whether there should be a newline after the tag
Throws:
IOException

writeStartTag

public void writeStartTag(String startTag)
                   throws IOException
Writes a start tag.

Parameters:
startTag - the complete start tag, e.g. <start>
Throws:
IOException
See Also:
setNlAfterStartTag(boolean)

writeEndTag

public void writeEndTag(String endTag,
                        boolean nl)
                 throws IOException
Writes an end tag.

Parameters:
endTag - the complete end tag, e.g. </end>
nl - decides whether there should be a newline after the tag
Throws:
IOException

writeEndTag

public void writeEndTag(String endTag)
                 throws IOException
Writes an end tag.

Parameters:
endTag - the complete end tag, e.g. </end>
Throws:
IOException
See Also:
setNlAfterEndTag(boolean)

writeEmptyElement

public void writeEmptyElement(String emptyTag,
                              boolean nl)
                       throws IOException
Writes an empty element.

Parameters:
emptyTag - the complete tag for an empty element, e.g. <empty/>
nl - decides whether there should be a newline after the tag
Throws:
IOException

writeEmptyElement

public void writeEmptyElement(String emptyTag)
                       throws IOException
Writes an empty element.

Parameters:
emptyTag - the complete tag for an empty element, e.g. <start/>
Throws:
IOException
See Also:
setNlAfterEmptyTag(boolean)

writeCData

public void writeCData(String cData)
                throws IOException
Writes character data with encoding.

Parameters:
cData - the character data to write
Throws:
IOException

writePCData

public void writePCData(String pcData)
                 throws IOException
Writes character data without encoding.

Parameters:
pcData - the parseable character data to write
Throws:
IOException

writeElementWithCData

public void writeElementWithCData(String startTag,
                                  String cData,
                                  String endTag)
                           throws IOException
Writes a full element consisting of a start tag, character data and an end tag. There will be no newline after start tag, so character data is literally preserved.
The character data will be encoded.

Parameters:
startTag - the complete start tag, e.g. <element>
cData - the character data to write
endTag - the complete end tag, e.g. </element>
Throws:
IOException

writeElementWithPCData

public void writeElementWithPCData(String startTag,
                                   String pcData,
                                   String endTag)
                            throws IOException
Writes a full element consisting of a start tag, character data and an end tag. There will be no newline after start tag, so character data is literally preserved.
The character data will not be encoded.

Parameters:
startTag - the complete start tag, e.g. <element>
pcData - the parseable character data to write
endTag - the complete end tag, e.g. </element>
Throws:
IOException


Copyright © 2001-2010 The Apache Software Foundation. All Rights Reserved.