Package com.puppycrawl.tools.checkstyle.xpath

Class XpathQueryGenerator

java.lang.Object
com.puppycrawl.tools.checkstyle.xpath.XpathQueryGenerator
public class XpathQueryGenerator extends 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 Details

    • rootAst

      private final DetailAST rootAst
      The root ast.

    • 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 Details

    • 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 Details

    • generate

      public List<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

      @Nullable 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

      @Nullable 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 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 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 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 String encode(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:
      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 String encodeCharacter(char chr)
      Encodes escape character for Xpath. Escape characters need '&' before, but it also requires XML 1.1 until #5168.
      Parameters:
      chr - Character to check.
      Returns:
      String, Encoded string.