Package com.avoka.component.xml

Class XmlDoc

  • public class XmlDoc
extends Object
    Provides a XML Document class for use in Groovy scripts. An XmlDoc object wraps an underlying object and provides convenience methods for performing access and modification operations.

    XML Read Example

    This Groovy example creates an XmlDoc from a delivery submissionXml string value, and then reads out a values and puts them in a map. 

     import com.avoka.component.xml.XmlDoc

 def xmlDoc = new XmlDoc(submissionXml)

 def contact = [:]
 contact.firstName = xmlDoc.getText('//YourDetails/FirstName')
 contact.lastName = xmlDoc.getText('//YourDetails/LastName')
 contact.email = xmlDoc.getText('//YourDetails/Email')
 contact.state = xmlDoc.getText('//Location/State')
    Note you have the full power of XQuery so you can perform XQuerys like: 
     def countryList = addressXmlDoc.list("//root/country[@value='USA']");

    Please see the W3C Schools XPath Syntax for more examples.

    XML Write Example

    This Groovy example writes form prefill data into a schemaSeed XML Document. 

     import com.avoka.component.xml.XmlDoc

 def xmlDoc = new XmlDoc(schemaSeed)

 def userDetails = ...

 xmlDoc.setText('/AvokaSmartForm/YourDetails/FirstName', userDetails.firstName)
 xmlDoc.setText('/AvokaSmartForm/YourDetails/LastName', userDetails.lastName)
 xmlDoc.setText('/AvokaSmartForm/YourDetails/Email', userDetails.email)

    You can also add Nodes or a list of Nodes to an XML Document using the addNode(String, Node) or addNodeList(String, List) methods. See the Composer Cascading DD List Example later to see this in action.

    Adding XML Content as Text

    When creating large amounts of XML it is often easer to use string templating techniques to create the XML content and then add this to the target XML document.

    The example below is using the addContent(String, String, String) method to add the '/ItemList/Item' elements from the source prefillDataContext XML text to the xmlDoc object under the node '/AvokaSmartForm/Accounts'. 

     import com.avoka.component.xml.XmlDoc

 // Text prefill XML content
 def prefillDataContent = '<ItemList> <Item>A1</Item> <Item>B2</Item> </ItemList>'

 // Target document to add prefill content to
 def xmlDoc = new XmlDoc(schemaSeed)
 xmlDoc.addContent(prefillDataContent, '/ItemList/Item', '/AvokaSmartForm/Accounts')

    If you need to replace existing content in an XML Document rather than adding to it, then use the removeNodes(String) method first before adding the content. For example: 

     import com.avoka.component.xml.XmlDoc

 def prefillDataContent = '<ItemList> <Item>A1</Item> <Item>B2</Item> </ItemList>'

 def xmlDoc = new XmlDoc(schemaSeed)

 // Remove any existing data
 xmlDoc.removeNodes('/AvokaSmartForm/Accounts')

 xmlDoc.addContent(prefillDataContent, '/ItemList/Item', '/AvokaSmartForm/Accounts')

    Composer DD List Example

    This Groovy example writes creates a Composer Drop Down (DD) list value and writes a schemaSeed XML Document for form prefill. 

     import com.avoka.component.xml.XmlDoc
 import com.avoka.component.xml.DropDownListUtils

 def shiftDoc = new XmlDoc(shiftXml)
 def shiftList = DropDownListUtils.createDDListString(xmlDoc, "//shift", "shift_id", "shift_name")

 def xmlDoc = new XmlDoc(schemaSeed)
 xmlDoc.setText('/AvokaSmartForm/Timesheet/ShiftOptions', shiftList)

    Composer Cascading DD List Example

    This Groovy example writes creates a Composer Cascading Drop Down (DD) List value and writes a schemaSeed XML Document for form prefill. 

     import com.avoka.component.xml.XmlDoc
 import com.avoka.component.xml.DropDownListUtils

 def addressCSV = ..
 def addressXmlDoc = DropDownListUtils.createCascadingDropdownXml(addressesCSV)
 def countryList = addressXmlDoc.getNodeList("//root/country[@value='United States of America']")

 def xmlDoc = new XmlDoc(schemaSeed)
 xmlDoc.addNodeList("/AvokaSmartForm/country-list", countyList)

    XQuery Data Transformation Example

    This Groovy example converts an XML address list into an alternative XML representation using an XQuery transform. 

     import com.avoka.component.xml.XmlDoc

 def addressXmlDoc = new XmlDoc(sourceData)

 def xquery = ..
 def cities = addressXmlDoc.performXQueryTransform(xquery)

    See http://en.wikibooks.org/wiki/XQuery for information on how to use XQuery.

    Since:
    3.5.0

    • Constructor Detail

      • XmlDoc

        public XmlDoc​(Document source)
        Create an XmlDoc object from the given XML document.
        Parameters:
        source - the source XML document

      • XmlDoc

        public XmlDoc​(String source)
        Create an XmlDoc object from the given XML document text.
        Parameters:
        source - the source XML document text

      • XmlDoc

        public XmlDoc​(byte[] source)
        Create an XmlDoc object from the given XML document text (UTF-8).
        Parameters:
        source - the source XML document text (UTF-8)

    • Method Detail

      • addContent

        public Node addContent​(String sourceContent,
                       String sourceXPath,
                       String targetXPath)
        Add the given XML content from the source XPath to this XML Document object at the specified target XPath.
        Parameters:
        sourceContent - the source XML content to add to the XML Document
        sourceXPath - the XPath to the node within the source XML content to add
        targetXPath - the XPath to add the content to in this XML Document
        Returns:
        the Node of the target XPath
        Since:
        3.6.4

      • addNode

        public Node addNode​(String xpath,
                    Node node)

        Add the given Node to the XML Document object at to specified XPath. If the XPath nodes do not exist in the document they will be created. This method will return a deep cloned copy of the given Node which was added to the XML Document at the specified path.

        XPath expressions must use an absolute path to avoid ambiguity when creating XML path elements, using // search criteria is not permitted.

        Parameters:
        xpath - the XPath location of where to add the node
        node - the Node to add to the XML Document
        Returns:
        the cloned node added to the XML Document at the specified XPath.

      • addNodeList

        public void addNodeList​(String xpath,
                        List<Node> nodeList)
        Add the given Node list to the XML Document object at to specified XPath. If the XPath nodes do not exist in the document they will be created. This method will return a deep cloned copy of the given list of Node which was added to the XML Document at the specified path. XPath expressions must use an absolute path to avoid ambiguity when creating XML path elements, using // search criteria is not permitted.
        Parameters:
        xpath - the XPath location of where to add the nodes
        nodeList - the list of Nodes to add to the XML Document

      • getDocument

        public Document getDocument()
        Return the underlying XML Document object.
        Returns:
        the underlying XML Document object.

      • getNode

        public Node getNode​(String xpath)
        Return the XML node for the given XPath.
        Parameters:
        xpath - the XPath expression of the node
        Returns:
        the node for the given xpath

      • getNodeList

        public List<Node> getNodeList​(String xpath)
        Return the list of XML Nodes for the given XPath expression.
        Parameters:
        xpath - the XPath expression
        Returns:
        the list of XML Nodes for the given XPath expression

      • getText

        public String getText​(String xpath)
        Return the text value for the given XPath or null if not found. 
         def xmlDoc = new com.avoka.component.xml.XmlDoc(submissionXml)

 def contact = [:]
 contact.firstName = xmlDoc.getText('//YourDetails/FirstName')
 contact.lastName = xmlDoc.getText('//YourDetails/LastName')
 contact.email = xmlDoc.getText('//YourDetails/Email')
 contact.state = xmlDoc.getText('//Location/State')
        Parameters:
        xpath - the XPath to search
        Returns:
        the text value for the given XPath or null if not found

      • setNode

        public Node setNode​(String xpath)

        Create the XML elements specified by the XPath expression if they don't exist, and return the leaf node.

        XPath expressions must use an absolute path to avoid ambiguity when creating XML path elements, using // search criteria is not permitted. 

         def line1 = xmlDoc.set('/AvokaSmartForm/YourDetails/Address/Line1")
        Parameters:
        xpath - the XML elements to create
        Returns:
        the node specified by the XPath if found or the created XML node

      • setText

        public Node setText​(String xpath,
                    String textContent)

        Set the content text on the XML element specified by the XPath expression. This method will create the elements specified by the path if they don't exist.

        XPath expressions must use an absolute path to avoid ambiguity when creating XML path elements, using // search criteria is not permitted. 

         xmlDoc.setText('/AvokaSmartForm/YourDetails/Address/Line1", "30 George Street")

        Example

         def xmlDoc = new com.avoka.component.xml.XmlDoc(schemaSeed)

 def userDetails = ...

 xmlDoc.setText('/AvokaSmartForm/YourDetails/FirstName', userDetails.firstName)
 xmlDoc.setText('/AvokaSmartForm/YourDetails/LastName', userDetails.lastName)
 xmlDoc.setText('/AvokaSmartForm/YourDetails/Email', userDetails.email)
        Parameters:
        xpath - the XML element to set the text on, this path will be created if it does not exist
        textContent - the element content text value to set
        Returns:
        the node specified by the XPath if found or the created XML node

      • evalXPath

        public String evalXPath​(String xpath)
        Evaluate the XPath expression and return the given string value.

        Example

         def xmlDoc = new XmlDoc(schemaSeed)

 def fullname = xmlDoc.evalXPath("concat(//FirstName, ' ',//LastName)")
        Parameters:
        xpath - the XPath expression (required)
        Returns:
        the evaluated XPath expression as a string value
        Since:
        4.0.0

      • performXQueryTransform

        public String performXQueryTransform​(String xquery)

        Perform an XQuery transform against this XmlDoc and return the resulting text. This method uses the Saxon XQuery processor.

        See http://en.wikibooks.org/wiki/XQuery for information on how to use XQuery.

        Parameters:
        xquery - the XQuery transform to perform against this XmlDoc
        Returns:
        the resulting XQuery transform against this XmlDoc

      • removeNodes

        public boolean removeNodes​(String xpath)
        Remove the nodes from the XML Document object specified by the XPath.
        Parameters:
        xpath - the XPath of the nodes to remove
        Returns:
        true if a one or more nodes were removed from the XML Document object
        Since:
        3.6.4

      • removeNodeChildren

        public boolean removeNodeChildren​(String xpath)
        Remove the child nodes from the XML Document element specified by the XPath.
        Parameters:
        xpath - the XPath of the parent node whose children should be removed (required)
        Returns:
        true if a one or more nodes were removed from the XML Document object
        Since:
        4.1.5

      • getDataMap

        public Map<String,​String> getDataMap​(String jsonMap)

        Return a map of XML data element values from the document using the given jsonMap definition.

        Example JSON mapping format: 

         {
    "firstName": "//SmartForm/FormData/Contact/FirstName",
    "lastName": "//SmartForm/FormData/Contact/LastName",
    "email": "//SmartForm/FormData/Contact/Email"
 }
 
        
 This method provides a convenience wrapper around XmlUtils.getXmlDataMap(Document, String).
        Parameters:
        jsonMap - the JSON format name to XPath mapping definition (required)
        Returns:
        a map of XML data element values from the given document using the jsonMap definition
        Since:
        4.0.0

      • toFormattedString

        public String toFormattedString()
        Return the formatted string representation of the Document.
        Returns:
        the formatted string representation of the Document

      • toString

        public String toString()
        Return the string representation of the Document.
        Overrides:
        toString in class Object
        Returns:
        the string representation of the Document