View Javadoc
1   ////////////////////////////////////////////////////////////////////////////////
2   // checkstyle: Checks Java source code for adherence to a set of rules.
3   // Copyright (C) 2001-2018 the original author or authors.
4   //
5   // This library is free software; you can redistribute it and/or
6   // modify it under the terms of the GNU Lesser General Public
7   // License as published by the Free Software Foundation; either
8   // version 2.1 of the License, or (at your option) any later version.
9   //
10  // This library is distributed in the hope that it will be useful,
11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  // Lesser General Public License for more details.
14  //
15  // You should have received a copy of the GNU Lesser General Public
16  // License along with this library; if not, write to the Free Software
17  // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18  ////////////////////////////////////////////////////////////////////////////////
19  
20  package com.puppycrawl.tools.checkstyle.checks.annotation;
21  
22  import java.util.regex.Matcher;
23  import java.util.regex.Pattern;
24  
25  import com.puppycrawl.tools.checkstyle.StatelessCheck;
26  import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
27  import com.puppycrawl.tools.checkstyle.api.DetailAST;
28  import com.puppycrawl.tools.checkstyle.api.TextBlock;
29  import com.puppycrawl.tools.checkstyle.api.TokenTypes;
30  import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTagInfo;
31  import com.puppycrawl.tools.checkstyle.utils.AnnotationUtility;
32  import com.puppycrawl.tools.checkstyle.utils.CommonUtils;
33  
34  /**
35   * <p>
36   * This class is used to verify that the {@link Override Override}
37   * annotation is present when the inheritDoc javadoc tag is present.
38   * </p>
39   *
40   * <p>
41   * Rationale: The {@link Override Override} annotation helps
42   * compiler tools ensure that an override is actually occurring.  It is
43   * quite easy to accidentally overload a method or hide a static method
44   * and using the {@link Override Override} annotation points
45   * out these problems.
46   * </p>
47   *
48   * <p>
49   * This check will log a violation if using the inheritDoc tag on a method that
50   * is not valid (ex: private, or static method).
51   * </p>
52   *
53   * <p>
54   * There is a slight difference between the Override annotation in Java 5 versus
55   * Java 6 and above. In Java 5, any method overridden from an interface cannot
56   * be annotated with Override. In Java 6 this behavior is allowed.
57   * </p>
58   *
59   * <p>
60   * As a result of the aforementioned difference between Java 5 and Java 6, a
61   * property called {@code javaFiveCompatibility } is available. This
62   * property will only check classes, interfaces, etc. that do not contain the
63   * extends or implements keyword or are not anonymous classes. This means it
64   * only checks methods overridden from {@code java.lang.Object}
65   *
66   * <b>Java 5 Compatibility mode severely limits this check. It is recommended to
67   * only use it on Java 5 source</b>
68   * </p>
69   *
70   * <pre>
71   * &lt;module name=&quot;MissingOverride&quot;&gt;
72   *    &lt;property name=&quot;javaFiveCompatibility&quot;
73   *        value=&quot;true&quot;/&gt;
74   * &lt;/module&gt;
75   * </pre>
76   *
77   * @author Travis Schneeberger
78   */
79  @StatelessCheck
80  public final class MissingOverrideCheck extends AbstractCheck {
81  
82      /**
83       * A key is pointing to the warning message text in "messages.properties"
84       * file.
85       */
86      public static final String MSG_KEY_TAG_NOT_VALID_ON = "tag.not.valid.on";
87  
88      /**
89       * A key is pointing to the warning message text in "messages.properties"
90       * file.
91       */
92      public static final String MSG_KEY_ANNOTATION_MISSING_OVERRIDE =
93          "annotation.missing.override";
94  
95      /** {@link Override Override} annotation name. */
96      private static final String OVERRIDE = "Override";
97  
98      /** Fully-qualified {@link Override Override} annotation name. */
99      private static final String FQ_OVERRIDE = "java.lang." + OVERRIDE;
100 
101     /** Compiled regexp to match Javadoc tags with no argument and {}. */
102     private static final Pattern MATCH_INHERIT_DOC =
103             CommonUtils.createPattern("\\{\\s*@(inheritDoc)\\s*\\}");
104 
105     /**
106      * Java 5 compatibility option.
107      * @see #setJavaFiveCompatibility(boolean)
108      */
109     private boolean javaFiveCompatibility;
110 
111     /**
112      * Sets Java 5 compatibility mode.
113      *
114      * <p>
115      * In Java 5, this check could flag code that is not valid for the Override
116      * annotation even though it is a proper override. See the class
117      * documentation for more information.
118      * </p>
119      *
120      * <p>
121      * Set this to true to turn on Java 5 compatibility mode. Set this to
122      * false to turn off Java 5 compatibility mode.
123      * </p>
124      *
125      * @param compatibility compatibility or not
126      */
127     public void setJavaFiveCompatibility(final boolean compatibility) {
128         javaFiveCompatibility = compatibility;
129     }
130 
131     @Override
132     public int[] getDefaultTokens() {
133         return getRequiredTokens();
134     }
135 
136     @Override
137     public int[] getAcceptableTokens() {
138         return getRequiredTokens();
139     }
140 
141     @Override
142     public int[] getRequiredTokens() {
143         return new int[]
144         {TokenTypes.METHOD_DEF, };
145     }
146 
147     // -@cs[CyclomaticComplexity] Too complex to break apart.
148     @Override
149     public void visitToken(final DetailAST ast) {
150         final TextBlock javadoc =
151             getFileContents().getJavadocBefore(ast.getLineNo());
152 
153         final boolean containsTag = containsJavadocTag(javadoc);
154         if (containsTag && !JavadocTagInfo.INHERIT_DOC.isValidOn(ast)) {
155             log(ast.getLineNo(), MSG_KEY_TAG_NOT_VALID_ON,
156                 JavadocTagInfo.INHERIT_DOC.getText());
157         }
158         else {
159             boolean check = true;
160 
161             if (javaFiveCompatibility) {
162                 final DetailAST defOrNew = ast.getParent().getParent();
163 
164                 if (defOrNew.findFirstToken(TokenTypes.EXTENDS_CLAUSE) != null
165                     || defOrNew.findFirstToken(TokenTypes.IMPLEMENTS_CLAUSE) != null
166                     || defOrNew.getType() == TokenTypes.LITERAL_NEW) {
167                     check = false;
168                 }
169             }
170 
171             if (check
172                 && containsTag
173                 && !AnnotationUtility.containsAnnotation(ast, OVERRIDE)
174                 && !AnnotationUtility.containsAnnotation(ast, FQ_OVERRIDE)) {
175                 log(ast.getLineNo(), MSG_KEY_ANNOTATION_MISSING_OVERRIDE);
176             }
177         }
178     }
179 
180     /**
181      * Checks to see if the text block contains a inheritDoc tag.
182      *
183      * @param javadoc the javadoc of the AST
184      * @return true if contains the tag
185      */
186     private static boolean containsJavadocTag(final TextBlock javadoc) {
187         boolean javadocTag = false;
188 
189         if (javadoc != null) {
190             final String[] lines = javadoc.getText();
191 
192             for (final String line : lines) {
193                 final Matcher matchInheritDoc =
194                     MATCH_INHERIT_DOC.matcher(line);
195 
196                 if (matchInheritDoc.find()) {
197                     javadocTag = true;
198                     break;
199                 }
200             }
201         }
202         return javadocTag;
203     }
204 
205 }