com.adobe.fd.workflow.api

Class XPathUtils

java.lang.Object

com.adobe.fd.workflow.api.XPathUtils

@Service
public class XPathUtils
extends Object

Utility class which allows retrieval of values from XML documents using XPath queries, as well as updation of values inside an XML document.

Constructor Summary

Constructors

Constructor and Description
XPathUtils()

Method Summary

Modifier and Type	Method and Description
Map<String,Object>	query(Document xmlDoc, Map<String,QName> queries) Queries the given XML document using the supplied XPath queries, and returns the results.
Object	query(Document xmlDoc, String xpathQuery, QName type) Utility query method for a single XPath query.
Map<String,Object>	query(String xmlJcrPath, org.apache.sling.api.resource.ResourceResolver rr, Map<String,QName> queries) Utility query method for the scenario where the XML document is a node in the repository.
Object	query(String xmlJcrPath, org.apache.sling.api.resource.ResourceResolver rr, String xpathQuery, QName type) Utility query method for executing a single XPath query against an XML document stored in the repository.
Document	update(Document xmlDoc, Map<String,String> values) Updates the nodes or attributes at the given paths inside the given XML document with the supplied values, and returns a new XML document containing the modified values.
Document	update(Document xmlDoc, String xpathQuery, String value) Utility update method for the use-case where only one value needs to be updated.
void	update(String xmlJcrPath, org.apache.sling.api.resource.ResourceResolver rr, Map<String,String> values, boolean save) Utility update method for the use-case where the XML to be updated is stored as a node in the repository.
void	update(String xmlJcrPath, org.apache.sling.api.resource.ResourceResolver rr, String xpathQuery, String value, boolean save) Utility method for the use-case where a single value needs to be updated in an XML document stored in the repository.

Constructor Detail

XPathUtils

public XPathUtils()

Method Detail

query

public Map<String,Object> query(Document xmlDoc,
                                Map<String,QName> queries)
                         throws ParserConfigurationException,
                                IOException,
                                SAXException,
                                XPathException

Queries the given XML document using the supplied XPath queries, and returns the results.

Parameters:

xmlDoc - An XML document

queries - A map of XPath queries to the expected return types for the queries. The return types should be drawn from the types defined in javax.xml.xpath.XPathConstants. The return type can also be null, in which case the string representation of the element(s) at the specified XPath expression will be returned.

Returns:

A map of XPath queries to the values retrieved by executing the queries against the given XML.

Throws:

ParserConfigurationException - If an XML parser configuration error is detected.

IOException - If an error occurs while reading the given XML document.

SAXException - If an error occurs while parsing the given XML document.

XPathException - If an error occurs while executing the given XPath queries.

query

public Object query(Document xmlDoc,
                    String xpathQuery,
                    QName type)
             throws ParserConfigurationException,
                    IOException,
                    SAXException,
                    XPathException

Utility query method for a single XPath query.

Parameters:

xmlDoc - An XML document.

xpathQuery - An XPath query to be executed on the given XML.

type - The expected return type for the value retrieved by executing the given query.

Returns:

The result of executing the given query on the given XML.

Throws:

ParserConfigurationException - If an XML parser configuration error is detected.

IOException - If an error occurs while reading the given XML document.

SAXException - If an error occurs while parsing the given XML document.

XPathException - If an error occurs while executing the given XPath queries.

See Also:

query(com.adobe.aemfd.docmanager.Document, java.util.Map)

query

public Map<String,Object> query(String xmlJcrPath,
                                org.apache.sling.api.resource.ResourceResolver rr,
                                Map<String,QName> queries)
                         throws ParserConfigurationException,
                                IOException,
                                SAXException,
                                XPathException

Utility query method for the scenario where the XML document is a node in the repository.

Parameters:

xmlJcrPath - The repository path of an XML document.

rr - The resource-resolver to be used for reading the given XML path. This resolver must have read access for the given path.

queries - A map of XPath queries to expected return types.

Returns:

A map of XPath queries to the values retrieved by executing the queries against the given XML.

Throws:

ParserConfigurationException - If an XML parser configuration error is detected.

IOException - If an error occurs while reading the given XML document.

SAXException - If an error occurs while parsing the given XML document.

XPathException - If an error occurs while executing the given XPath queries.

See Also:

query(com.adobe.aemfd.docmanager.Document, java.util.Map)

query

public Object query(String xmlJcrPath,
                    org.apache.sling.api.resource.ResourceResolver rr,
                    String xpathQuery,
                    QName type)
             throws ParserConfigurationException,
                    IOException,
                    SAXException,
                    XPathException

Utility query method for executing a single XPath query against an XML document stored in the repository.

Parameters:

xmlJcrPath - The repository path of an XML document.

rr - The resource-resolver to be used for reading the given XML path.

xpathQuery - An XPath query to be executed on the given XML.

type - The expected return type for the value retrieved by executing the given query.

Returns:

The result of executing the given query on the given XML.

Throws:

ParserConfigurationException - If an XML parser configuration error is detected.

IOException - If an error occurs while reading the given XML document.

SAXException - If an error occurs while parsing the given XML document.

XPathException - If an error occurs while executing the given XPath queries.

See Also:

query(String, org.apache.sling.api.resource.ResourceResolver, java.util.Map)

update

public Document update(Document xmlDoc,
                       Map<String,String> values)
                throws ParserConfigurationException,
                       IOException,
                       SAXException,
                       XPathException,
                       TransformerException

Updates the nodes or attributes at the given paths inside the given XML document with the supplied values, and returns a new XML document containing the modified values.

Parameters:

xmlDoc - An XML document.

values - A map of XML node/attribute paths to the new values to be set at these paths. The paths are represented using XPath expressions, and each path must resolve to a single existing node inside the given XML (or a single attribute of such a node). If a node is being updated, then it is typically expected to be a leaf node with some text content and no child nodes.

Returns:

A new XML document representing the given XML updated with the given values.

Throws:

ParserConfigurationException - If an XML parser configuration error is detected.

IOException - If an error occurs while reading the given XML document.

SAXException - If an error occurs while parsing the given XML document.

XPathException - If an error occurs while executing the given XPath expressions.

TransformerException - If an unexpected error occurs while constructing the updated XML document.

update

public Document update(Document xmlDoc,
                       String xpathQuery,
                       String value)
                throws ParserConfigurationException,
                       IOException,
                       SAXException,
                       XPathException,
                       TransformerException

Utility update method for the use-case where only one value needs to be updated.

Parameters:

xmlDoc - An XML document.

xpathQuery - The node/attribute path to be updated.

value - The new value to be set at the given path.

Returns:

A new XML document representing the given XML updated with the given value.

Throws:

ParserConfigurationException - If an XML parser configuration error is detected.

IOException - If an error occurs while reading the given XML document.

SAXException - If an error occurs while parsing the given XML document.

XPathException - If an error occurs while executing the given XPath expressions.

TransformerException - If an unexpected error occurs while constructing the updated XML document.

See Also:

update(com.adobe.aemfd.docmanager.Document, java.util.Map)

update

public void update(String xmlJcrPath,
                   org.apache.sling.api.resource.ResourceResolver rr,
                   Map<String,String> values,
                   boolean save)
            throws ParserConfigurationException,
                   IOException,
                   SAXException,
                   XPathException,
                   TransformerException,
                   javax.jcr.RepositoryException

Utility update method for the use-case where the XML to be updated is stored as a node in the repository. This method updates the XML in place.

Parameters:

xmlJcrPath - The repository path of an XML document to be updated.

rr - The resource-resolver to be used for reading and updating the document. This resolver must have both read and write access to the given path.

values - A map of paths to the new values to be set at these paths.

save - Whether the updates to the XML should be committed immediately or not. This should be set to false for scenarios where the resource-resolver is a managed one (e.g. one adapted from the workflow session provided by the workflow engine).

Throws:

ParserConfigurationException - If an XML parser configuration error is detected.

IOException - If an error occurs while reading the given XML document.

SAXException - If an error occurs while parsing the given XML document.

XPathException - If an error occurs while executing the given XPath expressions.

TransformerException - If an unexpected error occurs while constructing the updated XML document.

javax.jcr.RepositoryException - If a repository error occurs while reading or updating the given XML.

See Also:

update(com.adobe.aemfd.docmanager.Document, java.util.Map)

update

public void update(String xmlJcrPath,
                   org.apache.sling.api.resource.ResourceResolver rr,
                   String xpathQuery,
                   String value,
                   boolean save)
            throws ParserConfigurationException,
                   IOException,
                   SAXException,
                   XPathException,
                   TransformerException,
                   javax.jcr.RepositoryException

Utility method for the use-case where a single value needs to be updated in an XML document stored in the repository.

Parameters:

xmlJcrPath - The repository path of an XML document.

rr - The resource resolver to be used for reading and updating the XML.

xpathQuery - The node/attribute path to be updated.

value - The new value to be set at the given path.

save - Whether the updates should be committed immediately.

Throws:

ParserConfigurationException - If an XML parser configuration error is detected.

IOException - If an error occurs while reading the given XML document.

SAXException - If an error occurs while parsing the given XML document.

XPathException - If an error occurs while executing the given XPath expression.

TransformerException - If an unexpected error occurs while constructing the updated XML document.

javax.jcr.RepositoryException - If a repository error occurs while reading or updating the given XML.

See Also:

update(String, org.apache.sling.api.resource.ResourceResolver, java.util.Map, boolean)