Package com.puppycrawl.tools.checkstyle.xpath

Class XpathQueryGenerator

  • public class XpathQueryGenerator
extends java.lang.Object
    Generates xpath queries. Xpath queries are generated based on received DetailAst element, line number, column number and token type. Token type parameter is optional.

    Example class 

     public class Main {

     public String sayHello(String name) {
         return "Hello, " + name;
     }
 }

    Following expression returns list of queries. Each query is the string representing full path to the node inside Xpath tree, whose line number is 3 and column number is 4. 

         new XpathQueryGenerator(rootAst, 3, 4).generate();

    Result list

    • /COMPILATION_UNIT/CLASS_DEF[./IDENT[@text='Main']]/OBJBLOCK/METHOD_DEF[./IDENT[@text='sayHello']]
    • /COMPILATION_UNIT/CLASS_DEF[./IDENT[@text='Main']]/OBJBLOCK/METHOD_DEF[./IDENT[@text='sayHello']] /MODIFIERS
    • /COMPILATION_UNIT/CLASS_DEF[./IDENT[@text='Main']]/OBJBLOCK/METHOD_DEF[./IDENT[@text='sayHello']] /MODIFIERS/LITERAL_PUBLIC

    • Field Detail

      • lineNumber

        private final int lineNumber
        The line number of the element for which the query should be generated.

      • columnNumber

        private final int columnNumber
        The column number of the element for which the query should be generated.

      • tokenType

        private final int tokenType
        The token type of the element for which the query should be generated. Optional.

      • fileText

        private final FileText fileText
        The FileText object, representing content of the file.

      • tabWidth

        private final int tabWidth
        The distance between tab stop position.

    • Constructor Detail

      • XpathQueryGenerator

        public XpathQueryGenerator​(TreeWalkerAuditEvent event,
                           int tabWidth)
        Creates a new XpathQueryGenerator instance.
        Parameters:
        event - TreeWalkerAuditEvent object
        tabWidth - distance between tab stop position

      • XpathQueryGenerator

        public XpathQueryGenerator​(DetailAST rootAst,
                           int lineNumber,
                           int columnNumber,
                           FileText fileText,
                           int tabWidth)
        Creates a new XpathQueryGenerator instance.
        Parameters:
        rootAst - root ast
        lineNumber - line number of the element for which the query should be generated
        columnNumber - column number of the element for which the query should be generated
        fileText - the FileText object
        tabWidth - distance between tab stop position

      • XpathQueryGenerator

        public XpathQueryGenerator​(DetailAST rootAst,
                           int lineNumber,
                           int columnNumber,
                           int tokenType,
                           FileText fileText,
                           int tabWidth)
        Creates a new XpathQueryGenerator instance.
        Parameters:
        rootAst - root ast
        lineNumber - line number of the element for which the query should be generated
        columnNumber - column number of the element for which the query should be generated
        tokenType - token type of the element for which the query should be generated
        fileText - the FileText object
        tabWidth - distance between tab stop position

    • Method Detail

      • generate

        public java.util.List<java.lang.String> generate()
        Returns list of xpath queries of nodes, matching line number, column number and token type. This approach uses DetailAST traversal. DetailAST means detail abstract syntax tree.
        Returns:
        list of xpath queries of nodes, matching line number, column number and token type

      • findChildWithTextAttribute

        private static DetailAST findChildWithTextAttribute​(DetailAST root)
        Returns child DetailAst element of the given root, which has text attribute.
        Parameters:
        root - DetailAST root ast
        Returns:
        child DetailAst element of the given root

      • findChildWithTextAttributeRecursively

        private static DetailAST findChildWithTextAttributeRecursively​(DetailAST root)
        Returns child DetailAst element of the given root, which has text attribute. Performs search recursively inside node's subtree.
        Parameters:
        root - DetailAST root ast
        Returns:
        child DetailAst element of the given root

      • generateXpathQuery

        public static java.lang.String generateXpathQuery​(DetailAST ast)
        Returns full xpath query for given ast element.
        Parameters:
        ast - DetailAST ast element
        Returns:
        full xpath query for given ast element

      • findPositionAmongSiblings

        private static int findPositionAmongSiblings​(DetailAST ast)
        Finds position of the ast element among siblings.
        Parameters:
        ast - DetailAST ast element
        Returns:
        position of the ast element

      • isXpathQueryForNodeIsAccurateEnough

        private static boolean isXpathQueryForNodeIsAccurateEnough​(DetailAST ast)
        Checks if ast element has all requirements to have unique xpath query.
        Parameters:
        ast - DetailAST ast element
        Returns:
        true if ast element will have unique xpath query, false otherwise

      • getMatchingAstElements

        private java.util.List<DetailAST> getMatchingAstElements()
        Returns list of nodes matching defined line number, column number and token type.
        Returns:
        list of nodes matching defined line number, column number and token type

      • getXpathQuery

        private static java.lang.String getXpathQuery​(DetailAST root,
                                              DetailAST ast)
        Returns relative xpath query for given ast element from root.
        Parameters:
        root - DetailAST root element
        ast - DetailAST ast element
        Returns:
        relative xpath query for given ast element from root

      • hasAtLeastOneSiblingWithSameTokenType

        private static boolean hasAtLeastOneSiblingWithSameTokenType​(DetailAST ast)
        Checks if the given ast element has unique TokenTypes among siblings.
        Parameters:
        ast - DetailAST ast element
        Returns:
        if the given ast element has unique TokenTypes among siblings

      • expandedTabColumn

        private int expandedTabColumn​(DetailAST ast)
        Returns the column number with tabs expanded.
        Parameters:
        ast - DetailAST root ast
        Returns:
        the column number with tabs expanded

      • isMatchingByLineAndColumnAndTokenType

        private boolean isMatchingByLineAndColumnAndTokenType​(DetailAST ast)
        Checks if the given DetailAST node is matching line number, column number and token type.
        Parameters:
        ast - DetailAST ast element
        Returns:
        true if the given DetailAST node is matching

      • encode

        private static java.lang.String encode​(java.lang.String value)
        Escape <, >, &, ' and " as their entities. Custom method for Xpath generation to maintain compatibility with Saxon and encoding outside Ascii range characters.

        According to Saxon documentation in http://saxon.sourceforge.net/saxon7.1/expressions.html From Saxon 7.1, string delimiters can be doubled within the string to represent the delimiter itself: for example select='"He said, ""Go!"""'.

        Guava cannot as Guava encoding does not meet our requirements like double encoding for apos, removed slashes which are basic requirements for Saxon to decode.

        Parameters:
        value - the value to escape.
        Returns:
        the escaped value if necessary.

      • encodeCharacter

        private static java.lang.String encodeCharacter​(char chr)
        Encodes escape character for Xpath. Escape characters need '&' before but it also requires XML 1.1 until https://github.com/checkstyle/checkstyle/issues/5168.
        Parameters:
        chr - Character to check.
        Returns:
        String, Encoded string.