001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2016 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.Collections;
023import java.util.Set;
024
025import com.google.common.collect.Sets;
026import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
027import com.puppycrawl.tools.checkstyle.api.DetailAST;
028import com.puppycrawl.tools.checkstyle.api.TokenTypes;
029
030/**
031 * Checks that any combination of String literals
032 * is on the left side of an equals() comparison.
033 * Also checks for String literals assigned to some field
034 * (such as <code>someString.equals(anotherString = "text")</code>).
035 *
036 * <p>Rationale: Calling the equals() method on String literals
037 * will avoid a potential NullPointerException.  Also, it is
038 * pretty common to see null check right before equals comparisons
039 * which is not necessary in the below example.
040 *
041 * <p>For example:
042 *
043 * <pre>
044 *  {@code
045 *    String nullString = null;
046 *    nullString.equals(&quot;My_Sweet_String&quot;);
047 *  }
048 * </pre>
049 * should be refactored to
050 *
051 * <pre>
052 *  {@code
053 *    String nullString = null;
054 *    &quot;My_Sweet_String&quot;.equals(nullString);
055 *  }
056 * </pre>
057 *
058 * @author Travis Schneeberger
059 * @author Vladislav Lisetskiy
060 */
061public class EqualsAvoidNullCheck extends AbstractCheck {
062
063    /**
064     * A key is pointing to the warning message text in "messages.properties"
065     * file.
066     */
067    public static final String MSG_EQUALS_AVOID_NULL = "equals.avoid.null";
068
069    /**
070     * A key is pointing to the warning message text in "messages.properties"
071     * file.
072     */
073    public static final String MSG_EQUALS_IGNORE_CASE_AVOID_NULL = "equalsIgnoreCase.avoid.null";
074
075    /** Method name for comparison. */
076    private static final String EQUALS = "equals";
077
078    /** Type name for comparison. */
079    private static final String STRING = "String";
080
081    /** Whether to process equalsIgnoreCase() invocations. */
082    private boolean ignoreEqualsIgnoreCase;
083
084    /** Stack of sets of field names, one for each class of a set of nested classes. */
085    private FieldFrame currentFrame;
086
087    @Override
088    public int[] getDefaultTokens() {
089        return getAcceptableTokens();
090    }
091
092    @Override
093    public int[] getAcceptableTokens() {
094        return new int[] {
095            TokenTypes.METHOD_CALL,
096            TokenTypes.CLASS_DEF,
097            TokenTypes.METHOD_DEF,
098            TokenTypes.LITERAL_IF,
099            TokenTypes.LITERAL_FOR,
100            TokenTypes.LITERAL_WHILE,
101            TokenTypes.LITERAL_DO,
102            TokenTypes.LITERAL_CATCH,
103            TokenTypes.LITERAL_TRY,
104            TokenTypes.VARIABLE_DEF,
105            TokenTypes.PARAMETER_DEF,
106            TokenTypes.CTOR_DEF,
107            TokenTypes.SLIST,
108            TokenTypes.ENUM_DEF,
109            TokenTypes.ENUM_CONSTANT_DEF,
110            TokenTypes.LITERAL_NEW,
111        };
112    }
113
114    @Override
115    public int[] getRequiredTokens() {
116        return getAcceptableTokens();
117    }
118
119    /**
120     * Whether to ignore checking {@code String.equalsIgnoreCase(String)}.
121     * @param newValue whether to ignore checking
122     *    {@code String.equalsIgnoreCase(String)}.
123     */
124    public void setIgnoreEqualsIgnoreCase(boolean newValue) {
125        ignoreEqualsIgnoreCase = newValue;
126    }
127
128    @Override
129    public void beginTree(DetailAST rootAST) {
130        currentFrame = new FieldFrame(null);
131    }
132
133    @Override
134    public void visitToken(final DetailAST ast) {
135        switch (ast.getType()) {
136            case TokenTypes.VARIABLE_DEF:
137            case TokenTypes.PARAMETER_DEF:
138                currentFrame.addField(ast);
139                break;
140            case TokenTypes.METHOD_CALL:
141                processMethodCall(ast);
142                break;
143            case TokenTypes.SLIST:
144                processSlist(ast);
145                break;
146            case TokenTypes.LITERAL_NEW:
147                processLiteralNew(ast);
148                break;
149            default:
150                processFrame(ast);
151        }
152    }
153
154    @Override
155    public void leaveToken(DetailAST ast) {
156        final int astType = ast.getType();
157        if (astType != TokenTypes.VARIABLE_DEF
158                && astType != TokenTypes.PARAMETER_DEF
159                && astType != TokenTypes.METHOD_CALL
160                && astType != TokenTypes.SLIST
161                && astType != TokenTypes.LITERAL_NEW
162                || astType == TokenTypes.LITERAL_NEW
163                    && ast.branchContains(TokenTypes.LCURLY)) {
164            currentFrame = currentFrame.getParent();
165        }
166        else if (astType == TokenTypes.SLIST) {
167            leaveSlist(ast);
168        }
169    }
170
171    @Override
172    public void finishTree(DetailAST ast) {
173        traverseFieldFrameTree(currentFrame);
174    }
175
176    /**
177     * Determine whether SLIST begins static or non-static block and add it as
178     * a frame in this case.
179     * @param ast SLIST ast.
180     */
181    private void processSlist(DetailAST ast) {
182        final int parentType = ast.getParent().getType();
183        if (parentType == TokenTypes.SLIST
184                || parentType == TokenTypes.STATIC_INIT
185                || parentType == TokenTypes.INSTANCE_INIT) {
186            final FieldFrame frame = new FieldFrame(currentFrame);
187            currentFrame.addChild(frame);
188            currentFrame = frame;
189        }
190    }
191
192    /**
193     * Determine whether SLIST begins static or non-static block and
194     * @param ast SLIST ast.
195     */
196    private void leaveSlist(DetailAST ast) {
197        final int parentType = ast.getParent().getType();
198        if (parentType == TokenTypes.SLIST
199                || parentType == TokenTypes.STATIC_INIT
200                || parentType == TokenTypes.INSTANCE_INIT) {
201            currentFrame = currentFrame.getParent();
202        }
203    }
204
205    /**
206     * Process CLASS_DEF, METHOD_DEF, LITERAL_IF, LITERAL_FOR, LITERAL_WHILE, LITERAL_DO,
207     * LITERAL_CATCH, LITERAL_TRY, CTOR_DEF, ENUM_DEF, ENUM_CONSTANT_DEF.
208     * @param ast processed ast.
209     */
210    private void processFrame(DetailAST ast) {
211        final FieldFrame frame = new FieldFrame(currentFrame);
212        final int astType = ast.getType();
213        if (astType == TokenTypes.CLASS_DEF
214                || astType == TokenTypes.ENUM_DEF
215                || astType == TokenTypes.ENUM_CONSTANT_DEF) {
216            frame.setClassOrEnumOrEnumConstDef(true);
217            frame.setFrameName(ast.findFirstToken(TokenTypes.IDENT).getText());
218        }
219        currentFrame.addChild(frame);
220        currentFrame = frame;
221    }
222
223    /**
224     * Add the method call to the current frame if it should be processed.
225     * @param methodCall METHOD_CALL ast.
226     */
227    private void processMethodCall(DetailAST methodCall) {
228        final DetailAST dot = methodCall.getFirstChild();
229        if (dot.getType() == TokenTypes.DOT) {
230            final String methodName = dot.getLastChild().getText();
231            if (EQUALS.equals(methodName)
232                    || !ignoreEqualsIgnoreCase && "equalsIgnoreCase".equals(methodName)) {
233                currentFrame.addMethodCall(methodCall);
234            }
235        }
236    }
237
238    /**
239     * Determine whether LITERAL_NEW is an anonymous class definition and add it as
240     * a frame in this case.
241     * @param ast LITERAL_NEW ast.
242     */
243    private void processLiteralNew(DetailAST ast) {
244        if (ast.branchContains(TokenTypes.LCURLY)) {
245            final FieldFrame frame = new FieldFrame(currentFrame);
246            currentFrame.addChild(frame);
247            currentFrame = frame;
248        }
249    }
250
251    /**
252     * Traverse the tree of the field frames to check all equals method calls.
253     * @param frame to check method calls in.
254     */
255    private void traverseFieldFrameTree(FieldFrame frame) {
256        for (FieldFrame child: frame.getChildren()) {
257            if (!child.getChildren().isEmpty()) {
258                traverseFieldFrameTree(child);
259            }
260            currentFrame = child;
261            for (DetailAST methodCall: child.getMethodCalls()) {
262                checkMethodCall(methodCall);
263            }
264        }
265    }
266
267    /**
268     * Check whether the method call should be violated.
269     * @param methodCall method call to check.
270     */
271    private void checkMethodCall(DetailAST methodCall) {
272        DetailAST objCalledOn = methodCall.getFirstChild().getFirstChild();
273        if (objCalledOn.getType() == TokenTypes.DOT) {
274            objCalledOn = objCalledOn.getLastChild();
275        }
276        final DetailAST expr = methodCall.findFirstToken(TokenTypes.ELIST).getFirstChild();
277        if (isObjectValid(objCalledOn)
278                && containsOneArgument(methodCall)
279                && containsAllSafeTokens(expr)
280                && isCalledOnStringFieldOrVariable(objCalledOn)) {
281            final String methodName = methodCall.getFirstChild().getLastChild().getText();
282            if (EQUALS.equals(methodName)) {
283                log(methodCall.getLineNo(), methodCall.getColumnNo(),
284                    MSG_EQUALS_AVOID_NULL);
285            }
286            else {
287                log(methodCall.getLineNo(), methodCall.getColumnNo(),
288                    MSG_EQUALS_IGNORE_CASE_AVOID_NULL);
289            }
290        }
291    }
292
293    /**
294     * Check whether the object equals method is called on is not a String literal
295     * and not too complex.
296     * @param objCalledOn the object equals method is called on ast.
297     * @return true if the object is valid.
298     */
299    private static boolean isObjectValid(DetailAST objCalledOn) {
300        boolean result = true;
301        final DetailAST previousSibling = objCalledOn.getPreviousSibling();
302        if (previousSibling != null
303                && previousSibling.getType() == TokenTypes.DOT) {
304            result = false;
305        }
306        if (isStringLiteral(objCalledOn)) {
307            result = false;
308        }
309        return result;
310    }
311
312    /**
313     * Checks for calling equals on String literal and
314     * anon object which cannot be null.
315     * @param objCalledOn object AST
316     * @return if it is string literal
317     */
318    private static boolean isStringLiteral(DetailAST objCalledOn) {
319        return objCalledOn.getType() == TokenTypes.STRING_LITERAL
320                || objCalledOn.getType() == TokenTypes.LITERAL_NEW;
321    }
322
323    /**
324     * Verify that method call has one argument.
325     *
326     * @param methodCall METHOD_CALL DetailAST
327     * @return true if method call has one argument.
328     */
329    private static boolean containsOneArgument(DetailAST methodCall) {
330        final DetailAST elist = methodCall.findFirstToken(TokenTypes.ELIST);
331        return elist.getChildCount() == 1;
332    }
333
334    /**
335     * Looks for all "safe" Token combinations in the argument
336     * expression branch.
337     * @param expr the argument expression
338     * @return - true if any child matches the set of tokens, false if not
339     */
340    private boolean containsAllSafeTokens(final DetailAST expr) {
341        DetailAST arg = expr.getFirstChild();
342        arg = skipVariableAssign(arg);
343
344        boolean argIsNotNull = false;
345        if (arg.getType() == TokenTypes.PLUS) {
346            DetailAST child = arg.getFirstChild();
347            while (child != null
348                    && !argIsNotNull) {
349                argIsNotNull = child.getType() == TokenTypes.STRING_LITERAL
350                        || child.getType() == TokenTypes.IDENT;
351                child = child.getNextSibling();
352            }
353        }
354
355        return argIsNotNull
356                || !arg.branchContains(TokenTypes.IDENT)
357                    && !arg.branchContains(TokenTypes.LITERAL_NULL);
358    }
359
360    /**
361     * Skips over an inner assign portion of an argument expression.
362     * @param currentAST current token in the argument expression
363     * @return the next relevant token
364     */
365    private static DetailAST skipVariableAssign(final DetailAST currentAST) {
366        if (currentAST.getType() == TokenTypes.ASSIGN
367                && currentAST.getFirstChild().getType() == TokenTypes.IDENT) {
368            return currentAST.getFirstChild().getNextSibling();
369        }
370        return currentAST;
371    }
372
373    /**
374     * Determine, whether equals method is called on a field of String type.
375     * @param objCalledOn object ast.
376     * @return true if the object is of String type.
377     */
378    private boolean isCalledOnStringFieldOrVariable(DetailAST objCalledOn) {
379        final boolean result;
380        final DetailAST previousSiblingAst = objCalledOn.getPreviousSibling();
381        if (previousSiblingAst == null) {
382            result = isStringFieldOrVariable(objCalledOn);
383        }
384        else {
385            if (previousSiblingAst.getType() == TokenTypes.LITERAL_THIS) {
386                result = isStringFieldOrVariableFromThisInstance(objCalledOn);
387            }
388            else {
389                final String className = previousSiblingAst.getText();
390                result = isStringFieldOrVariableFromClass(objCalledOn, className);
391            }
392        }
393        return result;
394    }
395
396    /**
397     * Whether the field or the variable is of String type.
398     * @param objCalledOn the field or the variable to check.
399     * @return true if the field or the variable is of String type.
400     */
401    private boolean isStringFieldOrVariable(DetailAST objCalledOn) {
402        boolean result = false;
403        final String name = objCalledOn.getText();
404        FieldFrame frame = currentFrame;
405        while (frame != null) {
406            final DetailAST field = frame.findField(name);
407            if (field != null
408                    && (frame.isClassOrEnumOrEnumConstDef()
409                            || checkLineNo(field, objCalledOn))) {
410                result = STRING.equals(getFieldType(field));
411                break;
412            }
413            frame = frame.getParent();
414        }
415        return result;
416    }
417
418    /**
419     * Whether the field or the variable from THIS instance is of String type.
420     * @param objCalledOn the field or the variable from THIS instance to check.
421     * @return true if the field or the variable from THIS instance is of String type.
422     */
423    private boolean isStringFieldOrVariableFromThisInstance(DetailAST objCalledOn) {
424        boolean result = false;
425        final String name = objCalledOn.getText();
426        final DetailAST field = getObjectFrame(currentFrame).findField(name);
427        if (field != null) {
428            result = STRING.equals(getFieldType(field));
429        }
430        return result;
431    }
432
433    /**
434     * Whether the field or the variable from the specified class is of String type.
435     * @param objCalledOn the field or the variable from the specified class to check.
436     * @param className the name of the class to check in.
437     * @return true if the field or the variable from the specified class is of String type.
438     */
439    private boolean isStringFieldOrVariableFromClass(DetailAST objCalledOn,
440            final String className) {
441        boolean result = false;
442        final String name = objCalledOn.getText();
443        FieldFrame frame = getObjectFrame(currentFrame);
444        while (frame != null) {
445            if (className.equals(frame.getFrameName())) {
446                final DetailAST field = frame.findField(name);
447                if (field != null) {
448                    result = STRING.equals(getFieldType(field));
449                }
450                break;
451            }
452            frame = getObjectFrame(frame.getParent());
453        }
454        return result;
455    }
456
457    /**
458     * Get the nearest parent frame which is CLASS_DEF, ENUM_DEF or ENUM_CONST_DEF.
459     * @param frame to start the search from.
460     * @return the nearest parent frame which is CLASS_DEF, ENUM_DEF or ENUM_CONST_DEF.
461     */
462    private static FieldFrame getObjectFrame(FieldFrame frame) {
463        FieldFrame objectFrame = frame;
464        while (objectFrame != null && !objectFrame.isClassOrEnumOrEnumConstDef()) {
465            objectFrame = objectFrame.getParent();
466        }
467        return objectFrame;
468    }
469
470    /**
471     * Check whether the field is declared before the method call in case of
472     * methods and initialization blocks.
473     * @param field field to check.
474     * @param objCalledOn object equals method called on.
475     * @return true if the field is declared before the method call.
476     */
477    private static boolean checkLineNo(DetailAST field, DetailAST objCalledOn) {
478        boolean result = false;
479        if (field.getLineNo() < objCalledOn.getLineNo()
480                || field.getLineNo() == objCalledOn.getLineNo()
481                    && field.getColumnNo() < objCalledOn.getColumnNo()) {
482            result = true;
483        }
484        return result;
485    }
486
487    /**
488     * Get field type.
489     * @param field to get the type from.
490     * @return type of the field.
491     */
492    private static String getFieldType(DetailAST field) {
493        String fieldType = null;
494        final DetailAST identAst = field.findFirstToken(TokenTypes.TYPE)
495                .findFirstToken(TokenTypes.IDENT);
496        if (identAst != null) {
497            fieldType = identAst.getText();
498        }
499        return fieldType;
500    }
501
502    /**
503     * Holds the names of fields of a type.
504     */
505    private static class FieldFrame {
506        /** Parent frame. */
507        private final FieldFrame parent;
508
509        /** Set of frame's children. */
510        private final Set<FieldFrame> children = Sets.newHashSet();
511
512        /** Set of fields. */
513        private final Set<DetailAST> fields = Sets.newHashSet();
514
515        /** Set of equals calls. */
516        private final Set<DetailAST> methodCalls = Sets.newHashSet();
517
518        /** Name of the class, enum or enum constant declaration. */
519        private String frameName;
520
521        /** Whether the frame is CLASS_DEF, ENUM_DEF or ENUM_CONST_DEF. */
522        private boolean classOrEnumOrEnumConstDef;
523
524        /**
525         * Creates new frame.
526         * @param parent parent frame.
527         */
528        FieldFrame(FieldFrame parent) {
529            this.parent = parent;
530        }
531
532        /**
533         * Set the frame name.
534         * @param frameName value to set.
535         */
536        public void setFrameName(String frameName) {
537            this.frameName = frameName;
538        }
539
540        /**
541         * Getter for the frame name.
542         * @return frame name.
543         */
544        public String getFrameName() {
545            return frameName;
546        }
547
548        /**
549         * Getter for the parent frame.
550         * @return parent frame.
551         */
552        public FieldFrame getParent() {
553            return parent;
554        }
555
556        /**
557         * Getter for frame's children.
558         * @return children of this frame.
559         */
560        public Set<FieldFrame> getChildren() {
561            return Collections.unmodifiableSet(children);
562        }
563
564        /**
565         * Add child frame to this frame.
566         * @param child frame to add.
567         */
568        public void addChild(FieldFrame child) {
569            children.add(child);
570        }
571
572        /**
573         * Add field to this FieldFrame.
574         * @param field the ast of the field.
575         */
576        public void addField(DetailAST field) {
577            fields.add(field);
578        }
579
580        /**
581         * Sets isClassOrEnum.
582         * @param value value to set.
583         */
584        public void setClassOrEnumOrEnumConstDef(boolean value) {
585            classOrEnumOrEnumConstDef = value;
586        }
587
588        /**
589         * Getter for classOrEnumOrEnumConstDef.
590         * @return classOrEnumOrEnumConstDef.
591         */
592        public boolean isClassOrEnumOrEnumConstDef() {
593            return classOrEnumOrEnumConstDef;
594        }
595
596        /**
597         * Add method call to this frame.
598         * @param methodCall METHOD_CALL ast.
599         */
600        public void addMethodCall(DetailAST methodCall) {
601            methodCalls.add(methodCall);
602        }
603
604        /**
605         * Determines whether this FieldFrame contains the field.
606         * @param name name of the field to check.
607         * @return true if this FieldFrame contains instance field field.
608         */
609        public DetailAST findField(String name) {
610            for (DetailAST field: fields) {
611                if (getFieldName(field).equals(name)) {
612                    return field;
613                }
614            }
615            return null;
616        }
617
618        /**
619         * Getter for frame's method calls.
620         * @return method calls of this frame.
621         */
622        public Set<DetailAST> getMethodCalls() {
623            return Collections.unmodifiableSet(methodCalls);
624        }
625
626        /**
627         * Get the name of the field.
628         * @param field to get the name from.
629         * @return name of the field.
630         */
631        private static String getFieldName(DetailAST field) {
632            return field.findFirstToken(TokenTypes.IDENT).getText();
633        }
634    }
635}