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.

  • Method Details

    • 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() throws XMLDocumentException
      Go to the only child element of the curent node.
      Returns:
      this
      Throws:
      XMLDocumentException - If the current node has several childs or no child at all
    • 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() throws XMLDocumentException
      Go to the first child element of the curent node.
      Returns:
      this
      Throws:
      XMLDocumentException - If the current node has no child at all
    • 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() throws XMLDocumentException
      Go to the lastest child element of the curent node.
      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
    • forEach

      XMLTag forEach(String xpath, CallBack callBack)
    • 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.
    • getContext

      NamespaceContext getContext()
      Returns:
      the namespace context
    • 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) throws XMLDocumentException
      returns the attribute value of the current node
      Parameters:
      name - attribute name
      Returns:
      attribute value
      Throws:
      XMLDocumentException - If the attribute does not exist
    • 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
    • deleteAttribute

      XMLTag deleteAttribute(String name) throws XMLDocumentException
      Delete an attribute of the current node.
      Parameters:
      name - attribute name
      Returns:
      this
      Throws:
      XMLDocumentException - if the attribute does not exist
    • 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