info.aduna.xml
Class XMLWriter

java.lang.Object
  info.aduna.xml.XMLWriter

public class XMLWriter
extends Object

A utility class offering convenience methods for writing XML. This class takes care of character escaping, identation, etc. This class does not verify that the written data is legal XML. It is the callers responsibility to make sure that elements are properly nested, etc.

Example:

To write the following XML:

 <?xml version='1.0' encoding='UTF-8'?>
 <xml-doc>
        <foo a="1" b="2&amp;3"/>
        <bar>Hello World!</bar>
 </xml-doc>

One can use the following code:

 XMLWriter xmlWriter = new XMLWriter(myWriter);
 xmlWriter.setPrettyPrint(true);

 xmlWriter.startDocument();
 xmlWriter.startTag("xml-doc");

 xmlWriter.setAttribute("a", 1);
 xmlWriter.setAttribute("b", "2&3");
 xmlWriter.simpleTag("foo");

 xmlWriter.textTag("bar", "Hello World!");

 xmlWriter.endTag("xml-doc");
 xmlWriter.endDocument();
 

Field Summary

protected int

_indentLevel The current indentation level, i.e.

Constructor Summary

XMLWriter(OutputStream outputStream)
Creates a new XMLWriter that will write its data to the supplied OutputStream in the default UTF-8 character encoding.

XMLWriter(OutputStream outputStream, String charEncoding)
Creates a new XMLWriter that will write its data to the supplied OutputStream in specified character encoding.

XMLWriter(Writer writer)
Creates a new XMLWriter that will write its data to the supplied Writer.

Method Summary

protected void	_write(String s) Writes a string.
protected void	_writeIndent() Writes as much indentation strings as appropriate for the current indentation level.
protected void	_writeLn(String s) Writes a string followed by a line-separator.
void	comment(String comment) Writes a comment.
void	emptyElement(String elName) Writes an 'empty' element, e.g.
void	emptyLine() Writes an empty line.
void	endDocument() Finishes writing and flushes the OutputStream or Writer that this XMLWriter is writing to.
void	endTag(String elName) Writes an end tag.
String	getIndentString() Gets the string used for indentation.
boolean	prettyPrintEnabled() Checks whether pretty-printing is enabled.
void	setAttribute(String name, boolean value) Sets an attribute for the next start element.
void	setAttribute(String name, int value) Sets an attribute for the next start element.
void	setAttribute(String name, String value) Sets an attribute for the next start tag.
void	setIndentString(String indentString) Sets the string that should be used for indentation when pretty-printing is enabled.
void	setPrettyPrint(boolean prettyPrint) Enables or disables pretty-printing.
void	startDocument() Writes the XML header for the XML file.
void	startTag(String elName) Writes a start tag containing the previously set attributes.
void	text(String text) Writes a piece of text.
void	textElement(String elName, boolean value) Writes a start and end tag with the supplied boolean value between them.
void	textElement(String elName, int value) Writes a start and end tag with the supplied value between them.
void	textElement(String elName, String text) Writes a start and end tag with the supplied text between them.
void	unescapedTextElement(String elName, String text) Writes a start and end tag with the supplied text between them, without the usual escape rules.

Methods inherited from class java.lang.Object

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

Field Detail

_indentLevel

protected int _indentLevel

The current indentation level, i.e. the number of tabs to indent a start or end tag.

Constructor Detail

XMLWriter

public XMLWriter(Writer writer)

Creates a new XMLWriter that will write its data to the supplied Writer. Character encoding issues are left to the supplier of the Writer.

Parameters:

writer - The Writer to write the XML to.

XMLWriter

public XMLWriter(OutputStream outputStream)

Creates a new XMLWriter that will write its data to the supplied OutputStream in the default UTF-8 character encoding.

Parameters:

outputStream - The OutputStream to write the XML to.

XMLWriter

public XMLWriter(OutputStream outputStream,
                 String charEncoding)
          throws UnsupportedEncodingException

Creates a new XMLWriter that will write its data to the supplied OutputStream in specified character encoding.

Parameters:

outputStream - The OutputStream to write the XML to.

Throws:

UnsupportedEncodingException

Method Detail

setPrettyPrint

public void setPrettyPrint(boolean prettyPrint)

Enables or disables pretty-printing. If pretty-printing is enabled, the XMLWriter will add newlines and indentation to the written data. Pretty-printing is disabled by default.

Parameters:

prettyPrint - Flag indicating whether pretty-printing should be enabled.

prettyPrintEnabled

public boolean prettyPrintEnabled()

Checks whether pretty-printing is enabled.

Returns:

true if pretty-printing is enabled, false otherwise.

setIndentString

public void setIndentString(String indentString)

Sets the string that should be used for indentation when pretty-printing is enabled. The default indentation string is a tab character.

Parameters:

indentString - The indentation string, e.g. a tab or a number of spaces.

getIndentString

public String getIndentString()

Gets the string used for indentation.

Returns:

the indentation string.

startDocument

public void startDocument()
                   throws IOException

Writes the XML header for the XML file.

Throws:

IOException - If an I/O error occurs.

endDocument

public void endDocument()
                 throws IOException

Finishes writing and flushes the OutputStream or Writer that this XMLWriter is writing to.

Throws:

IOException

setAttribute

public void setAttribute(String name,
                         String value)

Sets an attribute for the next start tag.

Parameters:

name - The name of the attribute.

value - The value of the attribute.

setAttribute

public void setAttribute(String name,
                         int value)

Sets an attribute for the next start element.

Parameters:

name - The name of the attribute.

value - The value of the attribute. The integer value will be transformed to a string using the method String.valueOf(int).

See Also:

String.valueOf(int)

setAttribute

public void setAttribute(String name,
                         boolean value)

Sets an attribute for the next start element.

Parameters:

name - The name of the attribute.

value - The value of the attribute. The boolean value will be transformed to a string using the method String.valueOf(boolean).

See Also:

String.valueOf(boolean)

startTag

public void startTag(String elName)
              throws IOException

Writes a start tag containing the previously set attributes.

Parameters:

elName - The element name.

Throws:

IOException

See Also:

setAttribute(java.lang.String,java.lang.String)

endTag

public void endTag(String elName)
            throws IOException

Writes an end tag.

Parameters:

elName - The element name.

Throws:

IOException

emptyElement

public void emptyElement(String elName)
                  throws IOException

Writes an 'empty' element, e.g. <foo/>. The tag will contain any previously set attributes.

Parameters:

elName - The element name.

Throws:

IOException

See Also:

setAttribute(java.lang.String,java.lang.String)

textElement

public void textElement(String elName,
                        String text)
                 throws IOException

Writes a start and end tag with the supplied text between them. The start tag will contain any previously set attributes.

Parameters:

elName - The element name.

text - The text.

Throws:

IOException

See Also:

setAttribute(java.lang.String,java.lang.String)

unescapedTextElement

public void unescapedTextElement(String elName,
                                 String text)
                          throws IOException

Writes a start and end tag with the supplied text between them, without the usual escape rules. The start tag will contain any previously set attributes.

Parameters:

elName - The element name.

text - The text.

Throws:

IOException

See Also:

setAttribute(java.lang.String,java.lang.String)

textElement

public void textElement(String elName,
                        int value)
                 throws IOException

Writes a start and end tag with the supplied value between them. The start tag will contain any previously set attributes.

Parameters:

elName - The element name.

value - The value. The integer value will be transformed to a string using the method String.valueOf(int).

Throws:

IOException

See Also:

String.valueOf(int)

textElement

public void textElement(String elName,
                        boolean value)
                 throws IOException

Writes a start and end tag with the supplied boolean value between them. The start tag will contain any previously set attributes.

Parameters:

elName - The element name.

value - The boolean value. The integer value will be transformed to a string using the method String.valueOf(boolean).

Throws:

IOException

See Also:

String.valueOf(boolean)

text

public void text(String text)
          throws IOException

Writes a piece of text.

Parameters:

text - The text.

Throws:

IOException

comment

public void comment(String comment)
             throws IOException

Writes a comment.

Parameters:

comment - The comment.

Throws:

IOException

emptyLine

public void emptyLine()
               throws IOException

Writes an empty line. A call to this method will be ignored when pretty-printing is disabled.

Throws:

IOException

See Also:

setPrettyPrint(boolean)

_write

protected void _write(String s)
               throws IOException

Writes a string.

Throws:

IOException

_writeLn

protected void _writeLn(String s)
                 throws IOException

Writes a string followed by a line-separator. The line-separator is not written when pretty-printing is disabled.

Throws:

IOException

_writeIndent

protected void _writeIndent()
                     throws IOException

Writes as much indentation strings as appropriate for the current indentation level. A call to this method is ignored when pretty-printing is disabled.

Throws:

IOException