1 /////////////////////////////////////////////////////////////////////////////////////////////// 2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules. 3 // Copyright (C) 2001-2024 the original author or authors. 4 // 5 // This library is free software; you can redistribute it and/or 6 // modify it under the terms of the GNU Lesser General Public 7 // License as published by the Free Software Foundation; either 8 // version 2.1 of the License, or (at your option) any later version. 9 // 10 // This library is distributed in the hope that it will be useful, 11 // but WITHOUT ANY WARRANTY; without even the implied warranty of 12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 // Lesser General Public License for more details. 14 // 15 // You should have received a copy of the GNU Lesser General Public 16 // License along with this library; if not, write to the Free Software 17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 /////////////////////////////////////////////////////////////////////////////////////////////// 19 20 package com.puppycrawl.tools.checkstyle.checks.coding; 21 22 import java.util.List; 23 import java.util.stream.Collectors; 24 25 import com.puppycrawl.tools.checkstyle.StatelessCheck; 26 import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 27 import com.puppycrawl.tools.checkstyle.api.DetailAST; 28 import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 29 import com.puppycrawl.tools.checkstyle.xpath.AbstractNode; 30 import com.puppycrawl.tools.checkstyle.xpath.RootNode; 31 import net.sf.saxon.Configuration; 32 import net.sf.saxon.om.Item; 33 import net.sf.saxon.sxpath.XPathDynamicContext; 34 import net.sf.saxon.sxpath.XPathEvaluator; 35 import net.sf.saxon.sxpath.XPathExpression; 36 import net.sf.saxon.trans.XPathException; 37 38 /** 39 * <p> 40 * Evaluates Xpath query and report violation on all matching AST nodes. This check allows 41 * user to implement custom checks using Xpath. If Xpath query is not specified explicitly, 42 * then the check does nothing. 43 * </p> 44 * <p> 45 * It is recommended to define custom message for violation to explain what is not allowed and what 46 * to use instead, default message might be too abstract. To customize a message you need to 47 * add {@code message} element with <b>matchxpath.match</b> as {@code key} attribute and 48 * desired message as {@code value} attribute. 49 * </p> 50 * <p> 51 * Please read more about Xpath syntax at 52 * <a href="https://www.saxonica.com/html/documentation10/expressions/index.html">Xpath Syntax</a>. 53 * Information regarding Xpath functions can be found at 54 * <a href="https://www.saxonica.com/html/documentation10/functions/fn/index.html"> 55 * XSLT/XPath Reference</a>. 56 * Note, that <b>@text</b> attribute can be used only with token types that are listed in 57 * <a href="https://github.com/checkstyle/checkstyle/search?q=%22TOKEN_TYPES_WITH_TEXT_ATTRIBUTE+%3D+Arrays.asList%22"> 58 * XpathUtil</a>. 59 * </p> 60 * <ul> 61 * <li> 62 * Property {@code query} - Specify Xpath query. 63 * Type is {@code java.lang.String}. 64 * Default value is {@code ""}. 65 * </li> 66 * </ul> 67 * <p> 68 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 69 * </p> 70 * <p> 71 * Violation Message Keys: 72 * </p> 73 * <ul> 74 * <li> 75 * {@code matchxpath.match} 76 * </li> 77 * </ul> 78 * 79 * @since 8.39 80 */ 81 @StatelessCheck 82 public class MatchXpathCheck extends AbstractCheck { 83 84 /** 85 * A key is pointing to the warning message text provided by user. 86 */ 87 public static final String MSG_KEY = "matchxpath.match"; 88 89 /** Specify Xpath query. */ 90 private String query = ""; 91 92 /** Xpath expression. */ 93 private XPathExpression xpathExpression; 94 95 /** 96 * Setter to specify Xpath query. 97 * 98 * @param query Xpath query. 99 * @throws IllegalStateException if creation of xpath expression fails 100 * @since 8.39 101 */ 102 public void setQuery(String query) { 103 this.query = query; 104 if (!query.isEmpty()) { 105 try { 106 final XPathEvaluator xpathEvaluator = 107 new XPathEvaluator(Configuration.newConfiguration()); 108 xpathExpression = xpathEvaluator.createExpression(query); 109 } 110 catch (XPathException ex) { 111 throw new IllegalStateException("Creating Xpath expression failed: " + query, ex); 112 } 113 } 114 } 115 116 @Override 117 public int[] getDefaultTokens() { 118 return getRequiredTokens(); 119 } 120 121 @Override 122 public int[] getAcceptableTokens() { 123 return getRequiredTokens(); 124 } 125 126 @Override 127 public int[] getRequiredTokens() { 128 return CommonUtil.EMPTY_INT_ARRAY; 129 } 130 131 @Override 132 public boolean isCommentNodesRequired() { 133 return true; 134 } 135 136 @Override 137 public void beginTree(DetailAST rootAST) { 138 if (!query.isEmpty()) { 139 final List<DetailAST> matchingNodes = findMatchingNodesByXpathQuery(rootAST); 140 matchingNodes.forEach(node -> log(node, MSG_KEY)); 141 } 142 } 143 144 /** 145 * Find nodes that match query. 146 * 147 * @param rootAST root node 148 * @return list of matching nodes 149 * @throws IllegalStateException if evaluation of xpath query fails 150 */ 151 private List<DetailAST> findMatchingNodesByXpathQuery(DetailAST rootAST) { 152 try { 153 final RootNode rootNode = new RootNode(rootAST); 154 final XPathDynamicContext xpathDynamicContext = 155 xpathExpression.createDynamicContext(rootNode); 156 final List<Item> matchingItems = xpathExpression.evaluate(xpathDynamicContext); 157 return matchingItems.stream() 158 .map(item -> (DetailAST) ((AbstractNode) item).getUnderlyingNode()) 159 .collect(Collectors.toUnmodifiableList()); 160 } 161 catch (XPathException ex) { 162 throw new IllegalStateException("Evaluation of Xpath query failed: " + query, ex); 163 } 164 } 165 }