org.eclipse.rdf4j.common.xml

## Class XMLWriter

- java.lang.Object
- - org.eclipse.rdf4j.common.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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `_indentLevel` The current indentation level, i.e.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `Writer` | `getWriter()`
    `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.
    `void` | `writeStylesheet(String url)` Writes a link to an XSL stylesheet, using `<?xml-stylesheet type='text/xsl' href='url'?>`.

    - ### 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.

    - #### getWriter

          public Writer getWriter()

      Returns:
        the writer

    - #### 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)`

    - #### writeStylesheet

          public void writeStylesheet(String url)
                               throws IOException

      Writes a link to an XSL stylesheet, using `<?xml-stylesheet type='text/xsl' href='url'?>`.
      Parameters:
        `url` - The URL of the stylesheet.
      Throws:
        `IOException`

    - #### 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`

Copyright © 2015-2022 Eclipse Foundation. All Rights Reserved.