net.sf.okapi.common

## Class XMLWriter

- java.lang.Object
- - net.sf.okapi.common.XMLWriter

-     public class XMLWriter
      extends java.lang.Object

  Helper class to write XML documents.

  IMPORTANT: flush() or close() must always be called to assure all content is flushed to the underlying streams.

  If a `StringWriter` is used the flush() or close() must be be called before calling the toString() method

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XMLWriter(java.lang.String path)` Creates a new XML document on disk.
    `XMLWriter(java.io.Writer writer)` Creates a new XML document for a given writer object.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendRawXML(java.lang.String xmlData)` Writes a chunk of raw XML (and line-breaks are normalized to platform specific ones).
    `void` | `close()` Closes the writer and release any associated resources.
    `protected void` | `finalize()`
    `void` | `flush()` Flushes the current buffer to the device.
    `java.lang.String` | `getLineBreak()` Gets the line break string currently used for this writer.
    `void` | `setLineBreak(java.lang.String lineBreak)` Sets the type of line-break to use when writing out the document.
    `void` | `writeAttributeString(java.lang.String name, java.lang.String value)` Writes an attribute and its associated value.
    `void` | `writeComment(java.lang.String text, boolean withLineBreak)` Writes a comment.
    `void` | `writeElementString(java.lang.String name, java.lang.String content)` Writes an element and its content.
    `void` | `writeEndDocument()` Writes the end of the document.
    `void` | `writeEndElement()` Writes the end of the last started element.
    `void` | `writeEndElementLineBreak()` Writes the end of the last started element and writes a line-break.
    `void` | `writeLineBreak()` Writes a line-break, and if the writer is in a start tag, close it before.
    `void` | `writeRawXML(java.lang.String xmlData)` Writes a chunk of raw XML (and line-breaks are normalized to platform specific ones).
    `void` | `writeStartDocument()` Writes the start of the document.
    `void` | `writeStartElement(java.lang.String name)` Writes the start of an element.
    `void` | `writeStartHTMLDocument(java.lang.String title)` Writes the start of a XHTML document, including the head and start of body element.
    `void` | `writeString(java.lang.String text)` Writes a string.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### XMLWriter

          public XMLWriter(java.lang.String path)

      Creates a new XML document on disk.
      Parameters:
        `path` - the full path of the document to create. If any directory in the path does not exists yet it will be created automatically. The document is always written in UTF-8 and the type of line-breaks is the one of the platform where the application runs.

    - #### XMLWriter

          public XMLWriter(java.io.Writer writer)

      Creates a new XML document for a given writer object.
      Parameters:
        `writer` - the writer to use to output the document. If this writer outputs to bytes it must be set to output in UTF-8.

  - ### Method Detail

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

      Overrides:
        `finalize` in class `java.lang.Object`
      Throws:
        `java.lang.Throwable`

    - #### setLineBreak

          public void setLineBreak(java.lang.String lineBreak)

      Sets the type of line-break to use when writing out the document. By default, the type is the one of the platform. This method can be used for example, to force the line-breaks to be "\n" instead of "\r\n" when writing out on a string that will be later written out on a file where "\n" will be converted to "\r\n" (therefore avoiding to end up with "\r\r\n").
      Parameters:
        `lineBreak` - the new type of line-break to use.

    - #### getLineBreak

          public java.lang.String getLineBreak()

      Gets the line break string currently used for this writer.
      Returns:
        the line break string used.

    - #### close

          public void close()

      Closes the writer and release any associated resources.

    - #### writeStartDocument

          public void writeStartDocument()

      Writes the start of the document. This method generates the XML declaration.

    - #### writeStartHTMLDocument

          public void writeStartHTMLDocument(java.lang.String title)

      Writes the start of a XHTML document, including the head and start of body element.
      Parameters:
        `title` - the title of the document (can be null).

    - #### writeEndDocument

          public void writeEndDocument()

      Writes the end of the document. This method closes any open tag, and flush the writer.

    - #### writeStartElement

          public void writeStartElement(java.lang.String name)

      Writes the start of an element.
      Parameters:
        `name` - the name of the element to start.

    - #### writeEndElement

          public void writeEndElement()

      Writes the end of the last started element.

    - #### writeEndElementLineBreak

          public void writeEndElementLineBreak()

      Writes the end of the last started element and writes a line-break.

    - #### writeElementString

          public void writeElementString(java.lang.String name,
                                java.lang.String content)

      Writes an element and its content.
      Parameters:
        `name` - the name of the element to write.
        `content` - the content to enclose inside this element.

    - #### writeAttributeString

          public void writeAttributeString(java.lang.String name,
                                  java.lang.String value)

      Writes an attribute and its associated value. You must use `writeStartElement(String)` just before.
      Parameters:
        `name` - the name of the attribute.
        `value` - the value of the attribute.

    - #### writeString

          public void writeString(java.lang.String text)

      Writes a string. The text is automatically escaped.
      Parameters:
        `text` - the text to output.

    - #### writeRawXML

          public void writeRawXML(java.lang.String xmlData)

      Writes a chunk of raw XML (and line-breaks are normalized to platform specific ones). If a tag is open, it is closed automatically before the data are written. Use `appendRawXML(String)` to output without preliminary closing.
      Parameters:
        `xmlData` - the data to output. No escaping is performed, but the line-breaks are converted to the line-break type of the output.

    - #### appendRawXML

          public void appendRawXML(java.lang.String xmlData)

      Writes a chunk of raw XML (and line-breaks are normalized to platform specific ones). If a tag is open it is not closed (so this allows you to output raw attributes).
      Parameters:
        `xmlData` - the data to output. No escaping is performed, but the line-breaks are converted to the line-break type of the output.

    - #### writeComment

          public void writeComment(java.lang.String text,
                          boolean withLineBreak)

      Writes a comment.
      Parameters:
        `text` - the text of the comment.
        `withLineBreak` - add a line break at the end of the comment.

    - #### writeLineBreak

          public void writeLineBreak()

      Writes a line-break, and if the writer is in a start tag, close it before.

    - #### flush

          public void flush()

      Flushes the current buffer to the device.