View Javadoc

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  }