Interface XMLTag

  • All Known Implementing Classes:
    XMLDoc

    public interface XMLTag
    Enables you to build, parse, navigate, modify XML documents through a simple and intuitive fluent interface.

    XMLTag is not thread-safe and cannot be considered so, even for non mutating methods. This is due to the current location which needs to be kept, as we work in a fluent interface style.

    Author:
    Mathieu Carbou (mathieu.carbou@gmail.com)
    • Method Detail

      • addNamespace

        XMLTag addNamespace​(String prefix,
                            String namespaceURI)
        Add a namespace to the document
        Parameters:
        prefix - The prefix of the namespace
        namespaceURI - The URI of the namespace
        Returns:
        this
      • addTag

        XMLTag addTag​(String name)
        Create a tag under the current location and use it as the current node
        Parameters:
        name - Name of the element to add
        Returns:
        this
      • addAttribute

        XMLTag addAttribute​(String name,
                            String value)
        Create a new attribute for the current node
        Parameters:
        name - Name of the attribute to add
        value - value of the attribute to add
        Returns:
        this
      • addText

        XMLTag addText​(String text)
        Add a text node under the current node, and jump to the parent node. This enables the create or quick documents like this:

        addTag("name").addText("Bob")addTag("sex").addText("M")addTag("age").addText("30")

        <name>Bob</name><sex>M</sex><age>30</age>

        Parameters:
        text - the text to add
        Returns:
        this
      • addCDATA

        XMLTag addCDATA​(String data)
        Add a data node under the current node, and jump to the parent node. This enables the create or quick documents like this:

        addTag("name").addCDATA("Bob")addTag("sex").addCDATA("M")addTag("age").addCDATA("30")

        <name><![CDATA[Bob]]></name><sex><![CDATA[M]]></sex><age><![CDATA[30]]></age>

        Parameters:
        data - the data to add
        Returns:
        this
      • addDocument

        XMLTag addDocument​(XMLTag tag)
        Inserts another XMLTag instance under the current tag. The whole document will be inserted.
        Parameters:
        tag - The XMLTag instance to insert
        Returns:
        this
      • addDocument

        XMLTag addDocument​(Document doc)
        Inserts another Document instance under the current tag
        Parameters:
        doc - The Document instance to insert
        Returns:
        this
      • addTag

        XMLTag addTag​(XMLTag tag)
        Inserts another XMLTag tag hierarchy under the current tag. Only the current tag of the given document will be inserted with its hierarchy, not the whole document.
        Parameters:
        tag - The XMLTag current tag hierarchy to insert
        Returns:
        this
      • addTag

        XMLTag addTag​(Element tag)
        Inserts a Element instance and its hierarchy under the current tag
        Parameters:
        tag - The Element instance to insert
        Returns:
        this
      • addAttribute

        XMLTag addAttribute​(Attr attr)
        Add given attribute to current element
        Parameters:
        attr - The attribute to insert
        Returns:
        this
      • addText

        XMLTag addText​(Text text)
        Add a text note to the current tag
        Parameters:
        text - The node to insert
        Returns:
        this
      • addCDATA

        XMLTag addCDATA​(CDATASection data)
        Add a CDATA note to the current tag
        Parameters:
        data - The node to insert
        Returns:
        this
      • gotoParent

        XMLTag gotoParent()
        Go to parent tag. Do nothing if we are already at root
        Returns:
        this
      • gotoRoot

        XMLTag gotoRoot()
        Go to document root tag
        Returns:
        this
      • gotoTag

        XMLTag gotoTag​(String relativeXpath,
                       Object... arguments)
                throws XMLDocumentException
        Go to a specific node
        Parameters:
        relativeXpath - XPath expresion
        arguments - to be replaced in xpath expression before compiling. Uses String.format() to build XPath expression.
        Returns:
        this
        Throws:
        XMLDocumentException - if the node does not exist or if the XPath expression is invalid
      • gotoChild

        XMLTag gotoChild​(int i)
                  throws XMLDocumentException
        Go to the Nth child of the curent node.
        Parameters:
        i - index of the child, from 1 to child element number
        Returns:
        this
        Throws:
        XMLDocumentException - If the child node does not exist
      • gotoChild

        XMLTag gotoChild​(String nodeName)
                  throws XMLDocumentException
        Go to the child found with given node name
        Parameters:
        nodeName - name of the child to find.
        Returns:
        this
        Throws:
        XMLDocumentException - If the element with this name has not been found or if there are too many elements
      • gotoFirstChild

        XMLTag gotoFirstChild​(String name)
                       throws XMLDocumentException
        Go to the first child occurance found having given name
        Parameters:
        name - Name of the child to go at
        Returns:
        this
        Throws:
        XMLDocumentException - If the current node has no child at all
      • gotoLastChild

        XMLTag gotoLastChild​(String name)
                      throws XMLDocumentException
        Go to the last child occurance found having given name
        Parameters:
        name - Name of the child to go at
        Returns:
        this
        Throws:
        XMLDocumentException - If the current node has no child at all
      • hasTag

        boolean hasTag​(String relativeXpath,
                       Object... arguments)
        Check if a tag exist in the document
        Parameters:
        relativeXpath - XPath expression where the tag should be located
        arguments - XPath arguments. Uses String.format() to build XPath expression.
        Returns:
        true if the tag is exist
      • hasAttribute

        boolean hasAttribute​(String name,
                             String relativeXpath,
                             Object... arguments)
                      throws XMLDocumentException
        Check if targeted tag has an attribute of given name
        Parameters:
        name - the name of the attribute
        relativeXpath - XPath that target the tag
        arguments - optional arguments of xpath expression. Uses String.format() to build XPath expression.
        Returns:
        true if the tag exist with this attribute name
        Throws:
        XMLDocumentException - If the targetted node does not exist or if xpath expression is not valid
      • hasAttribute

        boolean hasAttribute​(String name)
        Check wheter current tag contains an atribute
        Parameters:
        name - Attribute name
        Returns:
        true if the attribute is in current tag
      • forEachChild

        XMLTag forEachChild​(CallBack callBack)
        Execute an action for each child in the current node.
        Parameters:
        callBack - Callback method to run after the current tag of the document has changed to a child
        Returns:
        this
      • forEach

        XMLTag forEach​(CallBack callBack,
                       String relativeXpath,
                       Object... arguments)
        Execute an action for each selected tags from the current node.
        Parameters:
        callBack - Callback method to run after the current tag of the document has changed to a child
        relativeXpath - XXath expression that select the node
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        this
      • rawXpathString

        String rawXpathString​(String relativeXpath,
                              Object... arguments)
        Execute an XPath expression directly using the Java XPath API, from the current node.
        Parameters:
        relativeXpath - The XPath expression
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        The XPathConstants.STRING return type
      • rawXpathNumber

        Number rawXpathNumber​(String relativeXpath,
                              Object... arguments)
        Execute an XPath expression directly using the Java XPath API, from the current node.
        Parameters:
        relativeXpath - The XPath expression
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        The XPathConstants.NUMBER return type
      • rawXpathBoolean

        Boolean rawXpathBoolean​(String relativeXpath,
                                Object... arguments)
        Execute an XPath expression directly using the Java XPath API, from the current node.
        Parameters:
        relativeXpath - The XPath expression
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        The XPathConstants.BOOLEAN return type
      • rawXpathNode

        Node rawXpathNode​(String relativeXpath,
                          Object... arguments)
        Execute an XPath expression directly using the Java XPath API, from the current node.
        Parameters:
        relativeXpath - The XPath expression
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        The XPathConstants.NODE return type
      • rawXpathNodeSet

        NodeList rawXpathNodeSet​(String relativeXpath,
                                 Object... arguments)
        Execute an XPath expression directly using the Java XPath API, from the current node.
        Parameters:
        relativeXpath - The XPath expression
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        The XPathConstants.NODESET return type
      • getCurrentTag

        Element getCurrentTag()
        Returns:
        the current tag
      • getChildCount

        int getChildCount()
        Returns:
        The number of child for the current tag
      • getChilds

        Iterable<XMLTag> getChilds()
        
         XMLTag tag = XMLDoc.newDocument(true)
                 .addRoot("root").addTag("a")
                 .gotoParent().addTag("b")
                 .gotoParent().addTag("c")
                 .gotoRoot();
         assertEquals(tag.getCurrentTagName(), "root");
         for (XMLTag xmlTag : tag.getChilds()) {
             if(xmlTag.getCurrentTagName().equals("b")) {
                 break;
             }
         }
         assertEquals(tag.getCurrentTagName(), "b");

        
         XMLTag tag = XMLDoc.newDocument(true)
                 .addRoot("root").addTag("a")
                 .gotoParent().addTag("b")
                 .gotoParent().addTag("c")
                 .gotoRoot();
         assertEquals(tag.getCurrentTagName(), "root");
         for (XMLTag xmlTag : tag.getChilds()) {
             System.out.println(xmlTag.getCurrentTagName());
         }
         assertEquals(tag.getCurrentTagName(), "root");
        Returns:
        An iterable object over childs
      • getChilds

        Iterable<XMLTag> getChilds​(String relativeXpath,
                                   Object... arguments)
        Create an iterable object over selected elements. Act as the getChilds method: The current position of XMLTag is modified at each iteration. Thus, if you break in the iteration, the current position will not be the same as the position before.
        Parameters:
        relativeXpath - XPath to select tags
        arguments - XPath arguments
        Returns:
        The iterable object
      • getChildElement

        List<Element> getChildElement()
        Returns:
        The child element's list
      • getCurrentTagName

        String getCurrentTagName()
        Returns:
        the current tag name
      • getCurrentTagLocation

        String getCurrentTagLocation()
        Returns:
        An XPath expression representing the current tag location in the document. If you are in the root node and run gotoTag() giving this XPath expression, you will return to the current node.
      • getPefix

        String getPefix​(String namespaceURI)
        Get the prefix of a namespace
        Parameters:
        namespaceURI - The URI of the namespace
        Returns:
        the prefix or "" if not found ("" is the default prefix - see javadoc)
      • getPefixes

        String[] getPefixes​(String namespaceURI)
        Get all bound prefixes of a namespace
        Parameters:
        namespaceURI - The URI of the namespace
        Returns:
        a list of prefixes or an empty array.
      • getText

        String getText()
        Returns:
        The text content of the current node, "" if none
      • getText

        String getText​(String relativeXpath,
                       Object... arguments)
                throws XMLDocumentException
        Get the text of a sepcific node
        Parameters:
        relativeXpath - XPath expression that select the node
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        the text of "" if none
        Throws:
        XMLDocumentException - If the XPath expression is not valid or if the node does not exist
      • getCDATA

        String getCDATA()
        Returns:
        The CDATA content of the current node, "" if none
      • getCDATA

        String getCDATA​(String relativeXpath,
                        Object... arguments)
                 throws XMLDocumentException
        Get the CDATA of a selected node
        Parameters:
        relativeXpath - XPath expression that select the node
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        the text of "" if none
        Throws:
        XMLDocumentException - If the XPath expression is invalid or if the node does not exist
      • getTextOrCDATA

        String getTextOrCDATA()
        Returns:
        The text content of the current node, if none tries to get the CDATA content, if none returns ""
      • getTextOrCDATA

        String getTextOrCDATA​(String relativeXpath,
                              Object... arguments)
                       throws XMLDocumentException
        Get the text of a sepcific node
        Parameters:
        relativeXpath - XPath expression that select the node
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        The text content of the current node, if none tries to get the CDATA content, if none returns ""
        Throws:
        XMLDocumentException - If the XPath expression is not valid or if the node does not exist
      • getCDATAorText

        String getCDATAorText()
        Returns:
        The CDATA content of the current node, if none tries to get the text content, if none returns ""
      • getCDATAorText

        String getCDATAorText​(String relativeXpath,
                              Object... arguments)
                       throws XMLDocumentException
        Get the text of a sepcific node
        Parameters:
        relativeXpath - XPath expression that select the node
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        The CDATA content of the current node, if none tries to get the text content, if none returns ""
        Throws:
        XMLDocumentException - If the XPath expression is not valid or if the node does not exist
      • getAttributeNames

        String[] getAttributeNames()
        Returns:
        all attribute names of current node
      • getAttribute

        String getAttribute​(String name,
                            String relativeXpath,
                            Object... arguments)
                     throws XMLDocumentException
        Returns the attribute value of the node pointed by given XPath expression
        Parameters:
        name - attribute name
        relativeXpath - XPath expression
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        attribute value
        Throws:
        XMLDocumentException - Attribute does not exist, targetted node or XPath expression is invalid
      • findAttribute

        String findAttribute​(String name)
        returns the attribute value of the current node or null if the attribute does not exist
        Parameters:
        name - attribute name
        Returns:
        attribute value or null if no attribute
      • findAttribute

        String findAttribute​(String name,
                             String relativeXpath,
                             Object... arguments)
                      throws XMLDocumentException
        Returns the attribute value of the node pointed by given XPath expression or null if the attribute does not exist
        Parameters:
        name - attribute name
        relativeXpath - XPath expression
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        the attribute value or null if the attribute does not exist
        Throws:
        XMLDocumentException - targetted node does not exist or XPath expression is invalid
      • getInnerDocument

        XMLTag getInnerDocument()
        Returns:
        Another XMLTag instance in which the current tag becomes de root element of the new document, and it contains all inner elements as in the previous document.
      • getInnerText

        String getInnerText()
        Returns:
        The text representation of the inner nodes of the current node. The current node is outputed as the root element of inner tags.
      • duplicate

        XMLTag duplicate()
        Returns:
        A new com.mycila.xmltool.XMLTag instance having the same properties and documents of the current instance. The current tag will also remain the same (this.getCurrentTagName().equals(this.duplicate().getCurrentTagName()))
      • setText

        XMLTag setText​(String text)
        Set the text in the current node. This method will replace all existing text and cdata by the given text. Also Jump after to the parent node. This enables the quicly replace test on several nodes like this:

        gotoChild("name").setText("Bob").gotoChild("sex").setText("M").gotoChild("age").setText("30")

        <name>Bob</name><sex>M</sex><age>30</age>

        Parameters:
        text - text to put under this node
        Returns:
        this
      • setText

        XMLTag setText​(String text,
                       String relativeXpath,
                       Object... arguments)
                throws XMLDocumentException
        Set the text in the targetted node. This method will replace all existing text and cdata by the given text, but remains on the current tag.
        Parameters:
        text - text to put under this node
        relativeXpath - XPath expression that select the node
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        this
        Throws:
        XMLDocumentException - If the XPath expression is invalid or if the node does not exist
      • setTextIfExist

        XMLTag setTextIfExist​(String text,
                              String relativeXpath,
                              Object... arguments)
                       throws XMLDocumentException
        Set the text in the targetted node. This method will replace all existing text and cdata by the given text, but remains on the current tag. If the targetted node does not exist, do nothing.
        Parameters:
        text - text to put under this node
        relativeXpath - XPath expression that select the node
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        this
        Throws:
        XMLDocumentException - If the XPath expression is invalid
      • setCDATA

        XMLTag setCDATA​(String data)
        Set the cdata in the current node. This method will replace all existing text and cdata by the given cdata Also Jump after to the parent node. This enables the quicly replace test on several nodes like this:

        gotoChild("name").setText("Bob").gotoChild("sex").setText("M").gotoChild("age").setText("30")

        <name>Bob</name><sex>M</sex><age>30</age>

        Parameters:
        data - text to put under this node in a cdata section
        Returns:
        this
      • setCDATA

        XMLTag setCDATA​(String data,
                        String relativeXpath,
                        Object... arguments)
                 throws XMLDocumentException
        Set the cdata in the targetted node. This method will replace all existing text and cdata by the given cdata, but remains on the current tag.
        Parameters:
        data - text to put under this node in a cdata section
        relativeXpath - XPath expression that select the node
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        this
        Throws:
        XMLDocumentException - If the XPath expression is invalid or if the node does not exist
      • setCDATAIfExist

        XMLTag setCDATAIfExist​(String data,
                               String relativeXpath,
                               Object... arguments)
                        throws XMLDocumentException
        Set the cdata in the targetted node. This method will replace all existing text and cdata by the given cdata, but remains on the current tag. If the targetted node does not exist, do nothing.
        Parameters:
        data - text to put under this node in a cdata section
        relativeXpath - XPath expression that select the node
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        this
        Throws:
        XMLDocumentException - If the XPath expression is invalid
      • setAttribute

        XMLTag setAttribute​(String name,
                            String value)
                     throws XMLDocumentException
        Sets the new value on an existign attribute, and remains on the current tag.
        Parameters:
        name - attribute name
        value - new attribute'svalue
        Returns:
        attribute value
        Throws:
        XMLDocumentException - If the attribute does not exist
      • setAttributeIfExist

        XMLTag setAttributeIfExist​(String name,
                                   String value)
        Sets the new value on an attribute, and remains on the current tag. If it does not exist, do nothing.
        Parameters:
        name - attribute name
        value - new attribute value
        Returns:
        attribute value
      • setAttribute

        XMLTag setAttribute​(String name,
                            String value,
                            String relativeXpath,
                            Object... arguments)
                     throws XMLDocumentException
        Sets the new value on a targetted node's attribute, and remains on the current tag.
        Parameters:
        name - attribute name
        value - new attribute's value
        relativeXpath - XPath expression
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        attribute value
        Throws:
        XMLDocumentException - Attribute does not exist, targetted node does not exit, or XPath expression is invalid
      • setAttributeIfExist

        XMLTag setAttributeIfExist​(String name,
                                   String value,
                                   String relativeXpath,
                                   Object... arguments)
                            throws XMLDocumentException
        Sets the new value on a targetted node's attribute, and remains on the current tag. If the attribute does not exist, do nothing.
        Parameters:
        name - attribute name
        value - new attribute's value
        relativeXpath - XPath expression
        arguments - facultative Xpath expression arguments. Uses String.format() to build XPath expression.
        Returns:
        attribute value
        Throws:
        XMLDocumentException - XPath expression is invalid or targetted node does not exist
      • deleteChilds

        XMLTag deleteChilds()
        Delete all existing elements of this node
        Returns:
        this
      • delete

        XMLTag delete()
               throws XMLDocumentException
        Delete current tag and its childs. If the current tag is the root tag of xml document, it cannot be delete. It can just be replaced. In this case, an exception is thrown
        Returns:
        this
        Throws:
        XMLDocumentException - if the current node is the root node
      • deleteAttributes

        XMLTag deleteAttributes()
        Delete all existing attributes of current node
        Returns:
        this
      • deleteAttributeIfExists

        XMLTag deleteAttributeIfExists​(String name)
        Delete an attribute of the current node, if it exists
        Parameters:
        name - attribute name
        Returns:
        this
      • renameTo

        XMLTag renameTo​(String newTagName)
        Replace current element name by another name
        Parameters:
        newTagName - New name of the tag
        Returns:
        this
      • deletePrefixes

        XMLTag deletePrefixes()
        Remove any prefix and namespaces contained in the tag name, childs and attributes, thus changing namespace and tag name. This can be very useful if you are working in a document when you want to ignore namespaces, if you don't know the tag prefix
        Returns:
        this
      • toDocument

        Document toDocument()
        Returns:
        the Document
      • toSource

        Source toSource()
        Returns:
        This document as Source
      • toString

        String toString()
        Overrides:
        toString in class Object
        Returns:
        a string representation of the document in UTF-8 (Unicode)
      • toString

        String toString​(String encoding)
        Parameters:
        encoding - destination encoding of XML document
        Returns:
        a string representation of the document
      • toBytes

        byte[] toBytes()
        Returns:
        This document representation as String bytes, using default encoding of the document
      • toBytes

        byte[] toBytes​(String encoding)
        Parameters:
        encoding - The encoding to use
        Returns:
        This document representation as String bytes using sepcified ancoding
      • toResult

        XMLTag toResult​(Result out)
        Converts this document to the result provided
        Parameters:
        out - The output result
        Returns:
        this
      • toResult

        XMLTag toResult​(Result out,
                        String encoding)
        Converts this document to the result provided, overriding default encoding of xml document
        Parameters:
        out - The output result
        encoding - The new encoding
        Returns:
        this
      • toStream

        XMLTag toStream​(OutputStream out)
        Write this document to a stream
        Parameters:
        out - The output result
        Returns:
        this
      • toStream

        XMLTag toStream​(OutputStream out,
                        String encoding)
        Write this document to a stream
        Parameters:
        out - The output result
        encoding - The new encoding
        Returns:
        this
      • toStream

        XMLTag toStream​(Writer out)
        Write this document to a stream
        Parameters:
        out - The output result
        Returns:
        this
      • toStream

        XMLTag toStream​(Writer out,
                        String encoding)
        Write this document to a stream
        Parameters:
        out - The output result
        encoding - The new encoding
        Returns:
        this
      • toResult

        Result toResult()
        Returns:
        The Result representation of this document. Useful when using web services for example.
      • toResult

        Result toResult​(String encoding)
        Parameters:
        encoding - The new encoding
        Returns:
        The Result representation of this document. Useful when using web services for example.
      • toOutputStream

        OutputStream toOutputStream()
        Returns:
        A stream where the document has already been written into
      • toOutputStream

        OutputStream toOutputStream​(String encoding)
        Parameters:
        encoding - The new encoding
        Returns:
        A stream where the document has already been written into
      • toWriter

        Writer toWriter()
        Returns:
        A stream where the document has already been written into
      • toWriter

        Writer toWriter​(String encoding)
        Parameters:
        encoding - The new encoding
        Returns:
        A stream where the document has already been written into
      • validate

        ValidationResult validate​(Source... schemas)
        Validate this document against specifief schemas
        Parameters:
        schemas - A list of schemas
        Returns:
        A validation result object containing exception list occured if any
      • validate

        ValidationResult validate​(URL... schemaLocations)
        Validate this document against specifief schemas
        Parameters:
        schemaLocations - A list of schemas
        Returns:
        A validation result object containing exception list occured if any