/**
 * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
 */

package net.sourceforge.pmd.lang.rule.xpath;

import java.util.List;
import java.util.Map;

import net.sourceforge.pmd.PropertyDescriptor;
import net.sourceforge.pmd.RuleContext;
import net.sourceforge.pmd.lang.ast.Node;

/**
 * This interface captures the logic needed by XPathRule to implement an XPath
 * based query on an AST Node.
 * <p>
 * Implementations of this class do not need to be thread-safe, but they will be
 * reused to query against different AST Nodes. Therefore, internal state should
 * be maintained in a fashion consistent with reuse. Further, implementations
 * are recommended to manage internal state that is invariant over AST Nodes in
 * a fashion which facilities high performance (e.g. caching).
 */
public interface XPathRuleQuery {

    /**
     * XPath 1.0 version.
     */
    String XPATH_1_0 = "1.0";

    /**
     * XPath 1.0 compatibility version.
     */
    String XPATH_1_0_COMPATIBILITY = "1.0 compatibility";

    /**
     * XPath 2.0 version.
     */
    String XPATH_2_0 = "2.0";

    /**
     * Set the XPath query string to be used.
     *
     * @param xpath
     *            The XPath query string.
     */
    void setXPath(String xpath);

    /**
     * Set the XPath version to be used.
     *
     * @param version
     *            The XPath version.
     * @throws UnsupportedOperationException
     *             if the version cannot be handled.
     */
    void setVersion(String version) throws UnsupportedOperationException;

    /**
     * Set the properties to use during the XPath query.
     */
    void setProperties(Map<PropertyDescriptor<?>, Object> properties);

    /**
     * Indicates which AST Nodes (if any) should be used with the RuleChain. Use
     * of the RuleChain will allow the query execute on a targed sub-tree of the
     * AST, instead of the entire AST from the root. This can result in great
     * performance benefits.
     */
    List<String> getRuleChainVisits();

    /**
     * Evaluate the XPath query against the given Node.
     *
     * @param node
     *            The Node.
     * @param data
     *            The RuleContext.
     * @return The matching Nodes.
     */
    List<Node> evaluate(Node node, RuleContext data);
}