001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2024 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; 023import java.util.stream.Collectors; 024 025import com.puppycrawl.tools.checkstyle.StatelessCheck; 026import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 027import com.puppycrawl.tools.checkstyle.api.DetailAST; 028import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 029import com.puppycrawl.tools.checkstyle.xpath.AbstractNode; 030import com.puppycrawl.tools.checkstyle.xpath.RootNode; 031import net.sf.saxon.Configuration; 032import net.sf.saxon.om.Item; 033import net.sf.saxon.sxpath.XPathDynamicContext; 034import net.sf.saxon.sxpath.XPathEvaluator; 035import net.sf.saxon.sxpath.XPathExpression; 036import net.sf.saxon.trans.XPathException; 037 038/** 039 * <p> 040 * Evaluates Xpath query and report violation on all matching AST nodes. This check allows 041 * user to implement custom checks using Xpath. If Xpath query is not specified explicitly, 042 * then the check does nothing. 043 * </p> 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 * <p> 051 * Please read more about Xpath syntax at 052 * <a href="https://www.saxonica.com/html/documentation10/expressions/index.html">Xpath Syntax</a>. 053 * Information regarding Xpath functions can be found at 054 * <a href="https://www.saxonica.com/html/documentation10/functions/fn/index.html"> 055 * XSLT/XPath Reference</a>. 056 * Note, that <b>@text</b> attribute can be used only with token types that are listed in 057 * <a href="https://github.com/checkstyle/checkstyle/search?q=%22TOKEN_TYPES_WITH_TEXT_ATTRIBUTE+%3D+Arrays.asList%22"> 058 * XpathUtil</a>. 059 * </p> 060 * <ul> 061 * <li> 062 * Property {@code query} - Specify Xpath query. 063 * Type is {@code java.lang.String}. 064 * Default value is {@code ""}. 065 * </li> 066 * </ul> 067 * <p> 068 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 069 * </p> 070 * <p> 071 * Violation Message Keys: 072 * </p> 073 * <ul> 074 * <li> 075 * {@code matchxpath.match} 076 * </li> 077 * </ul> 078 * 079 * @since 8.39 080 */ 081@StatelessCheck 082public class MatchXpathCheck extends AbstractCheck { 083 084 /** 085 * A key is pointing to the warning message text provided by user. 086 */ 087 public static final String MSG_KEY = "matchxpath.match"; 088 089 /** Specify Xpath query. */ 090 private String query = ""; 091 092 /** Xpath expression. */ 093 private XPathExpression xpathExpression; 094 095 /** 096 * Setter to specify Xpath query. 097 * 098 * @param query Xpath query. 099 * @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}