org.ujorm.tools.xml.builder

Class XmlBuilder

java.lang.Object

org.ujorm.tools.xml.builder.XmlBuilder

All Implemented Interfaces:

Closeable, AutoCloseable, ApiElement<XmlBuilder>

public class XmlBuilder
extends Object
implements ApiElement<XmlBuilder>

A XML builder. The main benefits are:

• secure building well-formed XML documents by the Java code
• a simple API built on a single XmlElement class
• creating XML components by a subclass is possible
• great performance and small memory footprint

¨

How to use the class:

  XmlPriter writer = XmlPriter.forXml();
  try (XmlBuilder html = new XmlBuilder(Html.HTML, writer)) {
      try (XmlBuilder head = html.addElement(Html.HEAD)) {
          head.addElement(Html.META, Html.A_CHARSET, UTF_8);
          head.addElement(Html.TITLE).addText("Test");
      }
      ry (XmlBuilder body = html.addElement(Html.BODY)) {
          body.addElement(Html.H1).addText("Hello word!");
          body.addElement(Html.DIV).addText(null);
      }
  };
  String result = writer.toString();
 

The XmlElement class implements the Closeable implementation for an optional highlighting the tree structure in the source code.

Since:

1.86

Author:

Pavel Ponec

Field Summary

Fields

Modifier and Type	Field and Description
static String	HTML The HTML tag name
protected @Nullable String	name Element name
protected static String	REQUIRED_MSG Assertion message template

Fields inherited from interface org.ujorm.tools.xml.ApiElement

HIDDEN_NAME

Constructor Summary

Constructors

Modifier	Constructor and Description
	XmlBuilder(@NotNull String name, @NotNull XmlPrinter writer) New element with a parent
	XmlBuilder(@Nullable String name, @NotNull XmlPrinter writer, int level) The new element constructor
protected	XmlBuilder(@Nullable String name, @NotNull XmlPrinter writer, int level, boolean printName) The new element constructor

Method Summary

Modifier and Type	Method and Description
@NotNull XmlBuilder	addCDATA(@Nullable CharSequence charData) Deprecated.
@NotNull XmlBuilder	addComment(@Nullable CharSequence comment) Deprecated.
@NotNull XmlBuilder	addElement(@NotNull String name) Create a new XmlBuilder for a required name and add it to children.
@NotNull XmlBuilder	addRawText(@Nullable Object value) Add an native text with no escaped characters, for example: XML code, JavaScript, CSS styles
@NotNull XmlBuilder	addText(@Nullable Object value) Add a text and escape special character
@NotNull XmlBuilder	addTextTemplated(@Nullable CharSequence template, Object... values) Message template with hight performance.
void	close() Close the Node
static @NotNull XmlBuilder	forHtml(@NotNull Appendable response) Create builder for HTML
static @NotNull XmlBuilder	forNiceHtml(@NotNull Appendable response)
int	getLevel()
@Nullable String	getName() Get an element name
XmlPrinter	getWriter() Writer
boolean	isClosed() Is the node closed?
boolean	isFilled()
boolean	isLastText() The last child was a text
protected @Nullable XmlBuilder	nextChild(@Nullable XmlBuilder element) Setup states
@NotNull XmlBuilder	setAttribute(@Nullable String name, @Nullable Object value) Add an attribute
@NotNull String	toString() Render the XML code including header

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.ujorm.tools.xml.ApiElement

setAttrib

Field Detail

HTML

public static final String HTML

The HTML tag name

See Also:

Constant Field Values

REQUIRED_MSG

protected static final String REQUIRED_MSG

Assertion message template

See Also:

Constant Field Values

name

@Nullable
protected final @Nullable String name

Element name

Constructor Detail

XmlBuilder

public XmlBuilder(@Nullable
                  @Nullable String name,
                  @NotNull
                  @NotNull XmlPrinter writer,
                  int level)

The new element constructor

Parameters:

name - The element name must not be special HTML characters. The null value is intended to build a root of AJAX queries.

XmlBuilder

protected XmlBuilder(@Nullable
                     @Nullable String name,
                     @NotNull
                     @NotNull XmlPrinter writer,
                     int level,
                     boolean printName)

The new element constructor

Parameters:

name - The element name must not be special HTML characters. The null value is intended to build a root of AJAX queries.

writer - A XmlPrinter

level - Level of the Element

printName - Print the element name immediately.

XmlBuilder

public XmlBuilder(@NotNull
                  @NotNull String name,
                  @NotNull
                  @NotNull XmlPrinter writer)

New element with a parent

Method Detail

getName

@Nullable
public @Nullable String getName()

Description copied from interface: ApiElement

Get an element name

Specified by:

getName in interface ApiElement<XmlBuilder>

nextChild

@Nullable
protected @Nullable XmlBuilder nextChild(@Nullable
                                                   @Nullable XmlBuilder element)

Setup states

Parameters:

element - A child Node or null value for a text data

addElement

@NotNull
public final @NotNull XmlBuilder addElement(@NotNull
                                                     @NotNull String name)

Create a new XmlBuilder for a required name and add it to children.

Specified by:

addElement in interface ApiElement<XmlBuilder>

Parameters:

name - A name of the new XmlElement is required.

Returns:

The new XmlElement!

setAttribute

@NotNull
public final @NotNull XmlBuilder setAttribute(@Nullable
                                                       @Nullable String name,
                                                       @Nullable
                                                       @Nullable Object value)

Add an attribute

Specified by:

setAttribute in interface ApiElement<XmlBuilder>

Parameters:

name - Required element name

value - The null value is ignored. Formatting is performed by the AbstractWriter.writeValue(Object, ApiElement, String) method, where the default implementation calls a toString() only.

Returns:

The original element

addText

@NotNull
public final @NotNull XmlBuilder addText(@Nullable
                                                  @Nullable Object value)

Add a text and escape special character

Specified by:

addText in interface ApiElement<XmlBuilder>

Parameters:

value - The null value is allowed. Formatting is performed by the AbstractWriter.writeValue(Object, ApiElement, String) method, where the default implementation calls a toString() only.

Returns:

This instance

addTextTemplated

@NotNull
public final @NotNull XmlBuilder addTextTemplated(@Nullable
                                                           @Nullable CharSequence template,
                                                           @NotNull
                                                           Object... values)

Message template with hight performance.

Specified by:

addTextTemplated in interface ApiElement<XmlBuilder>

Parameters:

template - Message template where parameters are marked by the {} symbol

values - argument values

Returns:

The original builder

addRawText

@NotNull
public final @NotNull XmlBuilder addRawText(@Nullable
                                                     @Nullable Object value)

Add an native text with no escaped characters, for example: XML code, JavaScript, CSS styles

Specified by:

addRawText in interface ApiElement<XmlBuilder>

Parameters:

value - The null value is ignored.

Returns:

This instance

addComment

@NotNull
 @Deprecated
public final @NotNull XmlBuilder addComment(@Nullable
                                                                  @Nullable CharSequence comment)

Deprecated.

Add a comment text. The CDATA structure isn't really for HTML at all.

Specified by:

addComment in interface ApiElement<XmlBuilder>

Parameters:

comment - A comment text must not contain a string --> .

Returns:

This instance

addCDATA

@NotNull
 @Deprecated
public final @NotNull XmlBuilder addCDATA(@Nullable
                                                                @Nullable CharSequence charData)

Deprecated.

Add a character data in CDATA format to XML only. The CDATA structure isn't really for HTML at all.

Specified by:

addCDATA in interface ApiElement<XmlBuilder>

Parameters:

charData - A text including the final DATA sequence. An empty argument is ignored.

Returns:

This instance

close

public final void close()

Close the Node

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in interface ApiElement<XmlBuilder>

isClosed

public boolean isClosed()

Is the node closed?

getLevel

public int getLevel()

isFilled

public boolean isFilled()

isLastText

public boolean isLastText()

The last child was a text

getWriter

public XmlPrinter getWriter()

Writer

toString

@NotNull
public @NotNull String toString()

Render the XML code including header

Overrides:

toString in class Object

forHtml

@NotNull
public static @NotNull XmlBuilder forHtml(@NotNull
                                                   @NotNull Appendable response)

Create builder for HTML

forNiceHtml

@NotNull
public static @NotNull XmlBuilder forNiceHtml(@NotNull
                                                       @NotNull Appendable response)