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