XpathQueryGenerator (checkstyle 9.3 API)

java.lang.Object
- com.puppycrawl.tools.checkstyle.xpath.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 Summary

Fields
Modifier and Type	Field and Description
`private int`	`columnNumber` The column number of the element for which the query should be generated.
`private FileText`	`fileText` The `FileText` object, representing content of the file.
`private int`	`lineNumber` The line number of the element for which the query should be generated.
`private DetailAST`	`rootAst` The root ast.
`private int`	`tabWidth` The distance between tab stop position.
`private int`	`tokenType` The token type of the element for which the query should be generated.

Constructor Summary

Constructors
Constructor and Description
`XpathQueryGenerator(DetailAST rootAst, int lineNumber, int columnNumber, FileText fileText, int tabWidth)` Creates a new `XpathQueryGenerator` instance.
`XpathQueryGenerator(DetailAST rootAst, int lineNumber, int columnNumber, int tokenType, FileText fileText, int tabWidth)` Creates a new `XpathQueryGenerator` instance.
`XpathQueryGenerator(TreeWalkerAuditEvent event, int tabWidth)` Creates a new `XpathQueryGenerator` instance.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`private static java.lang.String`	`encode(java.lang.String value)` Escape <, >, &, ' and " as their entities.
`private static java.lang.String`	`encodeCharacter(char chr)` Encodes escape character for Xpath.
`private int`	`expandedTabColumn(DetailAST ast)` Returns the column number with tabs expanded.
`private static DetailAST`	`findChildWithTextAttribute(DetailAST root)` Returns child `DetailAst` element of the given root, which has text attribute.
`private static DetailAST`	`findChildWithTextAttributeRecursively(DetailAST root)` Returns child `DetailAst` element of the given root, which has text attribute.
`private static int`	`findPositionAmongSiblings(DetailAST ast)` Finds position of the ast element among siblings.
`java.util.List<java.lang.String>`	`generate()` Returns list of xpath queries of nodes, matching line number, column number and token type.
`static java.lang.String`	`generateXpathQuery(DetailAST ast)` Returns full xpath query for given ast element.
`private java.util.List<DetailAST>`	`getMatchingAstElements()` Returns list of nodes matching defined line number, column number and token type.
`private static java.lang.String`	`getXpathQuery(DetailAST root, DetailAST ast)` Returns relative xpath query for given ast element from root.
`private static boolean`	`hasAtLeastOneSiblingWithSameTokenType(DetailAST ast)` Checks if the given ast element has unique `TokenTypes` among siblings.
`private boolean`	`isMatchingByLineAndColumnAndTokenType(DetailAST ast)` Checks if the given `DetailAST` node is matching line number, column number and token type.
`private static boolean`	`isXpathQueryForNodeIsAccurateEnough(DetailAST ast)` Checks if ast element has all requirements to have unique xpath query.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - 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 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.

Class XpathQueryGenerator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

rootAst

lineNumber

columnNumber

tokenType

fileText

tabWidth

Constructor Detail

XpathQueryGenerator

XpathQueryGenerator

XpathQueryGenerator

Method Detail

generate

findChildWithTextAttribute

findChildWithTextAttributeRecursively

generateXpathQuery

findPositionAmongSiblings

isXpathQueryForNodeIsAccurateEnough

getMatchingAstElements

getXpathQuery

hasAtLeastOneSiblingWithSameTokenType

expandedTabColumn

isMatchingByLineAndColumnAndTokenType

encode

encodeCharacter