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.design;
021
022import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
023import com.puppycrawl.tools.checkstyle.api.DetailAST;
024import com.puppycrawl.tools.checkstyle.api.Scope;
025import com.puppycrawl.tools.checkstyle.api.TokenTypes;
026import com.puppycrawl.tools.checkstyle.utils.ScopeUtils;
027
028/**
029 * Checks find classes that are designed for inheritance.
030 *
031 * <p>
032 * Nothing wrong could be with founded classes
033 * this Check make sence only for library project (not a application projects)
034 * who care about ideal OOP design to make sure clas work in all cases even misusage.
035 * Even in library projects this Check most likely find classes that are not required to check.
036 * User need to use suppressions extensively to got a benefit from this Check and avoid
037 * false positives.
038 * </p>
039 *
040 * <p>
041 * ATTENTION: Only user can deside whether class is designed for extension or not.
042 * Check just show all possible. If smth inappropriate is found please use supporession.
043 * </p>
044 *
045 * <p>
046 * More specifically, it enforces a programming style
047 * where superclasses provide empty "hooks" that can be
048 * implemented by subclasses.
049 * </p>
050 *
051 * <p>The exact rule is that non-private, non-static methods in
052 * non-final classes (or classes that do not
053 * only have private constructors) must either be
054 * <ul>
055 * <li>abstract or</li>
056 * <li>final or</li>
057 * <li>have an empty implementation</li>
058 * </ul>
059 *
060 *
061 * <p>
062 * This protects superclasses against being broken by
063 * subclasses. The downside is that subclasses are limited
064 * in their flexibility, in particular they cannot prevent
065 * execution of code in the superclass, but that also
066 * means that subclasses can't forget to call their super
067 * method.
068 * </p>
069 *
070 * @author lkuehne
071 */
072public class DesignForExtensionCheck extends AbstractCheck {
073
074    /**
075     * A key is pointing to the warning message text in "messages.properties"
076     * file.
077     */
078    public static final String MSG_KEY = "design.forExtension";
079
080    @Override
081    public int[] getDefaultTokens() {
082        return getAcceptableTokens();
083    }
084
085    @Override
086    public int[] getAcceptableTokens() {
087        return new int[] {TokenTypes.METHOD_DEF};
088    }
089
090    @Override
091    public int[] getRequiredTokens() {
092        return getAcceptableTokens();
093    }
094
095    @Override
096    public void visitToken(DetailAST ast) {
097        // nothing to do for Interfaces
098        if (!ScopeUtils.isInInterfaceOrAnnotationBlock(ast)
099                && !isPrivateOrFinalOrAbstract(ast)
100                && ScopeUtils.getSurroundingScope(ast).isIn(Scope.PROTECTED)) {
101
102            // method is ok if it is implementation can verified to be empty
103            // Note: native methods don't have impl in java code, so
104            // implementation can be null even if method not abstract
105            final DetailAST implementation = ast.findFirstToken(TokenTypes.SLIST);
106            final boolean nonEmptyImplementation = implementation == null
107                    || implementation.getFirstChild().getType() != TokenTypes.RCURLY;
108
109            final DetailAST classDef = findContainingClass(ast);
110            final DetailAST classMods = classDef.findFirstToken(TokenTypes.MODIFIERS);
111            // check if the containing class can be subclassed
112            final boolean classCanBeSubclassed = classDef.getType() != TokenTypes.ENUM_DEF
113                    && !classMods.branchContains(TokenTypes.FINAL);
114
115            if (nonEmptyImplementation && classCanBeSubclassed
116                    && hasDefaultOrExplicitNonPrivateCtor(classDef)) {
117
118                final String name = ast.findFirstToken(TokenTypes.IDENT).getText();
119                log(ast.getLineNo(), ast.getColumnNo(), MSG_KEY, name);
120            }
121        }
122    }
123
124    /**
125     * Check for modifiers.
126     * @param ast modifier ast
127     * @return tru in modifier is in checked ones
128     */
129    private static boolean isPrivateOrFinalOrAbstract(DetailAST ast) {
130        // method is ok if it is private or abstract or final
131        final DetailAST modifiers = ast.findFirstToken(TokenTypes.MODIFIERS);
132        return modifiers.branchContains(TokenTypes.LITERAL_PRIVATE)
133                || modifiers.branchContains(TokenTypes.ABSTRACT)
134                || modifiers.branchContains(TokenTypes.FINAL)
135                || modifiers.branchContains(TokenTypes.LITERAL_STATIC);
136    }
137
138    /**
139     * Has Default Or Explicit Non Private Ctor.
140     * @param classDef class ast
141     * @return true if Check should make a violation
142     */
143    private static boolean hasDefaultOrExplicitNonPrivateCtor(DetailAST classDef) {
144        // check if subclassing is prevented by having only private ctors
145        final DetailAST objBlock = classDef.findFirstToken(TokenTypes.OBJBLOCK);
146
147        boolean hasDefaultConstructor = true;
148        boolean hasExplicitNonPrivateCtor = false;
149
150        DetailAST candidate = objBlock.getFirstChild();
151
152        while (candidate != null) {
153            if (candidate.getType() == TokenTypes.CTOR_DEF) {
154                hasDefaultConstructor = false;
155
156                final DetailAST ctorMods =
157                        candidate.findFirstToken(TokenTypes.MODIFIERS);
158                if (!ctorMods.branchContains(TokenTypes.LITERAL_PRIVATE)) {
159                    hasExplicitNonPrivateCtor = true;
160                    break;
161                }
162            }
163            candidate = candidate.getNextSibling();
164        }
165
166        return hasDefaultConstructor || hasExplicitNonPrivateCtor;
167    }
168
169    /**
170     * Searches the tree towards the root until it finds a CLASS_DEF node.
171     * @param ast the start node for searching
172     * @return the CLASS_DEF node.
173     */
174    private static DetailAST findContainingClass(DetailAST ast) {
175        DetailAST searchAST = ast;
176        while (searchAST.getType() != TokenTypes.CLASS_DEF
177               && searchAST.getType() != TokenTypes.ENUM_DEF) {
178            searchAST = searchAST.getParent();
179        }
180        return searchAST;
181    }
182}