de.caff.io.xml

## Class SimpleXmlWriter

- java.lang.Object
- - de.caff.io.xml.SimpleXmlWriter

- All Implemented Interfaces:
    java.lang.AutoCloseable

      public class SimpleXmlWriter
      extends java.lang.Object
      implements java.lang.AutoCloseable

  Simple XML writer.

  This writer makes creation of simple XML documents without advanced features simple. Use the following to create simple XML:

  This class was not only moved from package `de.caff.util.xml`, it also underwent important changes: in order to become auto-closeable methods are renamed:

  - `SimpleXmlWriter.open(String, Object...)` is replaced by `begin(String, Object...)`.
  - `SimpleXmlWriter.close()` is replaced by `end()`. Because the new class also provides a `close()` with different semantics special care has to be taken when switching!
  - `SimpleXmlWriter.finish()` is replaced by `close()` to make this class auto-closable.
  - Most constructors already create the XML declaration with version (always 1.0) and encoding. Other constructors allow finetuning, e.g. for HTML creation.
  - The `element(String, Object...)` method writes an empty element which is already closed with the given attributes' name-value pairs.
  - The `begin(String, Object...)` method writes an opening element with the given attributes' name-value pairs.
  - The `end()` method closes the element created by the latest `begin(String, Object...)` call.
  - The `close()` method closes all open elements. Although inherited from the `AutoCloseable` interface it will not throw any checked exception.
  - The `comment(String)` method inserts a comment with the given text.
  - The `text(Object)` method inserts the given text, taking care of escaping.
  - The `textf(String, Object...)` method does the same, but allows formatting like `String.format(String, Object...)`.
  - The `cdata(String)` method inserts the given text in raw form as a CDATA section.
  - The `nl()` method can be used to insert a newline, see also the comments on automatic wrapping below.
  - The `expand(byte[])` inserts binary data as 2-digit-per-byte hexadecimal numbers.
  - The `expandBase64(byte[])` inserts binary data in base64 encoding.
  - The `expand(byte[], int)` method can be used to format binary data as 2-digit-per-byte hexadecimal numbers, and can be used with either the `text(Object)` method or as attribute value (in the latter case best with `columns` set to `0`).

  Automatic wrapping and indentation of hierarchy levels can be switched on by using constructor which accept an `indentation` parameter with a non-negative indentation value. A value of `0` switches auto-wrapping on, starting each opening tag on a new line. A value greater than zero will also indent each sub level by the given number of blanks. A negative value will switch both auto-wrapping and indentation off.

  Author:
    Rammi

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `autoWrap` Is automatic wrapping enabled?
    `protected StringCollector` | `collector` Collector used for output text collection.
    `static java.lang.String` | `DEFAULT_ENCODING` Default encoding in XML header.
    `protected java.lang.String` | `indentation` Use as indentation if non-`null`.
    `protected java.util.Locale` | `locale` Locale to be used when formatting.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpleXmlWriter(java.util.Locale locale, StringCollector collector)` Constructor.
    `SimpleXmlWriter(java.util.Locale locale, StringCollector collector, int indentation)` Constructor.
    `SimpleXmlWriter(java.util.Locale locale, StringCollector collector, java.lang.String preamble)` Constructor.
    `SimpleXmlWriter(java.util.Locale locale, StringCollector collector, java.lang.String preamble, int indentation)` Constructor.
    `SimpleXmlWriter(StringCollector collector)` Constructor.
    `SimpleXmlWriter(StringCollector collector, int indentation)` Constructor.
    `SimpleXmlWriter(StringCollector collector, java.lang.String preamble)` Constructor.
    `SimpleXmlWriter(StringCollector collector, java.lang.String preamble, int indentation)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `SimpleXmlWriter` | `begin(java.lang.String tag, java.lang.Object... attributes)` Write the opening tag of an element.
    `SimpleXmlWriter` | `beginI(java.lang.String tag, Indexable<?> attributes)` Write the opening tag of an element, using indexed attributes.
    `SimpleXmlWriter` | `beginP(java.lang.String tag, Indexable<? extends Pair<?>> attributes)` Write the opening tag of an element, using paired attributes.
    `SimpleXmlWriter` | `cdata(java.lang.String text)` Outputs the raw text as a CDATA section.
    `void` | `close()`
    `SimpleXmlWriter` | `comment(java.lang.String comment)` Add a comment.
    `SimpleXmlWriter` | `element(java.lang.String tag, java.lang.Object... attributes)` Writes an empty element.
    `SimpleXmlWriter` | `elementI(java.lang.String tag, Indexable<?> attributes)` Writes an empty element with indexed attributes.
    `SimpleXmlWriter` | `elementP(java.lang.String tag, Indexable<? extends Pair<?>> attributes)` Writes an empty element with paired attributes.
    `SimpleXmlWriter` | `end()` Close the latest open element.
    `SimpleXmlWriter` | `end(java.lang.String tag)` Close the given element.
    `SimpleXmlWriter` | `expand(byte[] data)` Convert data into hex code and add it as text.
    `static java.lang.String` | `expand(byte[] data, int columns)` Expand an array of bytes into a hex string.
    `SimpleXmlWriter` | `expandBase64(byte[] data)` Convert data into hex code and add it as text.
    `static java.lang.String` | `getDefaultPreamble()` Get the default XML preamble with UTF-8 encoding.
    `java.lang.String` | `getIndentation()` Get the indentation.
    `java.util.Locale` | `getLocale()` Get the locale used for formatting text.
    `static java.lang.String` | `getPreamble(java.lang.String encoding)` Get an XML preamble with the given encoding.
    `SimpleXmlWriter` | `indentedText(java.lang.Object text)` Output text following the current indentation.
    `SimpleXmlWriter` | `indentedText(java.lang.String format, java.lang.Object... args)` Output formatted text following the current indentation.
    `boolean` | `isAutoWrap()` Is automatic wrapping enabled?
    `SimpleXmlWriter` | `loop(java.lang.String loopTag, java.lang.Iterable<? extends XmlStorable> items)` Store a loop with no size.
    `SimpleXmlWriter` | `loop(java.lang.String loopTag, java.lang.String sizeAttr, java.util.Collection<? extends XmlStorable> items)` Store a sized loop with a size.
    `SimpleXmlWriter` | `loop(java.lang.String loopTag, java.lang.String sizeAttr, Countable<? extends XmlStorable> items)` Store a sized loop with a size.
    `SimpleXmlWriter` | `loop(java.lang.String loopTag, java.lang.String sizeAttr, XmlStorable... items)` Store a sized loop with a size.
    `SimpleXmlWriter` | `nl()` Add a newline.
    `SimpleXmlWriter` | `text(java.lang.Object text)` Add text outside of tags.
    `SimpleXmlWriter` | `textf(java.lang.String format, java.lang.Object... args)` Add formatted text outside of tags.

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

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

- - ### Field Detail

    - #### DEFAULT_ENCODING

          public static final java.lang.String DEFAULT_ENCODING

      Default encoding in XML header.
      See Also:
        Constant Field Values

    - #### collector

          @NotNull
          protected final StringCollector collector

      Collector used for output text collection.

    - #### autoWrap

          protected final boolean autoWrap

      Is automatic wrapping enabled?

    - #### indentation

          @Nullable
          protected final java.lang.String indentation

      Use as indentation if non-`null`.

    - #### locale

          @NotNull
          protected final java.util.Locale locale

      Locale to be used when formatting.

  - ### Constructor Detail

    - #### SimpleXmlWriter

          public SimpleXmlWriter(@NotNull
                                 StringCollector collector)

      Constructor. The created writer will use the `default preamble`, default locale, no indentation, and no automatic wrapping,
      Parameters:
        `collector` - string collector to which the XML output is written
      See Also:
        `OutputStreamStringCollector`, `TextStringCollector`

    - #### SimpleXmlWriter

          public SimpleXmlWriter(@NotNull
                                 java.util.Locale locale,
                                 @NotNull
                                 StringCollector collector)

      Constructor. The created writer will use the `default preamble`, no indentation, and no automatic wrapping,
      Parameters:
        `locale` - locale used for text formatting in `textf(String, Object...)`
        `collector` - string collector to which the XML output is written
      See Also:
        `OutputStreamStringCollector`, `TextStringCollector`

    - #### SimpleXmlWriter

          public SimpleXmlWriter(@NotNull
                                 StringCollector collector,
                                 @Nullable
                                 java.lang.String preamble)

      Constructor. The created writer will use the default locale, no indentation and no automatic wrapping.
      Parameters:
        `collector` - string collector to which the XML output is written
        `preamble` - preamble written at the start, if `null` no preamble is written
      See Also:
        `OutputStreamStringCollector`, `TextStringCollector`

    - #### SimpleXmlWriter

          public SimpleXmlWriter(@NotNull
                                 java.util.Locale locale,
                                 @NotNull
                                 StringCollector collector,
                                 @Nullable
                                 java.lang.String preamble)

      Constructor. The created writer will use no indentation and no automatic wrapping.
      Parameters:
        `locale` - locale used for text formatting in `textf(String, Object...)`
        `collector` - string collector to which the XML output is written
        `preamble` - preamble written at the start, if `null` no preamble is written
      See Also:
        `OutputStreamStringCollector`, `TextStringCollector`

    - #### SimpleXmlWriter

          public SimpleXmlWriter(@NotNull
                                 StringCollector collector,
                                 int indentation)

      Constructor. The created writer will use the default locale, and the `default preamble`.
      Parameters:
        `collector` - string collector to which the XML output is written
        `indentation` - if `0` or more automatic newlines will be inserted and nested levels will be indented by the given number of spaces

    - #### SimpleXmlWriter

          public SimpleXmlWriter(@NotNull
                                 java.util.Locale locale,
                                 @NotNull
                                 StringCollector collector,
                                 int indentation)

      Constructor. The created writer will use the `default preamble`.
      Parameters:
        `locale` - locale used for text formatting in `textf(String, Object...)`
        `collector` - string collector to which the XML output is written
        `indentation` - if `0` or more automatic newlines will be inserted and nested levels will be indented by the given number of spaces

    - #### SimpleXmlWriter

          public SimpleXmlWriter(@NotNull
                                 StringCollector collector,
                                 @Nullable
                                 java.lang.String preamble,
                                 int indentation)

      Constructor. The created writer will us the default locale.
      Parameters:
        `collector` - string collector to which the XML output is written
        `preamble` - preamble to be written at the beginning of the output, use `null` for no preamble
        `indentation` - if `0` or more automatic newlines will be inserted and nested levels will be indented by the given number of spaces
      See Also:
        `getDefaultPreamble()`, `getPreamble(String)`

    - #### SimpleXmlWriter

          public SimpleXmlWriter(@NotNull
                                 java.util.Locale locale,
                                 @NotNull
                                 StringCollector collector,
                                 @Nullable
                                 java.lang.String preamble,
                                 int indentation)

      Constructor.
      Parameters:
        `locale` - locale used for text formatting in `textf(String, Object...)`
        `collector` - string collector to which the XML output is written
        `preamble` - preamble to be written at the beginning of the output, use `null` for no preamble
        `indentation` - if `0` or more automatic newlines will be inserted and nested levels will be indented by the given number of spaces
      See Also:
        `getDefaultPreamble()`, `getPreamble(String)`

  - ### Method Detail

    - #### isAutoWrap

          public boolean isAutoWrap()

      Is automatic wrapping enabled? Automatic wrapping is enabled when a constructor with a non-negative indentation is used.
      Returns:
        `true`: automatic wrapping is enabled
        `false`: automatic wrapping is disabled

    - #### getIndentation

          @NotNull
          public java.lang.String getIndentation()

      Get the indentation.
      Returns:
        indentation (a number of spaces), possibly empty

    - #### getLocale

          @NotNull
          public java.util.Locale getLocale()

      Get the locale used for formatting text.
      Returns:
        locale for formatting text
      See Also:
        `textf(String, Object...)`

    - #### getDefaultPreamble

          @NotNull
          public static java.lang.String getDefaultPreamble()

      Get the default XML preamble with UTF-8 encoding.
      Returns:
        default preamble

    - #### getPreamble

          @NotNull
          public static java.lang.String getPreamble(@NotNull
                                                              java.lang.String encoding)

      Get an XML preamble with the given encoding.
      Parameters:
        `encoding` - encoding
      Returns:
        XML preamble with defining the given encoding

    - #### begin

          @NotNull
          public SimpleXmlWriter begin(@NotNull
                                                java.lang.String tag,
                                                java.lang.Object... attributes)

      Write the opening tag of an element.
      Parameters:
        `tag` - element tag
        `attributes` - attributes, always in pairs of attribute name and attribute value, values will be escaped
      Returns:
        writer for chaining

    - #### beginI

          @NotNull
          public SimpleXmlWriter beginI(@NotNull
                                                 java.lang.String tag,
                                                 @NotNull
                                                 Indexable<?> attributes)

      Write the opening tag of an element, using indexed attributes.
      Parameters:
        `tag` - element tag
        `attributes` - attributes, always in pairs of attribute name and attribute value, values will be escaped
      Returns:
        writer for chaining

    - #### beginP

          @NotNull
          public SimpleXmlWriter beginP(@NotNull
                                                 java.lang.String tag,
                                                 @NotNull
                                                 Indexable<? extends Pair<?>> attributes)

      Write the opening tag of an element, using paired attributes.
      Parameters:
        `tag` - element tag
        `attributes` - attributes, always in pairs of attribute name and attribute value, values will be escaped
      Returns:
        writer for chaining

    - #### end

          @NotNull
          public SimpleXmlWriter end()

      Close the latest open element. This goes up one step up hierarchy.
      Returns:
        writer for chaining
      Throws:
        `java.util.EmptyStackException` - if closing although no element is open

    - #### end

          @NotNull
          public SimpleXmlWriter end(@Nullable
                                              java.lang.String tag)

      Close the given element.

      In difference to `end()` this method checks whether the closing tag matches the latest opening tag when a tag is given.

      Parameters:
        `tag` - tag expected to end, or `null` to ignore
      Returns:
        writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if tag does not match

    - #### comment

          @NotNull
          public SimpleXmlWriter comment(@NotNull
                                                  java.lang.String comment)

      Add a comment.
      Parameters:
        `comment` - comment to add
      Returns:
        writer for chaining

    - #### expand

          @NotNull
          public SimpleXmlWriter expand(@NotNull
                                                 byte[] data)

      Convert data into hex code and add it as text.
      Parameters:
        `data` - data to add
      Returns:
        writer for chaining

    - #### expand

          @NotNull
          public static java.lang.String expand(@NotNull
                                                         byte[] data,
                                                         int columns)

      Expand an array of bytes into a hex string.
      Parameters:
        `data` - data to expand
        `columns` - columns of hex digits of returned string before a line break is inserted. If `0` or less no break is inserted.
      Returns:
        hex string

    - #### expandBase64

          @NotNull
          public SimpleXmlWriter expandBase64(@NotNull
                                                       byte[] data)

      Convert data into hex code and add it as text.
      Parameters:
        `data` - data to add
      Returns:
        writer for chaining

    - #### element

          @NotNull
          public SimpleXmlWriter element(@NotNull
                                                  java.lang.String tag,
                                                  java.lang.Object... attributes)

      Writes an empty element.
      Parameters:
        `tag` - element tag
        `attributes` - attributes, always in pairs of attribute name and attribute value, values will be escaped
      Returns:
        writer for chaining

    - #### elementI

          @NotNull
          public SimpleXmlWriter elementI(@NotNull
                                                   java.lang.String tag,
                                                   @NotNull
                                                   Indexable<?> attributes)

      Writes an empty element with indexed attributes.
      Parameters:
        `tag` - element tag
        `attributes` - attributes, always in pairs of attribute name and attribute value, values will be escaped
      Returns:
        writer for chaining

    - #### elementP

          @NotNull
          public SimpleXmlWriter elementP(@NotNull
                                                   java.lang.String tag,
                                                   @NotNull
                                                   Indexable<? extends Pair<?>> attributes)

      Writes an empty element with paired attributes.
      Parameters:
        `tag` - element tag
        `attributes` - attributes, in pairs where `OrderedPair.first` defines the attribute's name, and `OrderedPair.second` defines its value
      Returns:
        writer for chaining

    - #### text

          @NotNull
          public SimpleXmlWriter text(@NotNull
                                               java.lang.Object text)

      Add text outside of tags.
      Parameters:
        `text` - text to add
      Returns:
        writer for chaining

    - #### indentedText

          @NotNull
          public SimpleXmlWriter indentedText(@NotNull
                                                       java.lang.Object text)

      Output text following the current indentation. This will remove all the whitespace around the text when outputting. If indentation is enabled, all lines will be outputted correctly indented, removing the whitespace around each line.
      Parameters:
        `text` - text to be outputted
      Returns:
        writer for chaining

    - #### textf

          @NotNull
          public SimpleXmlWriter textf(@NotNull
                                                java.lang.String format,
                                                @NotNull
                                                java.lang.Object... args)

      Add formatted text outside of tags. This will work the same as `String.format(String, Object...)` using the `locale` set via the constructor.
      Parameters:
        `format` - format string
        `args` - arguments for the format string
      Returns:
        writer for chaining

    - #### indentedText

          @NotNull
          public SimpleXmlWriter indentedText(@NotNull
                                                       java.lang.String format,
                                                       java.lang.Object... args)

      Output formatted text following the current indentation. This will work the same as `String.format(String, Object...)` using the `locale` set via the constructor.

      It will also remove all the whitespace around the text when outputting. If indentation is enabled, all lines will be outputted correctly indented, removing the whitespace around each line.

      Parameters:
        `format` - format string
        `args` - arguments for the format string
      Returns:
        writer for chaining

    - #### nl

          @NotNull
          public SimpleXmlWriter nl()

      Add a newline.
      Returns:
        writer for chaining

    - #### cdata

          @NotNull
          public SimpleXmlWriter cdata(@NotNull
                                                java.lang.String text)

      Outputs the raw text as a CDATA section.
      Parameters:
        `text` - text to be outputted, not escaped in any form
      Returns:
        writer for chaining

    - #### close

          public void close()

      Specified by:
        `close` in interface `java.lang.AutoCloseable`

    - #### loop

          @NotNull
          public SimpleXmlWriter loop(@NotNull
                                               java.lang.String loopTag,
                                               @NotNull
                                               java.lang.Iterable<? extends XmlStorable> items)

      Store a loop with no size. This will output the storage results of the items enclosed in an element using the given loop tags.
      Parameters:
        `loopTag` - tag for enclosing element
        `items` - items to output
      Returns:
        writer for chaining

    - #### loop

          @NotNull
          public SimpleXmlWriter loop(@NotNull
                                               java.lang.String loopTag,
                                               @NotNull
                                               java.lang.String sizeAttr,
                                               @NotNull
                                               Countable<? extends XmlStorable> items)

      Store a sized loop with a size. This will output the storage results of the items enclosed in an element using the given loop tags and the given size attribute with the size of `items` as its value.
      Parameters:
        `loopTag` - tag for enclosing element
        `sizeAttr` - attribute for the size
        `items` - items to output
      Returns:
        writer for chaining

    - #### loop

          @NotNull
          public SimpleXmlWriter loop(@NotNull
                                               java.lang.String loopTag,
                                               @NotNull
                                               java.lang.String sizeAttr,
                                               @NotNull
                                               java.util.Collection<? extends XmlStorable> items)

      Store a sized loop with a size. This will output the storage results of the items enclosed in an element using the given loop tags and the given size attribute with the size of `items` as its value.
      Parameters:
        `loopTag` - tag for enclosing element
        `sizeAttr` - attribute for the size
        `items` - items to output
      Returns:
        writer for chaining

    - #### loop

          @NotNull
          public SimpleXmlWriter loop(@NotNull
                                               java.lang.String loopTag,
                                               @NotNull
                                               java.lang.String sizeAttr,
                                               @NotNull
                                               XmlStorable... items)

      Store a sized loop with a size. This will output the storage results of the items enclosed in an element using the given loop tags and the given size attribute with the size of `items` as its value.
      Parameters:
        `loopTag` - tag for enclosing element
        `sizeAttr` - attribute for the size
        `items` - items to output
      Returns:
        writer for chaining