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.imports; 021 022import java.net.URI; 023import java.util.Collections; 024import java.util.Set; 025import java.util.regex.Pattern; 026 027import com.puppycrawl.tools.checkstyle.FileStatefulCheck; 028import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 029import com.puppycrawl.tools.checkstyle.api.CheckstyleException; 030import com.puppycrawl.tools.checkstyle.api.DetailAST; 031import com.puppycrawl.tools.checkstyle.api.ExternalResourceHolder; 032import com.puppycrawl.tools.checkstyle.api.FullIdent; 033import com.puppycrawl.tools.checkstyle.api.TokenTypes; 034 035/** 036 * <p> 037 * Controls what can be imported in each package and file. Useful for ensuring 038 * that application layering rules are not violated, especially on large projects. 039 * </p> 040 * <p> 041 * You can control imports based on the package name or based on the file name. 042 * When controlling packages, all files and sub-packages in the declared package 043 * will be controlled by this check. To specify differences between a main package 044 * and a sub-package, you must define the sub-package inside the main package. 045 * When controlling file, only the file name is considered and only files processed by 046 * <a href="https://checkstyle.org/config.html#TreeWalker">TreeWalker</a>. 047 * The file's extension is ignored. 048 * </p> 049 * <p> 050 * Short description of the behaviour: 051 * </p> 052 * <ul> 053 * <li> 054 * Check starts checking from the longest matching subpackage (later 'current subpackage') or 055 * the first file name match described inside import control file to package defined in class file. 056 * <ul> 057 * <li> 058 * The longest matching subpackage is found by starting with the root package and 059 * examining if any of the sub-packages or file definitions match the current 060 * class' package or file name. 061 * </li> 062 * <li> 063 * If a file name is matched first, that is considered the longest match and becomes 064 * the current file/subpackage. 065 * </li> 066 * <li> 067 * If another subpackage is matched, then it's subpackages and file names are examined 068 * for the next longest match and the process repeats recursively. 069 * </li> 070 * <li> 071 * If no subpackages or file names are matched, the current subpackage is then used. 072 * </li> 073 * </ul> 074 * </li> 075 * <li> 076 * Order of rules in the same subpackage/root are defined by the order of declaration 077 * in the XML file, which is from top (first) to bottom (last). 078 * </li> 079 * <li> 080 * If there is matching allow/disallow rule inside the current file/subpackage 081 * then the Check returns the first "allowed" or "disallowed" message. 082 * </li> 083 * <li> 084 * If there is no matching allow/disallow rule inside the current file/subpackage 085 * then it continues checking in the parent subpackage. 086 * </li> 087 * <li> 088 * If there is no matching allow/disallow rule in any of the files/subpackages, 089 * including the root level (import-control), then the import is disallowed by default. 090 * </li> 091 * </ul> 092 * <p> 093 * The DTD for an import control XML document is at 094 * <a href="https://checkstyle.org/dtds/import_control_1_4.dtd"> 095 * https://checkstyle.org/dtds/import_control_1_4.dtd</a>. 096 * It contains documentation on each of the elements and attributes. 097 * </p> 098 * <p> 099 * The check validates a XML document when it loads the document. To validate against 100 * the above DTD, include the following document type declaration in your XML document: 101 * </p> 102 * <pre> 103 * <!DOCTYPE import-control PUBLIC 104 * "-//Checkstyle//DTD ImportControl Configuration 1.4//EN" 105 * "https://checkstyle.org/dtds/import_control_1_4.dtd"> 106 * </pre> 107 * <ul> 108 * <li> 109 * Property {@code file} - Specify the location of the file containing the 110 * import control configuration. It can be a regular file, URL or resource path. 111 * It will try loading the path as a URL first, then as a file, and finally as a resource. 112 * Type is {@code java.net.URI}. 113 * Default value is {@code null}. 114 * </li> 115 * <li> 116 * Property {@code path} - Specify the regular expression of file paths to which 117 * this check should apply. Files that don't match the pattern will not be checked. 118 * The pattern will be matched against the full absolute file path. 119 * Type is {@code java.util.regex.Pattern}. 120 * Default value is {@code ".*"}. 121 * </li> 122 * </ul> 123 * <p> 124 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 125 * </p> 126 * <p> 127 * Violation Message Keys: 128 * </p> 129 * <ul> 130 * <li> 131 * {@code import.control.disallowed} 132 * </li> 133 * <li> 134 * {@code import.control.missing.file} 135 * </li> 136 * <li> 137 * {@code import.control.unknown.pkg} 138 * </li> 139 * </ul> 140 * 141 * @since 4.0 142 */ 143@FileStatefulCheck 144public class ImportControlCheck extends AbstractCheck implements ExternalResourceHolder { 145 146 /** 147 * A key is pointing to the warning message text in "messages.properties" 148 * file. 149 */ 150 public static final String MSG_MISSING_FILE = "import.control.missing.file"; 151 152 /** 153 * A key is pointing to the warning message text in "messages.properties" 154 * file. 155 */ 156 public static final String MSG_UNKNOWN_PKG = "import.control.unknown.pkg"; 157 158 /** 159 * A key is pointing to the warning message text in "messages.properties" 160 * file. 161 */ 162 public static final String MSG_DISALLOWED = "import.control.disallowed"; 163 164 /** 165 * A part of message for exception. 166 */ 167 private static final String UNABLE_TO_LOAD = "Unable to load "; 168 169 /** 170 * Specify the location of the file containing the import control configuration. 171 * It can be a regular file, URL or resource path. It will try loading the path 172 * as a URL first, then as a file, and finally as a resource. 173 */ 174 private URI file; 175 176 /** 177 * Specify the regular expression of file paths to which this check should apply. 178 * Files that don't match the pattern will not be checked. The pattern will 179 * be matched against the full absolute file path. 180 */ 181 private Pattern path = Pattern.compile(".*"); 182 /** Whether to process the current file. */ 183 private boolean processCurrentFile; 184 185 /** The root package controller. */ 186 private PkgImportControl root; 187 /** The package doing the import. */ 188 private String packageName; 189 /** The file name doing the import. */ 190 private String fileName; 191 192 /** 193 * The package controller for the current file. Used for performance 194 * optimisation. 195 */ 196 private AbstractImportControl currentImportControl; 197 198 @Override 199 public int[] getDefaultTokens() { 200 return getRequiredTokens(); 201 } 202 203 @Override 204 public int[] getAcceptableTokens() { 205 return getRequiredTokens(); 206 } 207 208 @Override 209 public int[] getRequiredTokens() { 210 return new int[] {TokenTypes.PACKAGE_DEF, TokenTypes.IMPORT, TokenTypes.STATIC_IMPORT, }; 211 } 212 213 // suppress deprecation until https://github.com/checkstyle/checkstyle/issues/11166 214 @SuppressWarnings("deprecation") 215 @Override 216 public void beginTree(DetailAST rootAST) { 217 currentImportControl = null; 218 processCurrentFile = path.matcher(getFilePath()).find(); 219 fileName = getFileContents().getText().getFile().getName(); 220 221 final int period = fileName.lastIndexOf('.'); 222 223 if (period != -1) { 224 fileName = fileName.substring(0, period); 225 } 226 } 227 228 @Override 229 public void visitToken(DetailAST ast) { 230 if (processCurrentFile) { 231 if (ast.getType() == TokenTypes.PACKAGE_DEF) { 232 if (root == null) { 233 log(ast, MSG_MISSING_FILE); 234 } 235 else { 236 packageName = getPackageText(ast); 237 currentImportControl = root.locateFinest(packageName, fileName); 238 if (currentImportControl == null) { 239 log(ast, MSG_UNKNOWN_PKG); 240 } 241 } 242 } 243 else if (currentImportControl != null) { 244 final String importText = getImportText(ast); 245 final AccessResult access = currentImportControl.checkAccess(packageName, fileName, 246 importText); 247 if (access != AccessResult.ALLOWED) { 248 log(ast, MSG_DISALLOWED, importText); 249 } 250 } 251 } 252 } 253 254 @Override 255 public Set<String> getExternalResourceLocations() { 256 return Collections.singleton(file.toString()); 257 } 258 259 /** 260 * Returns package text. 261 * 262 * @param ast PACKAGE_DEF ast node 263 * @return String that represents full package name 264 */ 265 private static String getPackageText(DetailAST ast) { 266 final DetailAST nameAST = ast.getLastChild().getPreviousSibling(); 267 return FullIdent.createFullIdent(nameAST).getText(); 268 } 269 270 /** 271 * Returns import text. 272 * 273 * @param ast ast node that represents import 274 * @return String that represents importing class 275 */ 276 private static String getImportText(DetailAST ast) { 277 final FullIdent imp; 278 if (ast.getType() == TokenTypes.IMPORT) { 279 imp = FullIdent.createFullIdentBelow(ast); 280 } 281 else { 282 // know it is a static import 283 imp = FullIdent.createFullIdent(ast 284 .getFirstChild().getNextSibling()); 285 } 286 return imp.getText(); 287 } 288 289 /** 290 * Setter to specify the location of the file containing the import control configuration. 291 * It can be a regular file, URL or resource path. It will try loading the path 292 * as a URL first, then as a file, and finally as a resource. 293 * 294 * @param uri the uri of the file to load. 295 * @throws IllegalArgumentException on error loading the file. 296 * @since 4.0 297 */ 298 public void setFile(URI uri) { 299 // Handle empty param 300 if (uri != null) { 301 try { 302 root = ImportControlLoader.load(uri); 303 file = uri; 304 } 305 catch (CheckstyleException ex) { 306 throw new IllegalArgumentException(UNABLE_TO_LOAD + uri, ex); 307 } 308 } 309 } 310 311 /** 312 * Setter to specify the regular expression of file paths to which this check should apply. 313 * Files that don't match the pattern will not be checked. The pattern will be matched 314 * against the full absolute file path. 315 * 316 * @param pattern the file path regex this check should apply to. 317 * @since 7.5 318 */ 319 public void setPath(Pattern pattern) { 320 path = pattern; 321 } 322 323}