001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2025 the original author or authors. 004// 005// This library is free software; you can redistribute it and/or 006// modify it under the terms of the GNU Lesser General Public 007// License as published by the Free Software Foundation; either 008// version 2.1 of the License, or (at your option) any later version. 009// 010// This library is distributed in the hope that it will be useful, 011// but WITHOUT ANY WARRANTY; without even the implied warranty of 012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013// Lesser General Public License for more details. 014// 015// You should have received a copy of the GNU Lesser General Public 016// License along with this library; if not, write to the Free Software 017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 018/////////////////////////////////////////////////////////////////////////////////////////////// 019 020package com.puppycrawl.tools.checkstyle.checks.coding; 021 022import java.util.List; 023 024import com.puppycrawl.tools.checkstyle.StatelessCheck; 025import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 026import com.puppycrawl.tools.checkstyle.api.DetailAST; 027import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 028import com.puppycrawl.tools.checkstyle.xpath.AbstractNode; 029import com.puppycrawl.tools.checkstyle.xpath.RootNode; 030import net.sf.saxon.Configuration; 031import net.sf.saxon.om.Item; 032import net.sf.saxon.sxpath.XPathDynamicContext; 033import net.sf.saxon.sxpath.XPathEvaluator; 034import net.sf.saxon.sxpath.XPathExpression; 035import net.sf.saxon.trans.XPathException; 036 037/** 038 * <div> 039 * Evaluates Xpath query and report violation on all matching AST nodes. This check allows 040 * user to implement custom checks using Xpath. If Xpath query is not specified explicitly, 041 * then the check does nothing. 042 * </div> 043 * 044 * <p> 045 * It is recommended to define custom message for violation to explain what is not allowed and what 046 * to use instead, default message might be too abstract. To customize a message you need to 047 * add {@code message} element with <b>matchxpath.match</b> as {@code key} attribute and 048 * desired message as {@code value} attribute. 049 * </p> 050 * 051 * <p> 052 * Please read more about Xpath syntax at 053 * <a href="https://www.saxonica.com/html/documentation10/expressions/index.html">Xpath Syntax</a>. 054 * Information regarding Xpath functions can be found at 055 * <a href="https://www.saxonica.com/html/documentation10/functions/fn/index.html"> 056 * XSLT/XPath Reference</a>. 057 * Note, that <b>@text</b> attribute can be used only with token types that are listed in 058 * <a href="https://github.com/checkstyle/checkstyle/search?q=%22TOKEN_TYPES_WITH_TEXT_ATTRIBUTE+%3D+Arrays.asList%22"> 059 * XpathUtil</a>. 060 * </p> 061 * <ul> 062 * <li> 063 * Property {@code query} - Specify Xpath query. 064 * Type is {@code java.lang.String}. 065 * Default value is {@code ""}. 066 * </li> 067 * </ul> 068 * 069 * <p> 070 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 071 * </p> 072 * 073 * <p> 074 * Violation Message Keys: 075 * </p> 076 * <ul> 077 * <li> 078 * {@code matchxpath.match} 079 * </li> 080 * </ul> 081 * 082 * @since 8.39 083 */ 084@StatelessCheck 085public class MatchXpathCheck extends AbstractCheck { 086 087 /** 088 * A key is pointing to the warning message text provided by user. 089 */ 090 public static final String MSG_KEY = "matchxpath.match"; 091 092 /** Specify Xpath query. */ 093 private String query = ""; 094 095 /** Xpath expression. */ 096 private XPathExpression xpathExpression; 097 098 /** 099 * Setter to specify Xpath query. 100 * 101 * @param query Xpath query. 102 * @throws IllegalStateException if creation of xpath expression fails 103 * @since 8.39 104 */ 105 public void setQuery(String query) { 106 this.query = query; 107 if (!query.isEmpty()) { 108 try { 109 final XPathEvaluator xpathEvaluator = 110 new XPathEvaluator(Configuration.newConfiguration()); 111 xpathExpression = xpathEvaluator.createExpression(query); 112 } 113 catch (XPathException exc) { 114 throw new IllegalStateException("Creating Xpath expression failed: " + query, exc); 115 } 116 } 117 } 118 119 @Override 120 public int[] getDefaultTokens() { 121 return getRequiredTokens(); 122 } 123 124 @Override 125 public int[] getAcceptableTokens() { 126 return getRequiredTokens(); 127 } 128 129 @Override 130 public int[] getRequiredTokens() { 131 return CommonUtil.EMPTY_INT_ARRAY; 132 } 133 134 @Override 135 public boolean isCommentNodesRequired() { 136 return true; 137 } 138 139 @Override 140 public void beginTree(DetailAST rootAST) { 141 if (!query.isEmpty()) { 142 final List<DetailAST> matchingNodes = findMatchingNodesByXpathQuery(rootAST); 143 matchingNodes.forEach(node -> log(node, MSG_KEY)); 144 } 145 } 146 147 /** 148 * Find nodes that match query. 149 * 150 * @param rootAST root node 151 * @return list of matching nodes 152 * @throws IllegalStateException if evaluation of xpath query fails 153 */ 154 private List<DetailAST> findMatchingNodesByXpathQuery(DetailAST rootAST) { 155 try { 156 final RootNode rootNode = new RootNode(rootAST); 157 final XPathDynamicContext xpathDynamicContext = 158 xpathExpression.createDynamicContext(rootNode); 159 final List<Item> matchingItems = xpathExpression.evaluate(xpathDynamicContext); 160 return matchingItems.stream() 161 .map(item -> (DetailAST) ((AbstractNode) item).getUnderlyingNode()) 162 .toList(); 163 } 164 catch (XPathException exc) { 165 throw new IllegalStateException("Evaluation of Xpath query failed: " + query, exc); 166 } 167 } 168}