Package com.microstrategy.utils.xml

Class 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  

    • 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

    • 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

        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

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

      • 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