Source code

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