001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2024 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.modifier; 021 022import java.util.ArrayList; 023import java.util.Iterator; 024import java.util.List; 025 026import com.puppycrawl.tools.checkstyle.StatelessCheck; 027import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 028import com.puppycrawl.tools.checkstyle.api.DetailAST; 029import com.puppycrawl.tools.checkstyle.api.TokenTypes; 030 031/** 032 * <p> 033 * Checks that the order of modifiers conforms to the suggestions in the 034 * <a href="https://docs.oracle.com/javase/specs/jls/se16/preview/specs/sealed-classes-jls.html"> 035 * Java Language specification, § 8.1.1, 8.3.1, 8.4.3</a> and 036 * <a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-9.html">9.4</a>. 037 * The correct order is: 038 * </p> 039 * <ol> 040 * <li> {@code public} </li> 041 * <li> {@code protected} </li> 042 * <li> {@code private} </li> 043 * <li> {@code abstract} </li> 044 * <li> {@code default} </li> 045 * <li> {@code static} </li> 046 * <li> {@code sealed} </li> 047 * <li> {@code non-sealed} </li> 048 * <li> {@code final} </li> 049 * <li> {@code transient} </li> 050 * <li> {@code volatile} </li> 051 * <li> {@code synchronized} </li> 052 * <li> {@code native} </li> 053 * <li> {@code strictfp} </li> 054 * </ol> 055 * <p> 056 * In additional, modifiers are checked to ensure all annotations 057 * are declared before all other modifiers. 058 * </p> 059 * <p> 060 * Rationale: Code is easier to read if everybody follows 061 * a standard. 062 * </p> 063 * <p> 064 * ATTENTION: We skip 065 * <a href="https://www.oracle.com/technical-resources/articles/java/ma14-architect-annotations.html"> 066 * type annotations</a> from validation. 067 * </p> 068 * <p> 069 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 070 * </p> 071 * <p> 072 * Violation Message Keys: 073 * </p> 074 * <ul> 075 * <li> 076 * {@code annotation.order} 077 * </li> 078 * <li> 079 * {@code mod.order} 080 * </li> 081 * </ul> 082 * 083 * @since 3.0 084 */ 085@StatelessCheck 086public class ModifierOrderCheck 087 extends AbstractCheck { 088 089 /** 090 * A key is pointing to the warning message text in "messages.properties" 091 * file. 092 */ 093 public static final String MSG_ANNOTATION_ORDER = "annotation.order"; 094 095 /** 096 * A key is pointing to the warning message text in "messages.properties" 097 * file. 098 */ 099 public static final String MSG_MODIFIER_ORDER = "mod.order"; 100 101 /** 102 * The order of modifiers as suggested in sections 8.1.1, 103 * 8.3.1 and 8.4.3 of the JLS. 104 */ 105 private static final String[] JLS_ORDER = { 106 "public", "protected", "private", "abstract", "default", "static", 107 "sealed", "non-sealed", "final", "transient", "volatile", 108 "synchronized", "native", "strictfp", 109 }; 110 111 @Override 112 public int[] getDefaultTokens() { 113 return getRequiredTokens(); 114 } 115 116 @Override 117 public int[] getAcceptableTokens() { 118 return getRequiredTokens(); 119 } 120 121 @Override 122 public int[] getRequiredTokens() { 123 return new int[] {TokenTypes.MODIFIERS}; 124 } 125 126 @Override 127 public void visitToken(DetailAST ast) { 128 final List<DetailAST> mods = new ArrayList<>(); 129 DetailAST modifier = ast.getFirstChild(); 130 while (modifier != null) { 131 mods.add(modifier); 132 modifier = modifier.getNextSibling(); 133 } 134 135 if (!mods.isEmpty()) { 136 final DetailAST error = checkOrderSuggestedByJls(mods); 137 if (error != null) { 138 if (error.getType() == TokenTypes.ANNOTATION) { 139 log(error, 140 MSG_ANNOTATION_ORDER, 141 error.getFirstChild().getText() 142 + error.getFirstChild().getNextSibling() 143 .getText()); 144 } 145 else { 146 log(error, MSG_MODIFIER_ORDER, error.getText()); 147 } 148 } 149 } 150 } 151 152 /** 153 * Checks if the modifiers were added in the order suggested 154 * in the Java language specification. 155 * 156 * @param modifiers list of modifier AST tokens 157 * @return null if the order is correct, otherwise returns the offending 158 * modifier AST. 159 */ 160 private static DetailAST checkOrderSuggestedByJls(List<DetailAST> modifiers) { 161 final Iterator<DetailAST> iterator = modifiers.iterator(); 162 163 // Speed past all initial annotations 164 DetailAST modifier = skipAnnotations(iterator); 165 166 DetailAST offendingModifier = null; 167 168 // All modifiers are annotations, no problem 169 if (modifier.getType() != TokenTypes.ANNOTATION) { 170 int index = 0; 171 172 while (modifier != null 173 && offendingModifier == null) { 174 if (modifier.getType() == TokenTypes.ANNOTATION) { 175 if (!isAnnotationOnType(modifier)) { 176 // Annotation not at start of modifiers, bad 177 offendingModifier = modifier; 178 } 179 break; 180 } 181 182 while (index < JLS_ORDER.length 183 && !JLS_ORDER[index].equals(modifier.getText())) { 184 index++; 185 } 186 187 if (index == JLS_ORDER.length) { 188 // Current modifier is out of JLS order 189 offendingModifier = modifier; 190 } 191 else if (iterator.hasNext()) { 192 modifier = iterator.next(); 193 } 194 else { 195 // Reached end of modifiers without problem 196 modifier = null; 197 } 198 } 199 } 200 return offendingModifier; 201 } 202 203 /** 204 * Skip all annotations in modifier block. 205 * 206 * @param modifierIterator iterator for collection of modifiers 207 * @return modifier next to last annotation 208 */ 209 private static DetailAST skipAnnotations(Iterator<DetailAST> modifierIterator) { 210 DetailAST modifier; 211 do { 212 modifier = modifierIterator.next(); 213 } while (modifierIterator.hasNext() && modifier.getType() == TokenTypes.ANNOTATION); 214 return modifier; 215 } 216 217 /** 218 * Checks whether annotation on type takes place. 219 * 220 * @param modifier modifier token. 221 * @return true if annotation on type takes place. 222 */ 223 private static boolean isAnnotationOnType(DetailAST modifier) { 224 boolean annotationOnType = false; 225 final DetailAST modifiers = modifier.getParent(); 226 final DetailAST definition = modifiers.getParent(); 227 final int definitionType = definition.getType(); 228 if (definitionType == TokenTypes.VARIABLE_DEF 229 || definitionType == TokenTypes.PARAMETER_DEF 230 || definitionType == TokenTypes.CTOR_DEF) { 231 annotationOnType = true; 232 } 233 else if (definitionType == TokenTypes.METHOD_DEF) { 234 final DetailAST typeToken = definition.findFirstToken(TokenTypes.TYPE); 235 final int methodReturnType = typeToken.getLastChild().getType(); 236 if (methodReturnType != TokenTypes.LITERAL_VOID) { 237 annotationOnType = true; 238 } 239 } 240 return annotationOnType; 241 } 242 243}