1 /**
2 * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
3 */
4 package net.sourceforge.pmd.lang.rule.xpath;
5
6 import java.util.List;
7 import java.util.Map;
8
9 import net.sourceforge.pmd.PropertyDescriptor;
10 import net.sourceforge.pmd.RuleContext;
11 import net.sourceforge.pmd.lang.ast.Node;
12
13 /**
14 * This interface captures the logic needed by XPathRule to implement an
15 * XPath based query on an AST Node.
16 * <p>
17 * Implementations of this class do not need to be thread-safe, but they will
18 * be reused to query against different AST Nodes. Therefore, internal state
19 * should be maintained in a fashion consistent with reuse. Further,
20 * implementations are recommended to manage internal state that is invariant
21 * over AST Nodes in a fashion which facilities high performance (e.g. caching).
22 */
23 public interface XPathRuleQuery {
24
25 /**
26 * XPath 1.0 version.
27 */
28 String XPATH_1_0 = "1.0";
29
30 /**
31 * XPath 1.0 compatibility version.
32 */
33 String XPATH_1_0_COMPATIBILITY = "1.0 compatibility";
34
35 /**
36 * XPath 2.0 version.
37 */
38 String XPATH_2_0 = "2.0";
39
40 /**
41 * Set the XPath query string to be used.
42 * @param xpath The XPath query string.
43 */
44 void setXPath(String xpath);
45
46 /**
47 * Set the XPath version to be used.
48 * @param version The XPath version.
49 * @throws UnsupportedOperationException if the version cannot be handled.
50 */
51 void setVersion(String version) throws UnsupportedOperationException;
52
53 /**
54 * Set the properties to use during the XPath query.
55 */
56 void setProperties(Map<PropertyDescriptor<?>, Object> properties);
57
58 /**
59 * Indicates which AST Nodes (if any) should be used with the RuleChain.
60 * Use of the RuleChain will allow the query execute on a targed sub-tree
61 * of the AST, instead of the entire AST from the root. This can result
62 * in great performance benefits.
63 */
64 List<String> getRuleChainVisits();
65
66 /**
67 * Evaluate the XPath query against the given Node.
68 * @param node The Node.
69 * @param data The RuleContext.
70 * @return The matching Nodes.
71 */
72 List<Node> evaluate(Node node, RuleContext data);
73 }