de.caff.util.xml

## Class SimpleXmlWriter

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

- Deprecated.
  this class has an improved substitute, see `SimpleXmlWriter`, where `open(String, Object...)` is renamed to `SimpleXmlWriter.begin(String, Object...)` and `close()` to `SimpleXmlWriter.end()`, which allows to make the class closable.

      @Deprecated
      public class SimpleXmlWriter
      extends java.lang.Object

  Simple XML writer.

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

  - 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 `open(String, Object...)` method writes an opening element with the given attributes' name-value pairs.
  - The `close()` method closes the element created by the latest `open(String, Object...)` call.
  - The `finish()` method closes all open elements.
  - 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` Deprecated. Is automatic wrapping enabled?
    `protected StringCollector` | `collector` Deprecated. Collector used for output text collection.
    `static java.lang.String` | `DEFAULT_ENCODING` Deprecated. Default encoding in XML header.
    `protected java.lang.String` | `indentation` Deprecated. Use as indentation if non-`null`.
    `protected java.util.Locale` | `locale` Deprecated. Locale to be used when formatting.

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `SimpleXmlWriter` | `cdata(java.lang.String text)` Deprecated. Outputs the raw text as CDATA section.
    `SimpleXmlWriter` | `close()` Deprecated. Close the latest open element.
    `SimpleXmlWriter` | `comment(java.lang.String comment)` Deprecated. Add a comment.
    `SimpleXmlWriter` | `element(java.lang.String tag, java.lang.Object... attributes)` Deprecated. Writes an empty element.
    `SimpleXmlWriter` | `expand(byte[] data)` Deprecated. Convert data into hex code and add it as text.
    `static java.lang.String` | `expand(byte[] data, int columns)` Deprecated. Expand an array of bytes into a hex string.
    `SimpleXmlWriter` | `expandBase64(byte[] data)` Deprecated. Convert data into hex code and add it as text.
    `void` | `finish()` Deprecated. Close all open elements.
    `static java.lang.String` | `getDefaultPreamble()` Deprecated. Get the default XML preamble with UTF-8 encoding.
    `java.lang.String` | `getIndentation()` Deprecated. Get the indentation.
    `java.util.Locale` | `getLocale()` Deprecated. Get the locale used for formatting text.
    `static java.lang.String` | `getPreamble(java.lang.String encoding)` Deprecated. Get an XML preamble with the given encoding.
    `boolean` | `isAutoWrap()` Deprecated. Is automatic wrapping enabled?
    `SimpleXmlWriter` | `nl()` Deprecated. Add a newline.
    `SimpleXmlWriter` | `open(java.lang.String tag, java.lang.Object... attributes)` Deprecated. Write the opening tag of an element.
    `SimpleXmlWriter` | `text(java.lang.Object text)` Deprecated. Add text outside of tags.
    `SimpleXmlWriter` | `textf(java.lang.String format, java.lang.Object... args)` Deprecated. 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

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

    - #### collector

          @NotNull
          protected final StringCollector collector

      Deprecated.
      Collector used for output text collection.

    - #### autoWrap

          protected final boolean autoWrap

      Deprecated.
      Is automatic wrapping enabled?

    - #### indentation

          @Nullable
          protected final java.lang.String indentation

      Deprecated.
      Use as indentation if non-`null`.

    - #### locale

          @NotNull
          protected final java.util.Locale locale

      Deprecated.
      Locale to be used when formatting.

  - ### Constructor Detail

    - #### SimpleXmlWriter

          public SimpleXmlWriter(@NotNull
                                 StringCollector collector)

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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()

      Deprecated.
      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()

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

    - #### getLocale

          @NotNull
          public java.util.Locale getLocale()

      Deprecated.
      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()

      Deprecated.
      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)

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

    - #### open

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

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

    - #### close

          @NotNull
          public SimpleXmlWriter close()

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

    - #### comment

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

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

    - #### expand

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

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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)

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

    - #### text

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

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

    - #### textf

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

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

    - #### nl

          @NotNull
          public SimpleXmlWriter nl()

      Deprecated.
      Add a newline.
      Returns:
        writer for chaining

    - #### cdata

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

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

    - #### finish

          public void finish()

      Deprecated.
      Close all open elements.