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 * &lt;!DOCTYPE import-control PUBLIC
104 *     "-//Checkstyle//DTD ImportControl Configuration 1.4//EN"
105 *     "https://checkstyle.org/dtds/import_control_1_4.dtd"&gt;
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}