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

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