java.lang.Object
- com.microstrategy.utils.xml.XMLBuilder

Direct Known Subclasses:

XMLStateSerializer
```
public class XMLBuilder
extends java.lang.Object
```
The purpose of this class is to assist in the creation of well-formed XML documents directly in the string buffer. This class helps in this process by automatically inserting in the buffer tag brackets and element closing tags, replacing special characters in the text and attribute values with proper entities and detecting programming errors that lead to the XML format errors. The process of building XML string using this class is much alike the process of building DOM object. Here is a small example:
```
    XMLBuilder builder = new XMLBuilder();
    builder.addChild("root");
    builder.addAttribute("atr1", "val1");
    builder.addChild("e1");
    builder.addAttribute("atr2", "val2");
    builder.addSibling("e2");
    builder.addText("Some text");
    builder.addSibling("e3");
    builder.addText("Another text");
    builder.closeAll();
    System.out.println(builder.getBuffer().toString());
 
```
This example will produce the following output:
```
 Some textAnother text
 
```
Most class methods return reference to itself (this), which allows to chain calls. For example above code can be rewritten like this:
```
      builder = new XMLBuilder();
      builder.addChild("root").addAttribute("atr1", "val1")
        .addChild("e1").addAttribute("atr2", "val2")
        .addSibling("e2").addText("Some text")
        .addSibling("e3").addText("Another text")
      .closeAll();
      System.out.println(builder.getBuffer().toString());
 
```
Because XML is built directly in the buffer the process must be sequential. You must add all attributes before adding child elements or text to an element. You must add all children to the element before adding siblings to it or any of it parents. The XMLBuilder detects incorrect sequences of calls and throws the XMLBuilderException with proper message. Notice that tis exception is unchecked. Notice also that for sake of performance we don't check for all possible errors. In particular we don't check for incorrect element and attribute names and for uniqueness of attribute names. We also provide some "fast" methods that add fragments to the buffer without checking them. Itâs the programmer responsibility to ensure that those fragments a correct and wonât lead to XML errors.
Internally we maintain a stack of not-closed element tags. The head of the stack is called the current element and represents the innermost not-closed element. The notion of stack and current element are used in method documentation to explain their effects.
Since:

MicroStrategy Web 7.3.1 or earlier

Nested Class Summary

Nested Classes
Modifier and Type Class Description

protected class XMLBuilder.Element

Field Summary

Fields
Modifier and Type Field Description

protected XMLBuilder.Element curElt
The corrent element.

Constructor Summary

Constructors
Constructor	Description
`XMLBuilder()`	Default constructor constructs the builder with initial buffer size 1000.
`XMLBuilder(int _bufSize)`	Constructs the instance with specified buffer size.
`XMLBuilder(int _bufSize, boolean _encode)`	Constructs the instance with specified buffer size.
`XMLBuilder(java.lang.StringBuffer _buf)`	Constructs the instance with specified buffer.
`XMLBuilder(java.lang.StringBuffer _buf, boolean _encode)`	Constructs the instance with specified buffer.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`XMLBuilder`	`addAttribute(java.lang.String name, int value)`	A shortcut method to add integer attributes.
`XMLBuilder`	`addAttribute(java.lang.String name, java.lang.String value)`	Adds an attribute to the current element.
`XMLBuilder`	`addAttribute(java.lang.String name, java.lang.String value, boolean singleQuot)`	Adds an attribute to the current element.
`XMLBuilder`	`addAttributeCond(java.lang.String name, int value)`	A shortcut method to add integer attributes.
`XMLBuilder`	`addBoolAttribute(java.lang.String name)`	A shortcut method to add boolean attributes.
`XMLBuilder`	`addBoolAttribute(java.lang.String name, boolean value)`	A shortcut method to add boolean attributes.
`XMLBuilder`	`addChild(java.lang.String tagName)`	Adds a child element to the current element.
`XMLBuilder`	`addChildMixed(java.lang.String tagName)`	Adds a child element to the current element.
`XMLBuilder`	`addChildTo(java.lang.String parentName, java.lang.String tagName)`	Adds a child element to the specified element.
`XMLBuilder`	`addRawAttribute(java.lang.String name, java.lang.String value)`	Use this "fast" method instead of `addAttribute(String, String)` when you are sure that the attribute value does not contain special characters '"' and '&'.
`XMLBuilder`	`addRawAttribute(java.lang.String name, java.lang.String value, boolean singleQuot)`	Use this "fast" method instead of `addAttribute(String, String, boolean)` when you are sure that the attribute value does not contain special character '&' and single or double quotes depending on the `singleCode` value.
`XMLBuilder`	`addRawText(java.lang.String text)`	Use this "fast" method instead of `addText` when you are sure that the text does not contain special characters '<', '>', and '&'.
`XMLBuilder`	`addRawTextMixed(java.lang.String text)`	Use this "fast" method instead of `addText` when you are sure that the text does not contain special characters '<', '>', and '&'.
`XMLBuilder`	`addRawXML(java.lang.String text)`	Use this method to append arbitrary text to the buffer.
`XMLBuilder`	`addRawXML(java.lang.StringBuffer text)`
`XMLBuilder`	`addRequiredBoolAttribute(java.lang.String name, boolean value)`	A shortcut method to add a required boolean attributes.
`XMLBuilder`	`addSibling(java.lang.String tagName)`	Adds a sibling element to the current element.
`XMLBuilder`	`addSiblingTo(java.lang.String name, java.lang.String tagName)`	Adds a sibling element to the specified element.
`XMLBuilder`	`addText(java.lang.String text)`	Adds text to the current element.
`XMLBuilder`	`addTextMixed(java.lang.String text)`	Adds text to the current element.
`XMLBuilder`	`addValueTag(java.lang.String tag, boolean value)`
`XMLBuilder`	`addValueTag(java.lang.String tag, float value)`
`XMLBuilder`	`addValueTag(java.lang.String tag, int value)`	Adds an integer element of format value
`XMLBuilder`	`addValueTag(java.lang.String tag, java.lang.String value)`	Adds element of format value
`XMLBuilder`	`append(XMLBuilder builder)`
`XMLBuilder`	`closeAll()`	Closes all elements in the stack.
`XMLBuilder`	`closeElement()`	Closes the current element (adds element closing tag) and removes it from the stack.
`XMLBuilder`	`closeElements(java.lang.String name, boolean inclusive)`	Closes all elements in the stack up to the specified element.
`protected void`	`closeTag()`
`java.lang.StringBuffer`	`getBuffer()`	Checks if XML building is complete, then returns the XML string buffer.
`java.lang.StringBuffer`	`getRawBuffer()`	Returns the XML string buffer in the current state.
`protected java.lang.StringBuffer`	`getRawBufferInternal()`	Check to see if the internal buffer has been allocated.
`void`	`init(java.lang.String _buf)`	Resets the builder and copies the _buf content in the builder's buffer
`void`	`init(java.lang.StringBuffer _buf)`	Deprecated. use {link `init(String)` instead
`boolean`	`isEncode()`	Returns true if encode flag is true
`void`	`printBuffer()`	Prints current buffer context (for debugging purposes).
`void`	`reset()`	Cleanups the buffer and the stack so the builder can be reused for building another XML.
`java.lang.String`	`toString()`	Returns the string representation of this object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - curElt
```
protected XMLBuilder.Element curElt
```
    The corrent element. The innermost not-closed element.
    
    See Also:
    
    XMLBuilder.Element
- Constructor Detail
  - XMLBuilder
```
public XMLBuilder()
```
    Default constructor constructs the builder with initial buffer size 1000.
  - XMLBuilder
```
public XMLBuilder(int _bufSize)
```
    Constructs the instance with specified buffer size. Use this constructor to improve performance by reducing the number of times the buffer will be reallocated during XML creation. You can use the size of original XML string to guess correct buffer size.
    
    Parameters:
    
    _bufSize - the initial buffer size
  - XMLBuilder
```
public XMLBuilder(int _bufSize,
                  boolean _encode)
```
    Constructs the instance with specified buffer size. Use this constructor to improve performance by reducing the number of times the buffer will be reallocated during XML creation. You can use the size of original XML string to guess correct buffer size.
    
    Parameters:
    
    _bufSize - the initial buffer size
    
    _encode - flag indicating that XML must be encodded
  - XMLBuilder
```
public XMLBuilder(java.lang.StringBuffer _buf)
```
    Constructs the instance with specified buffer. Used for building embeded objects XML
    
    Parameters:
    
    _buf - the bufer where to store XML
  - XMLBuilder
```
public XMLBuilder(java.lang.StringBuffer _buf,
                  boolean _encode)
```
    Constructs the instance with specified buffer. Used for building embeded objects XML
    
    Parameters:
    
    _buf - the bufer where to store XML
    
    _encode - flag indicating that XML must be encodded
- Method Detail
  - reset
```
public void reset()
```
    Cleanups the buffer and the stack so the builder can be reused for building another XML.
  - init
```
@Deprecated
public void init(java.lang.StringBuffer _buf)
```
    Deprecated.
    use {link init(String) instead
    
    Resets the builder and copies the _buf content in the builder's buffer
    
    Parameters:
    
    _buf - the buffer whose content to be copied.
    
    Since:
    
    MicroStrategy Web 8.0.0
  - init
```
public void init(java.lang.String _buf)
```
    Resets the builder and copies the _buf content in the builder's buffer
    
    Parameters:
    
    _buf - the buffer whose content to be copied.
    
    Since:
    
    MicroStrategy Web 9.0.0
  - isEncode
```
public boolean isEncode()
```
    Returns true if encode flag is true
    
    Returns:
    
    true if encode flag is true
  - addChild
```
public XMLBuilder addChild(java.lang.String tagName)
                    throws XMLBuilderException
```
    Adds a child element to the current element.
    
    Parameters:
    
    tagName - a tag name of the new element.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element already contains text (we don't allow mixed content) or if document already complete.
  - addChildMixed
```
public XMLBuilder addChildMixed(java.lang.String tagName)
                         throws XMLBuilderException
```
    Adds a child element to the current element. In contrast ot the {link #addChild} method this method can be used even after a text was added to the parent element. Therefor it allows to crated mixed content elements.
    
    Parameters:
    
    tagName - a tag name of the new element.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element already contains text (we don't allow mixed content) or if document already complete.
  - addChildTo
```
public XMLBuilder addChildTo(java.lang.String parentName,
                             java.lang.String tagName)
                      throws XMLBuilderException
```
    Adds a child element to the specified element. Closes all elements in stack up to (but excluding) parentName element, then adds a child element to it.
    
    Parameters:
    
    parentName - a paren element name. This element must be presently in the stack.
    
    tagName - a tag name of the new element.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the parent element not found in the stack or if it already contains text (we don't allow mixed content).
  - addSibling
```
public XMLBuilder addSibling(java.lang.String tagName)
                      throws XMLBuilderException
```
    Adds a sibling element to the current element.
    
    Parameters:
    
    tagName - a tag name of the new element.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if there is no current element or the current element is root of the document.
  - addSiblingTo
```
public XMLBuilder addSiblingTo(java.lang.String name,
                               java.lang.String tagName)
                        throws XMLBuilderException
```
    Adds a sibling element to the specified element. Closes all elements in stack up to (and including) name element, then adds a child element to the new current element.
    
    Parameters:
    
    name - a name of the element to which a sibling must be added. This element must be presently in the stack and must not be a root element.
    
    tagName - a tag name of the new element.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the requested element not found in the stack or if it is a root element
  - addAttribute
```
public final XMLBuilder addAttribute(java.lang.String name,
                                     java.lang.String value)
                              throws XMLBuilderException
```
    Adds an attribute to the current element. Attributes value will be wrapped in double quotes.
    
    Parameters:
    
    name - an attribute name.
    
    value - an attribute value.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element tag is closed (element already contains children or text).
  - addAttribute
```
public XMLBuilder addAttribute(java.lang.String name,
                               java.lang.String value,
                               boolean singleQuot)
                        throws XMLBuilderException
```
    Adds an attribute to the current element. Depending on the singleQuot parameter value the attribute value will be wrapped either in single or double quotes.
    
    Parameters:
    
    name - an attribute name.
    
    value - an attribute value.
    
    singleQuot - a flag indicating weather to wrap attribute value in simgle or double quotes.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element tag is closed (element already contains children or text).
  - addAttribute
```
public XMLBuilder addAttribute(java.lang.String name,
                               int value)
                        throws XMLBuilderException
```
    A shortcut method to add integer attributes.
    
    Parameters:
    
    name - an attribute name.
    
    value - an attribute value.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element tag is closed (element already contains children or text).
  - addAttributeCond
```
public XMLBuilder addAttributeCond(java.lang.String name,
                                   int value)
                            throws XMLBuilderException
```
    A shortcut method to add integer attributes. It adds attribut only if it is not equal to -1
    
    Parameters:
    
    name - an attribute name.
    
    value - an attribute value.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element tag is closed (element already contains children or text).
  - addBoolAttribute
```
public XMLBuilder addBoolAttribute(java.lang.String name)
                            throws XMLBuilderException
```
    A shortcut method to add boolean attributes. The attribute format will be name="1".
    
    Parameters:
    
    name - an attribute name.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element tag is closed (element already contains children or text).
  - addBoolAttribute
```
public XMLBuilder addBoolAttribute(java.lang.String name,
                                   boolean value)
                            throws XMLBuilderException
```
    A shortcut method to add boolean attributes. The attribute will be added only if the value is true. The attribute format will be name="1"
    
    Parameters:
    
    name - an attribute name.
    
    value - an attribute value.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element tag is closed (element already contains children or text). See #addRequiredBoolAttribute
  - addRequiredBoolAttribute
```
public XMLBuilder addRequiredBoolAttribute(java.lang.String name,
                                           boolean value)
                                    throws XMLBuilderException
```
    A shortcut method to add a required boolean attributes. The attribute will be added regardles of whether the value is true or flase. The attribute format will be name="1" or name="0".
    
    Parameters:
    
    name - an attribute name.
    
    value - an attribute value.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element tag is closed (element already contains children or text). See #addBoolAttribute
  - addRawAttribute
```
public final XMLBuilder addRawAttribute(java.lang.String name,
                                        java.lang.String value)
                                 throws XMLBuilderException
```
    Use this "fast" method instead of addAttribute(String, String) when you are sure that the attribute value does not contain special characters '"' and '&'.
    
    Parameters:
    
    name - an attribute name.
    
    value - an attribute value.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element tag is closed (element already contains children or text).
  - addRawAttribute
```
public XMLBuilder addRawAttribute(java.lang.String name,
                                  java.lang.String value,
                                  boolean singleQuot)
                           throws XMLBuilderException
```
    Use this "fast" method instead of addAttribute(String, String, boolean) when you are sure that the attribute value does not contain special character '&' and single or double quotes depending on the singleCode value.
    
    Parameters:
    
    name - an attribute name.
    
    value - an attribute value.
    
    singleQuot - a flag indicating weather to wrap attribute value in simgle or double quotes.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if the current element tag is closed (element already contains children or text).
  - addText
```
public XMLBuilder addText(java.lang.String text)
                   throws XMLBuilderException
```
    Adds text to the current element. This method does not allow mixed content in the parent element
    
    Parameters:
    
    text - a text to add
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if there is no current element or if the current element already contains children (we don't allow mixed content).
  - addTextMixed
```
public XMLBuilder addTextMixed(java.lang.String text)
                        throws XMLBuilderException
```
    Adds text to the current element. This method does allow mixed content in the parent element
    
    Parameters:
    
    text - a text to add
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if there is no current element.
  - addRawText
```
public XMLBuilder addRawText(java.lang.String text)
                      throws XMLBuilderException
```
    Use this "fast" method instead of addText when you are sure that the text does not contain special characters '<', '>', and '&'. This method does not allow mixed content in the parent element.
    
    Parameters:
    
    text - a text to add
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if there is no current element or if the current element already contains children (we don't allow mixed content).
  - addRawTextMixed
```
public XMLBuilder addRawTextMixed(java.lang.String text)
                           throws XMLBuilderException
```
    Use this "fast" method instead of addText when you are sure that the text does not contain special characters '<', '>', and '&'. This method does allow mixed content in the parent element.
    
    Parameters:
    
    text - a text to add
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if there is no current element.
  - addRawXML
```
public XMLBuilder addRawXML(java.lang.String text)
                     throws XMLBuilderException
```
    Use this method to append arbitrary text to the buffer. No validation is made.
    
    Parameters:
    
    text - a text to add
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if there is no current element or if the current element already contains children (we don't allow mixed content).
  - addValueTag
```
public XMLBuilder addValueTag(java.lang.String tag,
                              int value)
```
    Adds an integer element of format value
    
    Parameters:
    
    tag - tag name
    
    value - element value
    
    Returns:
    
    the current XMLBuilder
    
    Since:
    
    MicroStrategy Web 8.0.0
  - addValueTag
```
public XMLBuilder addValueTag(java.lang.String tag,
                              float value)
```
    Since:
    
    MicroStrategy Web 9.0.0
  - addValueTag
```
public XMLBuilder addValueTag(java.lang.String tag,
                              java.lang.String value)
```
    Adds element of format value
    
    Parameters:
    
    tag - tag name
    
    value - element value
    
    Returns:
    
    the current XMLBuilder
    
    Since:
    
    MicroStrategy Web 8.0.0
  - addValueTag
```
public XMLBuilder addValueTag(java.lang.String tag,
                              boolean value)
```
    Since:
    
    MicroStrategy Web 8.1.0
  - closeElement
```
public XMLBuilder closeElement()
                        throws XMLBuilderException
```
    Closes the current element (adds element closing tag) and removes it from the stack.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if there is no current element.
  - closeElements
```
public XMLBuilder closeElements(java.lang.String name,
                                boolean inclusive)
                         throws XMLBuilderException
```
    Closes all elements in the stack up to the specified element. If the inclusive parameter is true the spicified element will be also closed.
    
    Parameters:
    
    name - the name of the element in the stack.
    
    inclusive - When this parameter is true, the specified ellement will be closed also.
    
    Returns:
    
    this
    
    Throws:
    
    XMLBuilderException - if specified element is not in the stack.
    
    See Also:
    
    closeElement
  - closeAll
```
public XMLBuilder closeAll()
```
    Closes all elements in the stack. No further xml building is available after this call.
    
    Returns:
    
    this
    
    See Also:
    
    closeElement
  - getBuffer
```
public java.lang.StringBuffer getBuffer()
```
    Checks if XML building is complete, then returns the XML string buffer.
    
    Returns:
    
    XML string buffer.
  - toString
```
public java.lang.String toString()
```
    Returns the string representation of this object.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    A String representation of this object.
    
    Since:
    
    MicroStrategy Web 8.0.0
  - getRawBuffer
```
public java.lang.StringBuffer getRawBuffer()
```
    Returns the XML string buffer in the current state. No checks are made if the XML creation is complete.
    
    Returns:
    
    XML string buffer.
  - closeTag
```
protected void closeTag()
```
  - printBuffer
```
public void printBuffer()
```
    Prints current buffer context (for debugging purposes).
  - addRawXML
```
public XMLBuilder addRawXML(java.lang.StringBuffer text)
                     throws XMLBuilderException
```
    Throws:
    
    XMLBuilderException
    
    Since:
    
    MicroStrategy Web 8.1.1
  - append
```
public XMLBuilder append(XMLBuilder builder)
                  throws XMLBuilderException
```
    Throws:
    
    XMLBuilderException
    
    Since:
    
    MicroStrategy Web 8.1.1
  - getRawBufferInternal
```
protected java.lang.StringBuffer getRawBufferInternal()
```
    Check to see if the internal buffer has been allocated. Allocates the buffer if it doesn't exist and returns the buffer without any further checks.
    
    Returns:
    
    StringBuffer raw buffer used for this XMLBuilder
    
    Since:
    
    MicroStrategy Web 9.0.1

Class XMLBuilder

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

curElt

Constructor Detail

XMLBuilder

XMLBuilder

XMLBuilder

XMLBuilder

XMLBuilder

Method Detail

reset

init

init

isEncode

addChild

addChildMixed

addChildTo

addSibling

addSiblingTo

addAttribute

addAttribute

addAttribute

addAttributeCond

addBoolAttribute

addBoolAttribute

addRequiredBoolAttribute

addRawAttribute

addRawAttribute

addText

addTextMixed

addRawText

addRawTextMixed

addRawXML

addValueTag

addValueTag

addValueTag

addValueTag

closeElement

closeElements

closeAll

getBuffer

toString

getRawBuffer

closeTag

printBuffer

addRawXML

append

getRawBufferInternal