1 package org.tinyjee.maven.dim.utils;
2
3 import org.w3c.dom.Node;
4 import org.w3c.dom.NodeList;
5
6 import java.util.List;
7
8 /**
9 * Defines a simple data access interface that may be used to evaluate XPath expressions
10 * against the loaded XML document.
11 */
12 public interface XPathEvaluator {
13 /**
14 * Searches the loaded document for the text content of the first node matched by the given XPath expression.
15 *
16 * @param xpathExpression The xpath expression used to select the text content. E.g. <code>"/html/head/title"</code>
17 * @return The first matched text content or 'null' if not found.
18 */
19 String findText(String xpathExpression);
20
21 /**
22 * Finds all DOM nodes that match the given XPath expression.
23 *
24 * @param xpathExpression The xpath expression used to select nodes, E.g. <code>//table</code>
25 * @return A list of all matched DOM nodes. If no nodes were matched, an empty list is returned instead.
26 */
27 List<Node> findNodes(String xpathExpression);
28
29 /**
30 * Serializes the given DOM node to XML.
31 *
32 * @param node the node to serialize.
33 * @return the XML string representing the serialized node.
34 */
35 String serialize(Node node);
36
37 /**
38 * Converts the given {@link NodeList} to a java list of {@link Node} instances.
39 *
40 * @param nodeList the node list to convert.
41 * @return a node list that uses the standard java collection framework.
42 */
43 List<Node> asList(NodeList nodeList);
44
45 /**
46 * Creates a new dependent evaluator that resolves nodes relative to the given node.
47 * <p/>
48 * The evaluator returned by this method shares internals like namespace resolution and xpath engine and
49 * may not be used concurrently (in multiple threads) with its creator.
50 *
51 * @param node the node to resolve against.
52 * @return a new evaluator that resolves nodes relative to the given node.
53 */
54 XPathEvaluator newEvaluator(Node node);
55 }