001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2015 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.coding;
021
022import java.util.Arrays;
023
024import org.apache.commons.lang3.ArrayUtils;
025
026import com.puppycrawl.tools.checkstyle.api.Check;
027import com.puppycrawl.tools.checkstyle.api.DetailAST;
028import com.puppycrawl.tools.checkstyle.api.TokenTypes;
029import com.puppycrawl.tools.checkstyle.utils.CheckUtils;
030import com.puppycrawl.tools.checkstyle.utils.ScopeUtils;
031import com.puppycrawl.tools.checkstyle.utils.TokenUtils;
032
033/**
034 * <p>
035 * Checks that there are no <a href="https://en.wikipedia.org/wiki/Magic_number_%28programming%29">
036 * &quot;magic numbers&quot;</a> where a magic
037 * number is a numeric literal that is not defined as a constant.
038 * By default, -1, 0, 1, and 2 are not considered to be magic numbers.
039 * </p>
040 *
041 * <p>Constant definition is any variable/field that has 'final' modifier.
042 * It is fine to have one constant defining multiple numeric literals within one expression:
043 * <pre>
044 * {@code static final int SECONDS_PER_DAY = 24 * 60 * 60;
045 * static final double SPECIAL_RATIO = 4.0 / 3.0;
046 * static final double SPECIAL_SUM = 1 + Math.E;
047 * static final double SPECIAL_DIFFERENCE = 4 - Math.PI;
048 * static final Border STANDARD_BORDER = BorderFactory.createEmptyBorder(3, 3, 3, 3);
049 * static final Integer ANSWER_TO_THE_ULTIMATE_QUESTION_OF_LIFE = new Integer(42);}
050 * </pre>
051 *
052 * <p>Check have following options:
053 * ignoreHashCodeMethod - ignore magic numbers in hashCode methods;
054 * ignoreAnnotation - ignore magic numbers in annotation declarations;
055 * ignoreFieldDeclaration - ignore magic numbers in field declarations.
056 * <p>
057 * To configure the check with default configuration:
058 * </p>
059 * <pre>
060 * &lt;module name=&quot;MagicNumber&quot;/&gt;
061 * </pre>
062 * <p>
063 * results is following violations:
064 * </p>
065 * <pre>
066 * {@code
067 *   {@literal @}MyAnnotation(6) // violation
068 *   class MyClass {
069 *       private field = 7; // violation
070 *
071 *       void foo() {
072 *          int i = i + 1; // no violation
073 *          int j = j + 8; // violation
074 *       }
075 *   }
076 * }
077 * </pre>
078 * <p>
079 * To configure the check so that it checks floating-point numbers
080 * that are not 0, 0.5, or 1:
081 * </p>
082 * <pre>
083 *   &lt;module name=&quot;MagicNumber&quot;&gt;
084 *       &lt;property name=&quot;tokens&quot; value=&quot;NUM_DOUBLE, NUM_FLOAT&quot;/&gt;
085 *       &lt;property name=&quot;ignoreNumbers&quot; value=&quot;0, 0.5, 1&quot;/&gt;
086 *       &lt;property name=&quot;ignoreFieldDeclaration&quot; value=&quot;true&quot;/&gt;
087 *       &lt;property name=&quot;ignoreAnnotation&quot; value=&quot;true&quot;/&gt;
088 *   &lt;/module&gt;
089 * </pre>
090 * <p>
091 * results is following violations:
092 * </p>
093 * <pre>
094 * {@code
095 *   {@literal @}MyAnnotation(6) // no violation
096 *   class MyClass {
097 *       private field = 7; // no violation
098 *
099 *       void foo() {
100 *          int i = i + 1; // no violation
101 *          int j = j + (int)0.5; // no violation
102 *       }
103 *   }
104 * }
105 * </pre>
106 * <p>
107 * Config example of constantWaiverParentToken option:
108 * </p>
109 * <pre>
110 *   &lt;module name=&quot;MagicNumber&quot;&gt;
111 *       &lt;property name=&quot;constantWaiverParentToken&quot; value=&quot;ASSIGN,ARRAY_INIT,EXPR,
112 *       UNARY_PLUS, UNARY_MINUS, TYPECAST, ELIST, DIV, PLUS &quot;/&gt;
113 *   &lt;/module&gt;
114 * </pre>
115 * <p>
116 * result is following violation:
117 * </p>
118 * <pre>
119 * {@code
120 * class TestMethodCall {
121 *     public void method2() {
122 *         final TestMethodCall dummyObject = new TestMethodCall(62);    //violation
123 *         final int a = 3;        // ok as waiver is ASSIGN
124 *         final int [] b = {4, 5} // ok as waiver is ARRAY_INIT
125 *         final int c = -3;       // ok as waiver is UNARY_MINUS
126 *         final int d = +4;       // ok as waiver is UNARY_PLUS
127 *         final int e = method(1, 2) // ELIST is there but violation due to METHOD_CALL
128 *         final int x = 3 * 4;    // violation
129 *         final int y = 3 / 4;    // ok as waiver is DIV
130 *         final int z = 3 + 4;    // ok as waiver is PLUS
131 *         final int w = 3 - 4;    // violation
132 *         final int x = (int)(3.4);    //ok as waiver is TYPECAST
133 *     }
134 * }
135 * }
136 * </pre>
137 * @author Rick Giles
138 * @author Lars Kühne
139 * @author Daniel Solano Gómez
140 */
141public class MagicNumberCheck extends Check {
142
143    /**
144     * A key is pointing to the warning message text in "messages.properties"
145     * file.
146     */
147    public static final String MSG_KEY = "magic.number";
148
149    /**
150     * The token types that are allowed in the AST path from the
151     * number literal to the enclosing constant definition.
152     */
153    private int[] constantWaiverParentToken = {
154        TokenTypes.ASSIGN,
155        TokenTypes.ARRAY_INIT,
156        TokenTypes.EXPR,
157        TokenTypes.UNARY_PLUS,
158        TokenTypes.UNARY_MINUS,
159        TokenTypes.TYPECAST,
160        TokenTypes.ELIST,
161        TokenTypes.LITERAL_NEW,
162        TokenTypes.METHOD_CALL,
163        TokenTypes.STAR,
164        TokenTypes.DIV,
165        TokenTypes.PLUS,
166        TokenTypes.MINUS,
167    };
168
169    /** The numbers to ignore in the check, sorted. */
170    private double[] ignoreNumbers = {-1, 0, 1, 2};
171
172    /** Whether to ignore magic numbers in a hash code method. */
173    private boolean ignoreHashCodeMethod;
174
175    /** Whether to ignore magic numbers in annotation. */
176    private boolean ignoreAnnotation;
177
178    /** Whether to ignore magic numbers in field declaration. */
179    private boolean ignoreFieldDeclaration;
180
181    /**
182     * Constructor for MagicNumber Check.
183     * Sort the allowedTokensBetweenMagicNumberAndConstDef array for binary search.
184     */
185    public MagicNumberCheck() {
186        Arrays.sort(constantWaiverParentToken);
187    }
188
189    @Override
190    public int[] getDefaultTokens() {
191        return getAcceptableTokens();
192    }
193
194    @Override
195    public int[] getAcceptableTokens() {
196        return new int[] {
197            TokenTypes.NUM_DOUBLE,
198            TokenTypes.NUM_FLOAT,
199            TokenTypes.NUM_INT,
200            TokenTypes.NUM_LONG,
201        };
202    }
203
204    @Override
205    public int[] getRequiredTokens() {
206        return ArrayUtils.EMPTY_INT_ARRAY;
207    }
208
209    @Override
210    public void visitToken(DetailAST ast) {
211        if (ignoreAnnotation && isChildOf(ast, TokenTypes.ANNOTATION)) {
212            return;
213        }
214
215        if (isInIgnoreList(ast)
216            || ignoreHashCodeMethod && isInHashCodeMethod(ast)) {
217            return;
218        }
219
220        final DetailAST constantDefAST = findContainingConstantDef(ast);
221
222        if (constantDefAST == null) {
223            if (!(ignoreFieldDeclaration && isFieldDeclaration(ast))) {
224                reportMagicNumber(ast);
225            }
226        }
227        else {
228            final boolean found = isMagicNumberExists(ast, constantDefAST);
229            if (found) {
230                reportMagicNumber(ast);
231            }
232        }
233    }
234
235    /**
236     * Is magic number some where at ast tree.
237     * @param ast ast token
238     * @param constantDefAST constant ast
239     * @return true if magic number is present
240     */
241    private boolean isMagicNumberExists(DetailAST ast, DetailAST constantDefAST) {
242        boolean found = false;
243        DetailAST astNode = ast.getParent();
244        while (astNode != constantDefAST) {
245            final int type = astNode.getType();
246            if (Arrays.binarySearch(constantWaiverParentToken, type) < 0) {
247                found = true;
248                break;
249            }
250            astNode = astNode.getParent();
251        }
252        return found;
253    }
254
255    /**
256     * Finds the constant definition that contains aAST.
257     * @param ast the AST
258     * @return the constant def or null if ast is not contained in a constant definition.
259     */
260    private static DetailAST findContainingConstantDef(DetailAST ast) {
261        DetailAST varDefAST = ast;
262        while (varDefAST != null
263                && varDefAST.getType() != TokenTypes.VARIABLE_DEF
264                && varDefAST.getType() != TokenTypes.ENUM_CONSTANT_DEF) {
265            varDefAST = varDefAST.getParent();
266        }
267        DetailAST constantDef = null;
268
269        // no containing variable definition?
270        if (varDefAST != null) {
271            // implicit constant?
272            if (ScopeUtils.isInInterfaceOrAnnotationBlock(varDefAST)
273                    || varDefAST.getType() == TokenTypes.ENUM_CONSTANT_DEF) {
274                constantDef = varDefAST;
275            }
276            else {
277                // explicit constant
278                final DetailAST modifiersAST = varDefAST.findFirstToken(TokenTypes.MODIFIERS);
279
280                if (modifiersAST.branchContains(TokenTypes.FINAL)) {
281                    constantDef = varDefAST;
282                }
283            }
284        }
285        return constantDef;
286    }
287
288    /**
289     * Reports aAST as a magic number, includes unary operators as needed.
290     * @param ast the AST node that contains the number to report
291     */
292    private void reportMagicNumber(DetailAST ast) {
293        String text = ast.getText();
294        final DetailAST parent = ast.getParent();
295        DetailAST reportAST = ast;
296        if (parent.getType() == TokenTypes.UNARY_MINUS) {
297            reportAST = parent;
298            text = "-" + text;
299        }
300        else if (parent.getType() == TokenTypes.UNARY_PLUS) {
301            reportAST = parent;
302            text = "+" + text;
303        }
304        log(reportAST.getLineNo(),
305                reportAST.getColumnNo(),
306                MSG_KEY,
307                text);
308    }
309
310    /**
311     * Determines whether or not the given AST is in a valid hash code method.
312     * A valid hash code method is considered to be a method of the signature
313     * {@code public int hashCode()}.
314     *
315     * @param ast the AST from which to search for an enclosing hash code
316     *     method definition
317     *
318     * @return {@code true} if {@code ast} is in the scope of a valid hash code method.
319     */
320    private static boolean isInHashCodeMethod(DetailAST ast) {
321        boolean inHashCodeMethod = false;
322
323        // if not in a code block, can't be in hashCode()
324        if (ScopeUtils.isInCodeBlock(ast)) {
325            // find the method definition AST
326            DetailAST methodDefAST = ast.getParent();
327            while (methodDefAST != null
328                    && methodDefAST.getType() != TokenTypes.METHOD_DEF) {
329                methodDefAST = methodDefAST.getParent();
330            }
331
332            if (methodDefAST != null) {
333                // Check for 'hashCode' name.
334                final DetailAST identAST = methodDefAST.findFirstToken(TokenTypes.IDENT);
335
336                if ("hashCode".equals(identAST.getText())) {
337                    // Check for no arguments.
338                    final DetailAST paramAST = methodDefAST.findFirstToken(TokenTypes.PARAMETERS);
339                    // we are in a 'public int hashCode()' method! The compiler will ensure
340                    // the method returns an 'int' and is public.
341                    inHashCodeMethod = paramAST.getChildCount() == 0;
342                }
343            }
344        }
345        return inHashCodeMethod;
346    }
347
348    /**
349     * Decides whether the number of an AST is in the ignore list of this
350     * check.
351     * @param ast the AST to check
352     * @return true if the number of ast is in the ignore list of this check.
353     */
354    private boolean isInIgnoreList(DetailAST ast) {
355        double value = CheckUtils.parseDouble(ast.getText(), ast.getType());
356        final DetailAST parent = ast.getParent();
357        if (parent.getType() == TokenTypes.UNARY_MINUS) {
358            value = -1 * value;
359        }
360        return Arrays.binarySearch(ignoreNumbers, value) >= 0;
361    }
362
363    /**
364     * Determines whether or not the given AST is field declaration.
365     *
366     * @param ast AST from which to search for an enclosing field declaration
367     *
368     * @return {@code true} if {@code ast} is in the scope of field declaration
369     */
370    private static boolean isFieldDeclaration(DetailAST ast) {
371        DetailAST varDefAST = ast;
372        while (varDefAST != null
373                && varDefAST.getType() != TokenTypes.VARIABLE_DEF) {
374            varDefAST = varDefAST.getParent();
375        }
376
377        // contains variable declaration
378        // and it is directly inside class declaration
379        return varDefAST != null
380                && varDefAST.getParent().getParent().getType() == TokenTypes.CLASS_DEF;
381    }
382
383    /**
384     * Sets the tokens which are allowed between Magic Number and defined Object.
385     * @param tokens The string representation of the tokens interested in
386     */
387    public void setConstantWaiverParentToken(String... tokens) {
388        constantWaiverParentToken = new int[tokens.length];
389        for (int i = 0; i < tokens.length; i++) {
390            constantWaiverParentToken[i] = TokenUtils.getTokenId(tokens[i]);
391        }
392        Arrays.sort(constantWaiverParentToken);
393    }
394
395    /**
396     * Sets the numbers to ignore in the check.
397     * BeanUtils converts numeric token list to double array automatically.
398     * @param list list of numbers to ignore.
399     */
400    public void setIgnoreNumbers(double... list) {
401        if (list.length == 0) {
402            ignoreNumbers = ArrayUtils.EMPTY_DOUBLE_ARRAY;
403        }
404        else {
405            ignoreNumbers = new double[list.length];
406            System.arraycopy(list, 0, ignoreNumbers, 0, list.length);
407            Arrays.sort(ignoreNumbers);
408        }
409    }
410
411    /**
412     * Set whether to ignore hashCode methods.
413     * @param ignoreHashCodeMethod decide whether to ignore
414     *     hash code methods
415     */
416    public void setIgnoreHashCodeMethod(boolean ignoreHashCodeMethod) {
417        this.ignoreHashCodeMethod = ignoreHashCodeMethod;
418    }
419
420    /**
421     * Set whether to ignore Annotations.
422     * @param ignoreAnnotation decide whether to ignore annotations
423     */
424    public void setIgnoreAnnotation(boolean ignoreAnnotation) {
425        this.ignoreAnnotation = ignoreAnnotation;
426    }
427
428    /**
429     * Set whether to ignore magic numbers in field declaration.
430     * @param ignoreFieldDeclaration decide whether to ignore magic numbers
431     *     in field declaration
432     */
433    public void setIgnoreFieldDeclaration(boolean ignoreFieldDeclaration) {
434        this.ignoreFieldDeclaration = ignoreFieldDeclaration;
435    }
436
437    /**
438     * Determines if the given AST node has a parent node with given token type code.
439     *
440     * @param ast the AST from which to search for annotations
441     * @param type the type code of parent token
442     *
443     * @return {@code true} if the AST node has a parent with given token type.
444     */
445    private static boolean isChildOf(DetailAST ast, int type) {
446        boolean result = false;
447        DetailAST node = ast;
448        do {
449            if (node.getType() == type) {
450                result = true;
451            }
452            node = node.getParent();
453        } while (node != null && !result);
454
455        return result;
456    }
457}