Java tutorial
//////////////////////////////////////////////////////////////////////////////// // checkstyle: Checks Java source code for adherence to a set of rules. // Copyright (C) 2001-2014 Oliver Burn // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Lesser General Public // License as published by the Free Software Foundation; either // version 2.1 of the License, or (at your option) any later version. // // This library is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU // Lesser General Public License for more details. // // You should have received a copy of the GNU Lesser General Public // License along with this library; if not, write to the Free Software // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA //////////////////////////////////////////////////////////////////////////////// package com.puppycrawl.tools.checkstyle.checks.coding; import com.google.common.base.Objects; import com.google.common.collect.Sets; import com.puppycrawl.tools.checkstyle.api.Check; import com.puppycrawl.tools.checkstyle.api.DetailAST; import com.puppycrawl.tools.checkstyle.api.ScopeUtils; import com.puppycrawl.tools.checkstyle.api.TokenTypes; import com.puppycrawl.tools.checkstyle.api.Utils; import java.util.Set; import java.util.regex.Pattern; import java.util.regex.PatternSyntaxException; import org.apache.commons.beanutils.ConversionException; /** * <p>Checks that a local variable or a parameter does not shadow * a field that is defined in the same class. * <p> * An example of how to configure the check is: * <pre> * <module name="HiddenField"/> * </pre> * <p> * An example of how to configure the check so that it checks variables but not * parameters is: * <pre> * <module name="HiddenField"> * <property name="tokens" value="VARIABLE_DEF"/> * </module> * </pre> * <p> * An example of how to configure the check so that it ignores the parameter of * a setter method is: * <pre> * <module name="HiddenField"> * <property name="ignoreSetter" value="true"/> * </module> * </pre> * <p> * A method is recognized as a setter if it is in the following form * <pre> * ${returnType} set${Name}(${anyType} ${name}) { ... } * </pre> * where ${anyType} is any primitive type, class or interface name; * ${name} is name of the variable that is being set and ${Name} its * capitalized form that appears in the method name. By default it is expected * that setter returns void, i.e. ${returnType} is 'void'. For example * <pre> * void setTime(long time) { ... } * </pre> * Any other return types will not let method match a setter pattern. However, * by setting <em>setterCanReturnItsClass</em> property to <em>true</em> * definition of a setter is expanded, so that setter return type can also be * a class in which setter is declared. For example * <pre> * class PageBuilder { * PageBuilder setName(String name) { ... } * } * </pre> * Such methods are known as chain-setters and a common when Builder-pattern * is used. Property <em>setterCanReturnItsClass</em> has effect only if * <em>ignoreSetter</em> is set to true. * <p> * An example of how to configure the check so that it ignores the parameter * of either a setter that returns void or a chain-setter. * <pre> * <module name="HiddenField"> * <property name="ignoreSetter" value="true"/> * <property name="setterCanReturnItsClass" value="true"/> * </module> * </pre> * <p> * An example of how to configure the check so that it ignores constructor * parameters is: * <pre> * <module name="HiddenField"> * <property name="ignoreConstructorParameter" value="true"/> * </module> * </pre> * @author Dmitri Priimak */ public class HiddenFieldCheck extends Check { /** stack of sets of field names, * one for each class of a set of nested classes. */ private FieldFrame currentFrame; /** the regexp to match against */ private Pattern regexp; /** controls whether to check the pnameter of a property setter method */ private boolean ignoreSetter; /** * if ignoreSetter is set to true then this variable controls what * the setter method can return By default setter must return void. * However, is this variable is set to true then setter can also * return class in which is declared. */ private boolean setterCanReturnItsClass; /** controls whether to check the parameter of a constructor */ private boolean ignoreConstructorParameter; /** controls whether to check the parameter of abstract methods. */ private boolean ignoreAbstractMethods; @Override public int[] getDefaultTokens() { return new int[] { TokenTypes.VARIABLE_DEF, TokenTypes.PARAMETER_DEF, TokenTypes.CLASS_DEF, TokenTypes.ENUM_DEF, TokenTypes.ENUM_CONSTANT_DEF, }; } @Override public int[] getAcceptableTokens() { return new int[] { TokenTypes.VARIABLE_DEF, TokenTypes.PARAMETER_DEF, }; } @Override public int[] getRequiredTokens() { return new int[] { TokenTypes.CLASS_DEF, TokenTypes.ENUM_DEF, TokenTypes.ENUM_CONSTANT_DEF, }; } @Override public void beginTree(DetailAST rootAST) { currentFrame = new FieldFrame(null, true, null, null); } @Override public void visitToken(DetailAST ast) { final int type = ast.getType(); switch (type) { case TokenTypes.VARIABLE_DEF: case TokenTypes.PARAMETER_DEF: processVariable(ast); break; default: visitOtherTokens(ast, type); } } /** * Called to process tokens other than {@link TokenTypes.VARIABLE_DEF} * and {@link TokenTypes.PARAMETER_DEF} * * @param ast token to process * @param type type of the token */ private void visitOtherTokens(DetailAST ast, int type) { //A more thorough check of enum constant class bodies is //possible (checking for hidden fields against the enum //class body in addition to enum constant class bodies) //but not attempted as it seems out of the scope of this //check. final DetailAST typeMods = ast.findFirstToken(TokenTypes.MODIFIERS); final boolean isStaticInnerType = (typeMods != null) && typeMods.branchContains(TokenTypes.LITERAL_STATIC); final FieldFrame frame = new FieldFrame(currentFrame, isStaticInnerType, type, (type == TokenTypes.CLASS_DEF || type == TokenTypes.ENUM_DEF) ? ast.findFirstToken(TokenTypes.IDENT).getText() : null); //add fields to container final DetailAST objBlock = ast.findFirstToken(TokenTypes.OBJBLOCK); // enum constants may not have bodies if (objBlock != null) { DetailAST child = objBlock.getFirstChild(); while (child != null) { if (child.getType() == TokenTypes.VARIABLE_DEF) { final String name = child.findFirstToken(TokenTypes.IDENT).getText(); final DetailAST mods = child.findFirstToken(TokenTypes.MODIFIERS); if (mods.branchContains(TokenTypes.LITERAL_STATIC)) { frame.addStaticField(name); } else { frame.addInstanceField(name); } } child = child.getNextSibling(); } } // push container currentFrame = frame; } @Override public void leaveToken(DetailAST ast) { if ((ast.getType() == TokenTypes.CLASS_DEF) || (ast.getType() == TokenTypes.ENUM_DEF) || (ast.getType() == TokenTypes.ENUM_CONSTANT_DEF)) { //pop currentFrame = currentFrame.getParent(); } } /** * Process a variable token. * Check whether a local variable or parameter shadows a field. * Store a field for later comparison with local variables and parameters. * @param ast the variable token. */ private void processVariable(DetailAST ast) { if (!ScopeUtils.inInterfaceOrAnnotationBlock(ast) && (ScopeUtils.isLocalVariableDef(ast) || (ast.getType() == TokenTypes.PARAMETER_DEF))) { // local variable or parameter. Does it shadow a field? final DetailAST nameAST = ast.findFirstToken(TokenTypes.IDENT); final String name = nameAST.getText(); if ((currentFrame.containsStaticField(name) || (!inStatic(ast) && currentFrame.containsInstanceField(name))) && ((regexp == null) || (!getRegexp().matcher(name).find())) && !isIgnoredSetterParam(ast, name) && !isIgnoredConstructorParam(ast) && !isIgnoredParamOfAbstractMethod(ast)) { log(nameAST, "hidden.field", name); } } } /** * Determines whether an AST node is in a static method or static * initializer. * @param ast the node to check. * @return true if ast is in a static method or a static block; */ private static boolean inStatic(DetailAST ast) { DetailAST parent = ast.getParent(); while (parent != null) { switch (parent.getType()) { case TokenTypes.STATIC_INIT: return true; case TokenTypes.METHOD_DEF: final DetailAST mods = parent.findFirstToken(TokenTypes.MODIFIERS); return mods.branchContains(TokenTypes.LITERAL_STATIC); default: parent = parent.getParent(); } } return false; } /** * Decides whether to ignore an AST node that is the parameter of a * setter method, where the property setter method for field 'xyz' has * name 'setXyz', one parameter named 'xyz', and return type void * (default behavior) or return type is name of the class in which * such method is declared (allowed only if * {@link #setSetterCanReturnItsClass(boolean)} is called with * value <em>true</em>) * * @param ast the AST to check. * @param name the name of ast. * @return true if ast should be ignored because check property * ignoreSetter is true and ast is the parameter of a setter method. */ private boolean isIgnoredSetterParam(DetailAST ast, String name) { if (ast.getType() == TokenTypes.PARAMETER_DEF && ignoreSetter) { final DetailAST parametersAST = ast.getParent(); final DetailAST methodAST = parametersAST.getParent(); if (parametersAST.getChildCount() == 1 && methodAST.getType() == TokenTypes.METHOD_DEF && isSetterMethod(methodAST, name)) { return true; } } return false; } /** * Determine if a specific method identified by methodAST and a single * variable name aName is a setter. This recognition partially depends * on mSetterCanReturnItsClass property. * * @param aMethodAST AST corresponding to a method call * @param aName name of single parameter of this method. * @return true of false indicating of method is a setter or not. */ private boolean isSetterMethod(DetailAST aMethodAST, String aName) { final String methodName = aMethodAST.findFirstToken(TokenTypes.IDENT).getText(); boolean isSetterMethod = false; if (methodName.equals("set" + capitalize(aName))) { // method name did match set${Name}(${anyType} ${aName}) // where ${Name} is capitalized version of ${aName} // therefore this method is potentially a setter final DetailAST typeAST = aMethodAST.findFirstToken(TokenTypes.TYPE); final String returnType = typeAST.getFirstChild().getText(); if (typeAST.branchContains(TokenTypes.LITERAL_VOID) || (setterCanReturnItsClass && currentFrame.embeddedIn(returnType))) { // this method has signature // // void set${Name}(${anyType} ${name}) // // and therefore considered to be a setter // // or // // return type is not void, but it is the same as the class // where method is declared and and mSetterCanReturnItsClass // is set to true isSetterMethod = true; } } return isSetterMethod; } /** * Capitalizes a given property name the way we expect to see it in * a setter name. * @param name a property name * @return capitalized property name */ private static String capitalize(final String name) { String setterName = name; // we should not capitalize the first character if the second // one is a capital one, since according to JavBeans spec // setXYzz() is a setter for XYzz property, not for xYzz one. if (name != null && name.length() > 0 && (name.length() > 1 && !Character.isUpperCase(name.charAt(1)))) { setterName = name.substring(0, 1).toUpperCase() + name.substring(1); } return setterName; } /** * Decides whether to ignore an AST node that is the parameter of a * constructor. * @param ast the AST to check. * @return true if ast should be ignored because check property * ignoreConstructorParameter is true and ast is a constructor parameter. */ private boolean isIgnoredConstructorParam(DetailAST ast) { boolean result = false; if ((ast.getType() == TokenTypes.PARAMETER_DEF) && ignoreConstructorParameter) { final DetailAST parametersAST = ast.getParent(); final DetailAST constructorAST = parametersAST.getParent(); result = (constructorAST.getType() == TokenTypes.CTOR_DEF); } return result; } /** * Decides whether to ignore an AST node that is the parameter of an * abstract method. * @param ast the AST to check. * @return true if ast should be ignored because check property * ignoreAbstactMethods is true and ast is a parameter of abstract * methods. */ private boolean isIgnoredParamOfAbstractMethod(DetailAST ast) { boolean result = false; if ((ast.getType() == TokenTypes.PARAMETER_DEF) && ignoreAbstractMethods) { final DetailAST method = ast.getParent().getParent(); if (method.getType() == TokenTypes.METHOD_DEF) { final DetailAST mods = method.findFirstToken(TokenTypes.MODIFIERS); result = ((mods != null) && mods.branchContains(TokenTypes.ABSTRACT)); } } return result; } /** * Set the ignore format to the specified regular expression. * @param format a <code>String</code> value * @throws ConversionException unable to parse format */ public void setIgnoreFormat(String format) throws ConversionException { try { regexp = Utils.getPattern(format); } catch (final PatternSyntaxException e) { throw new ConversionException("unable to parse " + format, e); } } /** * Set whether to ignore the parameter of a property setter method. * @param ignoreSetter decide whether to ignore the parameter of * a property setter method. */ public void setIgnoreSetter(boolean ignoreSetter) { this.ignoreSetter = ignoreSetter; } /** * Controls if setter can return only void (default behavior) or it * can also return class in which it is declared. * * @param aSetterCanReturnItsClass if true then setter can return * either void or class in which it is declared. If false then * in order to be recognized as setter method (otherwise * already recognized as a setter) must return void. Later is * the default behavior. */ public void setSetterCanReturnItsClass(boolean aSetterCanReturnItsClass) { setterCanReturnItsClass = aSetterCanReturnItsClass; } /** * Set whether to ignore constructor parameters. * @param ignoreConstructorParameter decide whether to ignore * constructor parameters. */ public void setIgnoreConstructorParameter(boolean ignoreConstructorParameter) { this.ignoreConstructorParameter = ignoreConstructorParameter; } /** * Set whether to ignore parameters of abstract methods. * @param ignoreAbstractMethods decide whether to ignore * parameters of abstract methods. */ public void setIgnoreAbstractMethods(boolean ignoreAbstractMethods) { this.ignoreAbstractMethods = ignoreAbstractMethods; } /** @return the regexp to match against */ public Pattern getRegexp() { return regexp; } /** * Holds the names of static and instance fields of a type. * @author Rick Giles * Describe class FieldFrame * @author Rick Giles * @version Oct 26, 2003 */ private static class FieldFrame { /** type of the frame, such as TokenTypes.CLASS_DEF or TokenTypes.ENUM_DEF */ private final Integer frameType; /** name of the frame, such name of the class or enum declaration */ private final String frameName; /** is this a static inner type */ private final boolean staticType; /** parent frame. */ private final FieldFrame parent; /** set of instance field names */ private final Set<String> instanceFields = Sets.newHashSet(); /** set of static field names */ private final Set<String> staticFields = Sets.newHashSet(); /** * Creates new frame. * @param staticType is this a static inner type (class or enum). * @param parent parent frame. * @param frameType frameType derived from {@link TokenTypes} * @param frameName name associated with the frame, which can be a * class or enum name or null if no relevan information is available. */ public FieldFrame(FieldFrame parent, boolean staticType, Integer frameType, String frameName) { this.parent = parent; this.staticType = staticType; this.frameType = frameType; this.frameName = frameName; } /** * Is this frame for static inner type. * @return is this field frame for static inner type. */ boolean isStaticType() { return staticType; } /** * Adds an instance field to this FieldFrame. * @param field the name of the instance field. */ public void addInstanceField(String field) { instanceFields.add(field); } /** * Adds a static field to this FieldFrame. * @param field the name of the instance field. */ public void addStaticField(String field) { staticFields.add(field); } /** * Determines whether this FieldFrame contains an instance field. * @param field the field to check. * @return true if this FieldFrame contains instance field field. */ public boolean containsInstanceField(String field) { return instanceFields.contains(field) || !isStaticType() && (parent != null) && parent.containsInstanceField(field); } /** * Determines whether this FieldFrame contains a static field. * @param field the field to check. * @return true if this FieldFrame contains static field field. */ public boolean containsStaticField(String field) { return staticFields.contains(field) || (parent != null) && parent.containsStaticField(field); } /** * Getter for parent frame. * @return parent frame. */ public FieldFrame getParent() { return parent; } /** * Check if current frame is embedded in class or enum with * specific name. * * @param classOrEnumName name of class or enum that we are looking * for in the chain of field frames. * * @return true if current frame is embedded in class or enum * with name classOrNameName */ private boolean embeddedIn(String classOrEnumName) { FieldFrame currentFrame = this; while (currentFrame != null) { if (Objects.equal(currentFrame.frameName, classOrEnumName)) { return true; } currentFrame = currentFrame.parent; } return false; } } }