uk.ac.starlink.util

## Class XmlWriter

- java.lang.Object
- - uk.ac.starlink.util.XmlWriter

-     public class XmlWriter
      extends java.lang.Object

  Provides methods for writing XML output to a stream.
  Since:
    17 Mar 2006

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XmlWriter()` Constructs a new writer which outputs to `System.out`.
    `XmlWriter(java.io.PrintStream out)` Constructs a new writer which writes to a given print stream.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addElement(java.lang.String elName, java.lang.String attList, java.lang.String content)` Writes a whole element with given attribute list and content.
    `void` | `endElement(java.lang.String elName)` Outputs an end element tag.
    `static java.lang.String` | `formatAttribute(java.lang.String name, java.lang.String value)` Turns a name,value pair into an attribute assignment suitable for putting in an XML start tag.
    `static java.lang.String` | `formatText(java.lang.String text)` Performs necessary special character escaping for text which will be written as XML CDATA.
    `java.lang.String` | `getIndent(int level)` Returns the indentation string associated with a given level.
    `int` | `getLevel()` Returns the current element nesting level.
    `void` | `print(java.lang.String txt)` Outputs a literal string in the output.
    `void` | `println(java.lang.String txt)` Outputs a literal string in the output followed by a newline character.
    `void` | `setOut(java.io.PrintStream out)` Sets the destination stream for this writer.
    `void` | `startElement(java.lang.String elName)` Outputs a start element tag with no attributes.
    `void` | `startElement(java.lang.String elName, java.lang.String attList)` Outputs a start element tag with a given list of attributes.
    `void` | `writeDeclaration()` Writes an XML declaration.

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

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

- - ### Constructor Detail

    - #### XmlWriter

          public XmlWriter()

      Constructs a new writer which outputs to `System.out`.

    - #### XmlWriter

          public XmlWriter(java.io.PrintStream out)

      Constructs a new writer which writes to a given print stream.
      Parameters:
        `out` - destination stream

  - ### Method Detail

    - #### writeDeclaration

          public void writeDeclaration()

      Writes an XML declaration. Only call this before any other output.

    - #### startElement

          public void startElement(java.lang.String elName)

      Outputs a start element tag with no attributes.
      Parameters:
        `elName` - name of the element

    - #### startElement

          public void startElement(java.lang.String elName,
                                   java.lang.String attList)

      Outputs a start element tag with a given list of attributes. The supplied attribute list is exactly as it will be inserted into the output, so it must start with a space (if it's not empty) and any relevant escaping must have been done.
      Parameters:
        `elName` - name of the element
        `attList` - literal string giving the attribute list

    - #### endElement

          public void endElement(java.lang.String elName)

      Outputs an end element tag.
      Parameters:
        `elName` - name of the element
      Throws:
        `java.lang.IllegalArgumentException` - if that element's not ready to finish

    - #### addElement

          public void addElement(java.lang.String elName,
                                 java.lang.String attList,
                                 java.lang.String content)

      Writes a whole element with given attribute list and content. The supplied attribute list and content strings are exactly as they will be inserted into the output, so it must start with a space (if it's not empty) and any relevant escaping must have been done.
      Parameters:
        `elName` - name of the element
        `attList` - literal string giving the attribute list
        `content` - literal string giving the element content

    - #### print

          public void print(java.lang.String txt)

      Outputs a literal string in the output.
      Parameters:
        `txt` - literal text

    - #### setOut

          public void setOut(java.io.PrintStream out)

      Sets the destination stream for this writer.
      Parameters:
        `out` - new destination stream

    - #### println

          public void println(java.lang.String txt)

      Outputs a literal string in the output followed by a newline character.
      Parameters:
        `txt` - literal text

    - #### getLevel

          public int getLevel()

      Returns the current element nesting level.
      Returns:
        nesting level (0 at start and end of document)

    - #### formatAttribute

          public static java.lang.String formatAttribute(java.lang.String name,
                                                         java.lang.String value)

      Turns a name,value pair into an attribute assignment suitable for putting in an XML start tag. The resulting string starts with, but does not end with, whitespace. Any necessary escaping of the strings is taken care of.
      Parameters:
        `name` - the attribute name
        `value` - the attribute value
      Returns:
        string of the form ' name="value"'

    - #### formatText

          public static java.lang.String formatText(java.lang.String text)

      Performs necessary special character escaping for text which will be written as XML CDATA.
      Parameters:
        `text` - the input text
      Returns:
        `text` but with XML special characters escaped

    - #### getIndent

          public java.lang.String getIndent(int level)

      Returns the indentation string associated with a given level. This is a couple of spaces for each level.
      Returns:
        level