Source code

001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2022 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.javadoc;
021
022import java.util.Arrays;
023import java.util.HashMap;
024import java.util.HashSet;
025import java.util.Locale;
026import java.util.Map;
027import java.util.Set;
028import java.util.stream.Collectors;
029
030import com.puppycrawl.tools.checkstyle.JavadocDetailNodeParser;
031import com.puppycrawl.tools.checkstyle.JavadocDetailNodeParser.ParseErrorMessage;
032import com.puppycrawl.tools.checkstyle.JavadocDetailNodeParser.ParseStatus;
033import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
034import com.puppycrawl.tools.checkstyle.api.DetailAST;
035import com.puppycrawl.tools.checkstyle.api.DetailNode;
036import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
037import com.puppycrawl.tools.checkstyle.api.LineColumn;
038import com.puppycrawl.tools.checkstyle.api.TokenTypes;
039import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
040import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
041
042/**
043 * Base class for Checks that process Javadoc comments.
044 *
045 * @noinspection NoopMethodInAbstractClass
046 */
047public abstract class AbstractJavadocCheck extends AbstractCheck {
048
049    /**
050     * Message key of error message. Missed close HTML tag breaks structure
051     * of parse tree, so parser stops parsing and generates such error
052     * message. This case is special because parser prints error like
053     * {@code "no viable alternative at input 'b \n *\n'"} and it is not
054     * clear that error is about missed close HTML tag.
055     */
056    public static final String MSG_JAVADOC_MISSED_HTML_CLOSE =
057            JavadocDetailNodeParser.MSG_JAVADOC_MISSED_HTML_CLOSE;
058
059    /**
060     * Message key of error message.
061     */
062    public static final String MSG_JAVADOC_WRONG_SINGLETON_TAG =
063            JavadocDetailNodeParser.MSG_JAVADOC_WRONG_SINGLETON_TAG;
064
065    /**
066     * Parse error while rule recognition.
067     */
068    public static final String MSG_JAVADOC_PARSE_RULE_ERROR =
069            JavadocDetailNodeParser.MSG_JAVADOC_PARSE_RULE_ERROR;
070
071    /**
072     * Key is "line:column". Value is {@link DetailNode} tree. Map is stored in {@link ThreadLocal}
073     * to guarantee basic thread safety and avoid shared, mutable state when not necessary.
074     */
075    private static final ThreadLocal<Map<LineColumn, ParseStatus>> TREE_CACHE =
076            ThreadLocal.withInitial(HashMap::new);
077
078    /**
079     * The file context.
080     *
081     * @noinspection ThreadLocalNotStaticFinal
082     */
083    private final ThreadLocal<FileContext> context = ThreadLocal.withInitial(FileContext::new);
084
085    /** The javadoc tokens the check is interested in. */
086    private final Set<Integer> javadocTokens = new HashSet<>();
087
088    /**
089     * This property determines if a check should log a violation upon encountering javadoc with
090     * non-tight html. The default return value for this method is set to false since checks
091     * generally tend to be fine with non tight html. It can be set through config file if a check
092     * is to log violation upon encountering non-tight HTML in javadoc.
093     *
094     * @see ParseStatus#isNonTight()
095     * @see <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">
096     *     Tight HTML rules</a>
097     */
098    private boolean violateExecutionOnNonTightHtml;
099
100    /**
101     * Returns the default javadoc token types a check is interested in.
102     *
103     * @return the default javadoc token types
104     * @see JavadocTokenTypes
105     */
106    public abstract int[] getDefaultJavadocTokens();
107
108    /**
109     * Called to process a Javadoc token.
110     *
111     * @param ast
112     *        the token to process
113     */
114    public abstract void visitJavadocToken(DetailNode ast);
115
116    /**
117     * The configurable javadoc token set.
118     * Used to protect Checks against malicious users who specify an
119     * unacceptable javadoc token set in the configuration file.
120     * The default implementation returns the check's default javadoc tokens.
121     *
122     * @return the javadoc token set this check is designed for.
123     * @see JavadocTokenTypes
124     */
125    public int[] getAcceptableJavadocTokens() {
126        final int[] defaultJavadocTokens = getDefaultJavadocTokens();
127        final int[] copy = new int[defaultJavadocTokens.length];
128        System.arraycopy(defaultJavadocTokens, 0, copy, 0, defaultJavadocTokens.length);
129        return copy;
130    }
131
132    /**
133     * The javadoc tokens that this check must be registered for.
134     *
135     * @return the javadoc token set this must be registered for.
136     * @see JavadocTokenTypes
137     */
138    public int[] getRequiredJavadocTokens() {
139        return CommonUtil.EMPTY_INT_ARRAY;
140    }
141
142    /**
143     * This method determines if a check should process javadoc containing non-tight html tags.
144     * This method must be overridden in checks extending {@code AbstractJavadocCheck} which
145     * are not supposed to process javadoc containing non-tight html tags.
146     *
147     * @return true if the check should or can process javadoc containing non-tight html tags;
148     *     false otherwise
149     * @see ParseStatus#isNonTight()
150     * @see <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">
151     *     Tight HTML rules</a>
152     */
153    public boolean acceptJavadocWithNonTightHtml() {
154        return true;
155    }
156
157    /**
158     * Setter to control when to print violations if the Javadoc being examined by this check
159     * violates the tight html rules defined at
160     * <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">
161     *     Tight-HTML Rules</a>.
162     *
163     * @param shouldReportViolation value to which the field shall be set to
164     */
165    public final void setViolateExecutionOnNonTightHtml(boolean shouldReportViolation) {
166        violateExecutionOnNonTightHtml = shouldReportViolation;
167    }
168
169    /**
170     * Adds a set of tokens the check is interested in.
171     *
172     * @param strRep the string representation of the tokens interested in
173     */
174    public final void setJavadocTokens(String... strRep) {
175        for (String str : strRep) {
176            javadocTokens.add(JavadocUtil.getTokenId(str));
177        }
178    }
179
180    @Override
181    public void init() {
182        validateDefaultJavadocTokens();
183        if (javadocTokens.isEmpty()) {
184            javadocTokens.addAll(
185                    Arrays.stream(getDefaultJavadocTokens()).boxed().collect(Collectors.toList()));
186        }
187        else {
188            final int[] acceptableJavadocTokens = getAcceptableJavadocTokens();
189            Arrays.sort(acceptableJavadocTokens);
190            for (Integer javadocTokenId : javadocTokens) {
191                if (Arrays.binarySearch(acceptableJavadocTokens, javadocTokenId) < 0) {
192                    final String message = String.format(Locale.ROOT, "Javadoc Token \"%s\" was "
193                            + "not found in Acceptable javadoc tokens list in check %s",
194                            JavadocUtil.getTokenName(javadocTokenId), getClass().getName());
195                    throw new IllegalStateException(message);
196                }
197            }
198        }
199    }
200
201    /**
202     * Validates that check's required javadoc tokens are subset of default javadoc tokens.
203     *
204     * @throws IllegalStateException when validation of default javadoc tokens fails
205     */
206    private void validateDefaultJavadocTokens() {
207        if (getRequiredJavadocTokens().length != 0) {
208            final int[] defaultJavadocTokens = getDefaultJavadocTokens();
209            Arrays.sort(defaultJavadocTokens);
210            for (final int javadocToken : getRequiredJavadocTokens()) {
211                if (Arrays.binarySearch(defaultJavadocTokens, javadocToken) < 0) {
212                    final String message = String.format(Locale.ROOT,
213                            "Javadoc Token \"%s\" from required javadoc "
214                                + "tokens was not found in default "
215                                + "javadoc tokens list in check %s",
216                            javadocToken, getClass().getName());
217                    throw new IllegalStateException(message);
218                }
219            }
220        }
221    }
222
223    /**
224     * Called before the starting to process a tree.
225     *
226     * @param rootAst
227     *        the root of the tree
228     * @noinspection WeakerAccess
229     */
230    public void beginJavadocTree(DetailNode rootAst) {
231        // No code by default, should be overridden only by demand at subclasses
232    }
233
234    /**
235     * Called after finished processing a tree.
236     *
237     * @param rootAst
238     *        the root of the tree
239     * @noinspection WeakerAccess
240     */
241    public void finishJavadocTree(DetailNode rootAst) {
242        // No code by default, should be overridden only by demand at subclasses
243    }
244
245    /**
246     * Called after all the child nodes have been process.
247     *
248     * @param ast
249     *        the token leaving
250     */
251    public void leaveJavadocToken(DetailNode ast) {
252        // No code by default, should be overridden only by demand at subclasses
253    }
254
255    /**
256     * Defined final to not allow JavadocChecks to change default tokens.
257     *
258     * @return default tokens
259     */
260    @Override
261    public final int[] getDefaultTokens() {
262        return getRequiredTokens();
263    }
264
265    @Override
266    public final int[] getAcceptableTokens() {
267        return getRequiredTokens();
268    }
269
270    @Override
271    public final int[] getRequiredTokens() {
272        return new int[] {TokenTypes.BLOCK_COMMENT_BEGIN };
273    }
274
275    /**
276     * Defined final because all JavadocChecks require comment nodes.
277     *
278     * @return true
279     */
280    @Override
281    public final boolean isCommentNodesRequired() {
282        return true;
283    }
284
285    @Override
286    public final void beginTree(DetailAST rootAST) {
287        TREE_CACHE.get().clear();
288    }
289
290    @Override
291    public final void finishTree(DetailAST rootAST) {
292        // No code, prevent override in subclasses
293    }
294
295    @Override
296    public final void visitToken(DetailAST blockCommentNode) {
297        if (JavadocUtil.isJavadocComment(blockCommentNode)) {
298            // store as field, to share with child Checks
299            context.get().blockCommentAst = blockCommentNode;
300
301            final LineColumn treeCacheKey = new LineColumn(blockCommentNode.getLineNo(),
302                    blockCommentNode.getColumnNo());
303
304            final ParseStatus result;
305
306            if (TREE_CACHE.get().containsKey(treeCacheKey)) {
307                result = TREE_CACHE.get().get(treeCacheKey);
308            }
309            else {
310                result = context.get().parser
311                        .parseJavadocAsDetailNode(blockCommentNode);
312                TREE_CACHE.get().put(treeCacheKey, result);
313            }
314
315            if (result.getParseErrorMessage() == null) {
316                if (acceptJavadocWithNonTightHtml() || !result.isNonTight()) {
317                    processTree(result.getTree());
318                }
319
320                if (violateExecutionOnNonTightHtml && result.isNonTight()) {
321                    log(result.getFirstNonTightHtmlTag().getLine(),
322                            JavadocDetailNodeParser.MSG_UNCLOSED_HTML_TAG,
323                            result.getFirstNonTightHtmlTag().getText());
324                }
325            }
326            else {
327                final ParseErrorMessage parseErrorMessage = result.getParseErrorMessage();
328                log(parseErrorMessage.getLineNumber(),
329                        parseErrorMessage.getMessageKey(),
330                        parseErrorMessage.getMessageArguments());
331            }
332        }
333    }
334
335    /**
336     * Getter for block comment in Java language syntax tree.
337     *
338     * @return A block comment in the syntax tree.
339     */
340    protected DetailAST getBlockCommentAst() {
341        return context.get().blockCommentAst;
342    }
343
344    /**
345     * Processes JavadocAST tree notifying Check.
346     *
347     * @param root
348     *        root of JavadocAST tree.
349     */
350    private void processTree(DetailNode root) {
351        beginJavadocTree(root);
352        walk(root);
353        finishJavadocTree(root);
354    }
355
356    /**
357     * Processes a node calling Check at interested nodes.
358     *
359     * @param root
360     *        the root of tree for process
361     */
362    private void walk(DetailNode root) {
363        DetailNode curNode = root;
364        while (curNode != null) {
365            boolean waitsForProcessing = shouldBeProcessed(curNode);
366
367            if (waitsForProcessing) {
368                visitJavadocToken(curNode);
369            }
370            DetailNode toVisit = JavadocUtil.getFirstChild(curNode);
371            while (curNode != null && toVisit == null) {
372                if (waitsForProcessing) {
373                    leaveJavadocToken(curNode);
374                }
375
376                toVisit = JavadocUtil.getNextSibling(curNode);
377                if (toVisit == null) {
378                    curNode = curNode.getParent();
379                    if (curNode != null) {
380                        waitsForProcessing = shouldBeProcessed(curNode);
381                    }
382                }
383            }
384            curNode = toVisit;
385        }
386    }
387
388    /**
389     * Checks whether the current node should be processed by the check.
390     *
391     * @param curNode current node.
392     * @return true if the current node should be processed by the check.
393     */
394    private boolean shouldBeProcessed(DetailNode curNode) {
395        return javadocTokens.contains(curNode.getType());
396    }
397
398    @Override
399    public void destroy() {
400        super.destroy();
401        context.remove();
402        TREE_CACHE.remove();
403    }
404
405    /**
406     * The file context holder.
407     */
408    private static class FileContext {
409
410        /**
411         * Parses content of Javadoc comment as DetailNode tree.
412         */
413        private final JavadocDetailNodeParser parser = new JavadocDetailNodeParser();
414
415        /**
416         * DetailAST node of considered Javadoc comment that is just a block comment
417         * in Java language syntax tree.
418         */
419        private DetailAST blockCommentAst;
420
421    }
422
423}