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  }