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.coding; 021 022import java.io.File; 023 024import com.puppycrawl.tools.checkstyle.FileStatefulCheck; 025import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 026import com.puppycrawl.tools.checkstyle.api.DetailAST; 027import com.puppycrawl.tools.checkstyle.api.FullIdent; 028import com.puppycrawl.tools.checkstyle.api.TokenTypes; 029 030/** 031 * <div> 032 * Ensures that a class has a package declaration, and (optionally) whether 033 * the package name matches the directory name for the source file. 034 * </div> 035 * 036 * <p> 037 * Rationale: Classes that live in the null package cannot be imported. 038 * Many novice developers are not aware of this. 039 * </p> 040 * 041 * <p> 042 * Packages provide logical namespace to classes and should be stored in 043 * the form of directory levels to provide physical grouping to your classes. 044 * These directories are added to the classpath so that your classes 045 * are visible to JVM when it runs the code. 046 * </p> 047 * <ul> 048 * <li> 049 * Property {@code matchDirectoryStructure} - Control whether to check for 050 * directory and package name match. 051 * Type is {@code boolean}. 052 * Default value is {@code true}. 053 * </li> 054 * </ul> 055 * 056 * <p> 057 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 058 * </p> 059 * 060 * <p> 061 * Violation Message Keys: 062 * </p> 063 * <ul> 064 * <li> 065 * {@code mismatch.package.directory} 066 * </li> 067 * <li> 068 * {@code missing.package.declaration} 069 * </li> 070 * </ul> 071 * 072 * @since 3.2 073 */ 074@FileStatefulCheck 075public final class PackageDeclarationCheck extends AbstractCheck { 076 077 /** 078 * A key is pointing to the warning message text in "messages.properties" 079 * file. 080 */ 081 public static final String MSG_KEY_MISSING = "missing.package.declaration"; 082 083 /** 084 * A key is pointing to the warning message text in "messages.properties" 085 * file. 086 */ 087 public static final String MSG_KEY_MISMATCH = "mismatch.package.directory"; 088 089 /** Is package defined. */ 090 private boolean defined; 091 092 /** Control whether to check for directory and package name match. */ 093 private boolean matchDirectoryStructure = true; 094 095 /** 096 * Setter to control whether to check for directory and package name match. 097 * 098 * @param matchDirectoryStructure the new value. 099 * @since 7.6.1 100 */ 101 public void setMatchDirectoryStructure(boolean matchDirectoryStructure) { 102 this.matchDirectoryStructure = matchDirectoryStructure; 103 } 104 105 @Override 106 public int[] getDefaultTokens() { 107 return getRequiredTokens(); 108 } 109 110 @Override 111 public int[] getRequiredTokens() { 112 return new int[] {TokenTypes.PACKAGE_DEF}; 113 } 114 115 @Override 116 public int[] getAcceptableTokens() { 117 return getRequiredTokens(); 118 } 119 120 @Override 121 public void beginTree(DetailAST ast) { 122 defined = false; 123 } 124 125 @Override 126 public void finishTree(DetailAST ast) { 127 if (!defined && ast != null) { 128 log(ast, MSG_KEY_MISSING); 129 } 130 } 131 132 @Override 133 public void visitToken(DetailAST ast) { 134 defined = true; 135 136 if (matchDirectoryStructure) { 137 final DetailAST packageNameAst = ast.getLastChild().getPreviousSibling(); 138 final FullIdent fullIdent = FullIdent.createFullIdent(packageNameAst); 139 final String packageName = fullIdent.getText().replace('.', File.separatorChar); 140 141 final String directoryName = getDirectoryName(); 142 143 if (!directoryName.endsWith(packageName)) { 144 log(ast, MSG_KEY_MISMATCH, packageName); 145 } 146 } 147 } 148 149 /** 150 * Returns the directory name this file is in. 151 * 152 * @return Directory name. 153 */ 154 private String getDirectoryName() { 155 final String fileName = getFilePath(); 156 final int lastSeparatorPos = fileName.lastIndexOf(File.separatorChar); 157 return fileName.substring(0, lastSeparatorPos); 158 } 159 160}