Package org.dbunit.util.xml

Class XmlWriter

java.lang.Object
org.dbunit.util.xml.XmlWriter
public class XmlWriter extends Object
Makes writing XML much much easier. Improved from article
Since:
1.0
Version:
$Revision$ $Date$
Author:
Henri Yandell, Peter Cassetta, Last changed by: $Author$

  • Field Details

  • Constructor Details

    • XmlWriter

      public XmlWriter(Writer writer)
      Create an XmlWriter on top of an existing java.io.Writer.
      Parameters:
      writer - the writer to write to.

    • XmlWriter

      public XmlWriter(Writer writer, Charset charset)
      Create an XmlWriter on top of an existing java.io.Writer.
      Parameters:
      writer - the writer to write to.
      charset - the charset to declare in the XML prolog, may be null.

    • XmlWriter

      public XmlWriter(OutputStream outputStream, Charset charset)
      Create an XmlWriter on top of an existing OutputStream.
      Parameters:
      outputStream - the stream to write to.
      charset - The charset to be used for writing to the given output stream. Can be null. If it is null the DEFAULT_ENCODING is used.
      Since:
      2.4

  • Method Details

    • enablePrettyPrint

      public void enablePrettyPrint(boolean enable)
      Turn pretty printing on or off. Pretty printing is enabled by default, but it can be turned off to generate more compact XML.
      Parameters:
      enable - true to enable, false to disable pretty printing.

    • setIndent

      public void setIndent(String indent)
      Specify the string to prepend to a line for each level of indent. It is 2 spaces (" ") by default. Some may prefer a single tab ("\t") or a different number of spaces. Specifying an empty string will turn off indentation when pretty printing.
      Parameters:
      indent - representing one level of indentation while pretty printing.

    • setNewline

      public void setNewline(String newline)
      Specify the string used to terminate each line when pretty printing. It is a single newline ("\n") by default. Users who need to read generated XML documents in Windows editors like Notepad may wish to set this to a carriage return/newline sequence ("\r\n"). Specifying an empty string will turn off generation of line breaks when pretty printing.
      Parameters:
      newline - representing the newline sequence when pretty printing.

    • writeElementWithText

      public XmlWriter writeElementWithText(String name, String text) throws IOException
      A helper method. It writes out an element which contains only text.
      Parameters:
      name - String name of tag
      text - String of text to go inside the tag
      Returns:
      this writer.
      Throws:
      IOException - if writing fails.

    • writeEmptyElement

      public XmlWriter writeEmptyElement(String name) throws IOException
      A helper method. It writes out empty entities.
      Parameters:
      name - String name of tag
      Returns:
      this writer.
      Throws:
      IOException - if writing fails.

    • writeElement

      public XmlWriter writeElement(String name) throws IOException
      Begin to write out an element. Unlike the helper tags, this tag will need to be ended with the endElement method.
      Parameters:
      name - String name of tag
      Returns:
      this writer.
      Throws:
      IOException - if writing fails.

    • writeAttribute

      public XmlWriter writeAttribute(String attr, String value) throws IOException
      Write an attribute out for the current element. Any XML characters in the value are escaped. Currently it does not actually throw the exception, but the API is set that way for future changes.
      Parameters:
      attr - name of attribute.
      value - value of attribute.
      Returns:
      this writer.
      Throws:
      IOException - if writing fails.
      See Also:

    • writeAttribute

      public XmlWriter writeAttribute(String attr, String value, boolean literally) throws IOException
      Write an attribute out for the current element. Any XML characters in the value are escaped. Currently it does not actually throw the exception, but the API is set that way for future changes.
      Parameters:
      attr - name of attribute.
      value - value of attribute.
      literally - If the writer should be literally on the given value which means that meta characters will also be preserved by escaping them. Mainly preserves newlines and tabs.
      Returns:
      this writer.
      Throws:
      IOException - if writing fails.

    • endElement

      public XmlWriter endElement() throws IOException
      End the current element. This will throw an exception if it is called when there is not a currently open element.
      Returns:
      this writer.
      Throws:
      IOException - if there is no currently open element, or writing fails.

    • close

      public void close() throws IOException
      Close this writer. It does not close the underlying writer, but does throw an exception if there are as yet unclosed tags.
      Throws:
      IOException - if there are unclosed tags, or flushing fails.

    • flush

      public void flush() throws IOException
      Flushes the underlying writer, without close()'s unclosed-tags check. Intended for callers recovering from a write error mid-document, so already-written content reaches the underlying stream even though the document itself is incomplete.
      Throws:
      IOException - on a failure to flush the underlying writer.

    • writeText

      public XmlWriter writeText(String text) throws IOException
      Output body text. Any XML characters are escaped.
      Parameters:
      text - The text to be written
      Returns:
      This writer
      Throws:
      IOException - if writing fails.
      See Also:

    • writeText

      public XmlWriter writeText(String text, boolean literally) throws IOException
      Output body text. Any XML characters are escaped.
      Parameters:
      text - The text to be written
      literally - If the writer should be literally on the given value which means that meta characters will also be preserved by escaping them. Mainly preserves newlines and tabs.
      Returns:
      This writer
      Throws:
      IOException - if writing fails.

    • writeCData

      public XmlWriter writeCData(String cdata) throws IOException
      Write out a chunk of CDATA. This helper method surrounds the passed in data with the CDATA tag.
      Parameters:
      cdata - of CDATA text.
      Returns:
      this writer.
      Throws:
      IOException - if writing fails.

    • writeComment

      public XmlWriter writeComment(String comment) throws IOException
      Write out a chunk of comment. This helper method surrounds the passed in data with the XML comment tag.
      Parameters:
      comment - of text to comment.
      Returns:
      this writer.
      Throws:
      IOException - if writing fails.

    • main

      public static void main(String[] args) throws IOException
      Runs test1() and test2(), printing their output for manual inspection.
      Parameters:
      args - ignored.
      Throws:
      IOException - if writing the example XML fails.

    • test1

      public static void test1() throws IOException
      Writes an example XML document using the fluent writeElement(String) style.
      Throws:
      IOException - if writing the example XML fails.

    • test2

      public static void test2() throws IOException
      Writes the same example XML document as test1(), using the step-by-step style.
      Throws:
      IOException - if writing the example XML fails.

    • convertCharacterToEntity

      protected String convertCharacterToEntity(char currentChar, boolean literally)
      Returns the XML entity for the given character, if any.
      Parameters:
      currentChar - the character to convert.
      literally - whether the character was written via a "literal" write method, which affects which characters are converted.
      Returns:
      the XML entity for the given character, or null if it needs no entity.

    • setWriter

      public final void setWriter(Writer writer, String encoding)
      Resets the handler to write a new text document.
      Parameters:
      writer - XML text is written to this writer.
      encoding - if non-null, and an XML declaration is written, this is the name that will be used for the character encoding.
      Throws:
      IllegalStateException - if the current document hasn't yet ended (i.e. the output stream out is not null)

    • setWriter

      public final void setWriter(Writer writer, Charset charset)
      Sets the writer and character set to write to.
      Parameters:
      writer - the writer to write to.
      charset - the character set to encode the declaration with.

    • writeDeclaration

      public XmlWriter writeDeclaration() throws IOException
      Writes the XML declaration, if an encoding is set.
      Returns:
      this writer, for chaining.
      Throws:
      IOException - if writing to the underlying stream fails.

    • writeDoctype

      public XmlWriter writeDoctype(String systemId, String publicId) throws IOException
      Writes a DOCTYPE declaration for the dataset, if a system or public id is given.
      Parameters:
      systemId - the DTD's system id, or null.
      publicId - the DTD's public id, or null.
      Returns:
      this writer, for chaining.
      Throws:
      IOException - if writing to the underlying stream fails.