public class

XMLBuilder

extends Object
java.lang.Object
   ↳ com.microstrategy.utils.xml.XMLBuilder
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

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.

Summary

Nested Classes
class XMLBuilder.Element  
Fields
protected XMLBuilder.Element curElt The corrent element.
Public Constructors
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(StringBuffer _buf)
Constructs the instance with specified buffer.
XMLBuilder(StringBuffer _buf, boolean _encode)
Constructs the instance with specified buffer.
Public Methods
XMLBuilder addAttribute(String name, int value)
A shortcut method to add integer attributes.
XMLBuilder addAttribute(String name, String value, boolean singleQuot)
Adds an attribute to the current element.
final XMLBuilder addAttribute(String name, String value)
Adds an attribute to the current element.
XMLBuilder addAttributeCond(String name, int value)
A shortcut method to add integer attributes.
XMLBuilder addBoolAttribute(String name, boolean value)
A shortcut method to add boolean attributes.
XMLBuilder addBoolAttribute(String name)
A shortcut method to add boolean attributes.
XMLBuilder addChild(String tagName)
Adds a child element to the current element.
XMLBuilder addChildMixed(String tagName)
Adds a child element to the current element.
XMLBuilder addChildTo(String parentName, String tagName)
Adds a child element to the specified element.
XMLBuilder addRawAttribute(String name, 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.
final XMLBuilder addRawAttribute(String name, 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 addRawText(String text)
Use this "fast" method instead of addText when you are sure that the text does not contain special characters '<', '>', and '&'.
XMLBuilder addRawTextMixed(String text)
Use this "fast" method instead of addText when you are sure that the text does not contain special characters '<', '>', and '&'.
XMLBuilder addRawXML(String text)
Use this method to append arbitrary text to the buffer.
XMLBuilder addRawXML(StringBuffer text)
XMLBuilder addRequiredBoolAttribute(String name, boolean value)
A shortcut method to add a required boolean attributes.
XMLBuilder addSibling(String tagName)
Adds a sibling element to the current element.
XMLBuilder addSiblingTo(String name, String tagName)
Adds a sibling element to the specified element.
XMLBuilder addText(String text)
Adds text to the current element.
XMLBuilder addTextMixed(String text)
Adds text to the current element.
XMLBuilder addValueTag(String tag, int value)
Adds an integer element of format value
XMLBuilder addValueTag(String tag, float value)
XMLBuilder addValueTag(String tag, boolean value)
XMLBuilder addValueTag(String tag, 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(String name, boolean inclusive)
Closes all elements in the stack up to the specified element.
StringBuffer getBuffer()
Checks if XML building is complete, then returns the XML string buffer.
StringBuffer getRawBuffer()
Returns the XML string buffer in the current state.
void init(StringBuffer _buf)
This method is deprecated. use {link init(String) instead
void init(String _buf)
Resets the builder and copies the _buf content in the builder's buffer
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.
String toString()
Returns the string representation of this object.
Protected Methods
void closeTag()
StringBuffer getRawBufferInternal()
Check to see if the internal buffer has been allocated.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

protected XMLBuilder.Element curElt

The corrent element. The innermost not-closed element.

See Also

Public Constructors

public XMLBuilder ()

Default constructor constructs the builder with initial buffer size 1000.

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

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

public XMLBuilder (StringBuffer _buf)

Constructs the instance with specified buffer. Used for building embeded objects XML

Parameters
_buf the bufer where to store XML

public XMLBuilder (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

Public Methods

public XMLBuilder addAttribute (String name, int value)

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

public XMLBuilder addAttribute (String name, String value, boolean singleQuot)

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

public final XMLBuilder addAttribute (String name, String value)

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

public XMLBuilder addAttributeCond (String name, int value)

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

public XMLBuilder addBoolAttribute (String name, boolean value)

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

public XMLBuilder addBoolAttribute (String name)

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

public XMLBuilder addChild (String tagName)

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.

public XMLBuilder addChildMixed (String tagName)

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.

public XMLBuilder addChildTo (String parentName, String tagName)

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

public XMLBuilder addRawAttribute (String name, 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.

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

public final XMLBuilder addRawAttribute (String name, 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 '&'.

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

public XMLBuilder addRawText (String text)

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

public XMLBuilder addRawTextMixed (String text)

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.

public XMLBuilder addRawXML (String text)

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

public XMLBuilder addRawXML (StringBuffer text)

Throws
XMLBuilderException

public XMLBuilder addRequiredBoolAttribute (String name, boolean value)

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

public XMLBuilder addSibling (String tagName)

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.

public XMLBuilder addSiblingTo (String name, String tagName)

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

public XMLBuilder addText (String text)

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

public XMLBuilder addTextMixed (String text)

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.

public XMLBuilder addValueTag (String tag, int value)

Adds an integer element of format value

Parameters
tag tag name
value element value
Returns
  • the current XMLBuilder

public XMLBuilder addValueTag (String tag, float value)

public XMLBuilder addValueTag (String tag, boolean value)

public XMLBuilder addValueTag (String tag, String value)

Adds element of format value

Parameters
tag tag name
value element value
Returns
  • the current XMLBuilder

public XMLBuilder append (XMLBuilder builder)

Throws
XMLBuilderException

public XMLBuilder closeAll ()

Closes all elements in the stack. No further xml building is available after this call.

Returns
  • this
See Also

public XMLBuilder closeElement ()

Closes the current element (adds element closing tag) and removes it from the stack.

Returns
  • this
Throws
XMLBuilderException if there is no current element.

public XMLBuilder closeElements (String name, boolean inclusive)

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

public StringBuffer getBuffer ()

Checks if XML building is complete, then returns the XML string buffer.

Returns
  • XML string buffer.

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

public void init (StringBuffer _buf)

This method is 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.

public void init (String _buf)

Resets the builder and copies the _buf content in the builder's buffer

Parameters
_buf the buffer whose content to be copied.

public boolean isEncode ()

Returns true if encode flag is true

Returns
  • true if encode flag is true

public void printBuffer ()

Prints current buffer context (for debugging purposes).

public void reset ()

Cleanups the buffer and the stack so the builder can be reused for building another XML.

public String toString ()

Returns the string representation of this object.

Returns
  • A String representation of this object.

Protected Methods

protected void closeTag ()

protected 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