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

See Also:

HtmlElement

Field Summary

Fields

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

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
XmlBuilder	addCDATA(CharSequence charData) Deprecated.
XmlBuilder	addComment(CharSequence comment) Deprecated.
XmlBuilder	addElement(String name) Create a new XmlBuilder for a required name and add it to children.
XmlBuilder	addRawText(Object value) Add an native text with no escaped characters, for example: XML code, JavaScript, CSS styles
XmlBuilder	addText(Object value) Add a text and escape special character
void	close() Close the Node
static XmlBuilder	forHtml(Appendable response) Create builder for HTML
static XmlBuilder	forNiceHtml(Appendable response)
int	getLevel()
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 XmlBuilder	nextChild(XmlBuilder element) Setup states
XmlBuilder	setAttribute(String name, Object value) Add an attribute
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

protected 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

@Nonnull
protected final String name

Element name

Constructor Detail

XmlBuilder

public XmlBuilder(@Nonnull
                  CharSequence name,
                  @Nonnull
                  XmlPrinter writer,
                  int level)

The new element constructor

Parameters:

name - The element name must not be empty nor special HTML characters.

XmlBuilder

protected XmlBuilder(@Nonnull
                     CharSequence name,
                     @Nonnull
                     XmlPrinter writer,
                     int level,
                     boolean printName)

The new element constructor

Parameters:

name - The element name must not be empty nor special HTML characters.

writer - A XmlPrinter

level - Level of the Element

printName - Print the element name immediately.

XmlBuilder

public XmlBuilder(@Nonnull
                  CharSequence name,
                  @Nonnull
                  XmlPrinter writer)

New element with a parent

Method Detail

getName

@Nonnull
public String getName()

Description copied from interface: ApiElement

Get an element name

Specified by:

getName in interface ApiElement<XmlBuilder>

nextChild

@Nonnull
protected XmlBuilder nextChild(@Nullable
                                        XmlBuilder element)

Setup states

Parameters:

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

addElement

@Nonnull
public final XmlBuilder addElement(@Nonnull
                                            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

@Nonnull
public final XmlBuilder setAttribute(@Nonnull
                                              String name,
                                              @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 XmlPrinter#writeValue(java.lang.Object, org.ujorm.tools.dom.XmlElement, java.lang.String, java.io.Writer) method, where the default implementation calls a toString() only.

Returns:

The original element

addText

@Nonnull
public final XmlBuilder addText(@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 XmlPrinter#writeValue(java.lang.Object, org.ujorm.tools.dom.XmlElement, java.lang.String, java.io.Writer) method, where the default implementation calls a toString() only.

Returns:

This instance

addRawText

@Nonnull
public final XmlBuilder addRawText(@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

@Nonnull
 @Deprecated
public final XmlBuilder addComment(@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

@Nonnull
 @Deprecated
public final XmlBuilder addCDATA(@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

@Nonnull
public String toString()

Render the XML code including header

Overrides:

toString in class Object

forHtml

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

Create builder for HTML

forNiceHtml

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