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.javadoc; 021 022import java.io.File; 023import java.io.IOException; 024import java.util.Set; 025import java.util.concurrent.ConcurrentHashMap; 026 027import com.puppycrawl.tools.checkstyle.GlobalStatefulCheck; 028import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck; 029import com.puppycrawl.tools.checkstyle.api.CheckstyleException; 030import com.puppycrawl.tools.checkstyle.api.FileText; 031 032/** 033 * <div> 034 * Checks that each Java package has a Javadoc file used for commenting. 035 * By default, it only allows a {@code package-info.java} file, 036 * but can be configured to allow a {@code package.html} file. 037 * </div> 038 * 039 * <p> 040 * A violation will be reported if both files exist as this is not allowed by the Javadoc tool. 041 * </p> 042 * <ul> 043 * <li> 044 * Property {@code allowLegacy} - Allow legacy {@code package.html} file to be used. 045 * Type is {@code boolean}. 046 * Default value is {@code false}. 047 * </li> 048 * <li> 049 * Property {@code fileExtensions} - Specify the file extensions of the files to process. 050 * Type is {@code java.lang.String[]}. 051 * Default value is {@code .java}. 052 * </li> 053 * </ul> 054 * 055 * <p> 056 * Parent is {@code com.puppycrawl.tools.checkstyle.Checker} 057 * </p> 058 * 059 * <p> 060 * Violation Message Keys: 061 * </p> 062 * <ul> 063 * <li> 064 * {@code javadoc.legacyPackageHtml} 065 * </li> 066 * <li> 067 * {@code javadoc.packageInfo} 068 * </li> 069 * </ul> 070 * 071 * @since 5.0 072 */ 073@GlobalStatefulCheck 074public class JavadocPackageCheck extends AbstractFileSetCheck { 075 076 /** 077 * A key is pointing to the warning message text in "messages.properties" 078 * file. 079 */ 080 public static final String MSG_LEGACY_PACKAGE_HTML = "javadoc.legacyPackageHtml"; 081 082 /** 083 * A key is pointing to the warning message text in "messages.properties" 084 * file. 085 */ 086 public static final String MSG_PACKAGE_INFO = "javadoc.packageInfo"; 087 088 /** The directories checked. */ 089 private final Set<File> directoriesChecked = ConcurrentHashMap.newKeySet(); 090 091 /** Allow legacy {@code package.html} file to be used. */ 092 private boolean allowLegacy; 093 094 /** 095 * Creates a new instance. 096 */ 097 public JavadocPackageCheck() { 098 // java, not html! 099 // The rule is: Every JAVA file should have a package.html sibling 100 setFileExtensions("java"); 101 } 102 103 @Override 104 protected void processFiltered(File file, FileText fileText) throws CheckstyleException { 105 // Check if already processed directory 106 final File dir; 107 try { 108 dir = file.getCanonicalFile().getParentFile(); 109 } 110 catch (IOException ex) { 111 throw new CheckstyleException( 112 "Exception while getting canonical path to file " + file.getPath(), ex); 113 } 114 final boolean isDirChecked = !directoriesChecked.add(dir); 115 if (!isDirChecked) { 116 // Check for the preferred file. 117 final File packageInfo = new File(dir, "package-info.java"); 118 final File packageHtml = new File(dir, "package.html"); 119 120 if (packageInfo.exists()) { 121 if (packageHtml.exists()) { 122 log(1, MSG_LEGACY_PACKAGE_HTML); 123 } 124 } 125 else if (!allowLegacy || !packageHtml.exists()) { 126 log(1, MSG_PACKAGE_INFO); 127 } 128 } 129 } 130 131 /** 132 * Setter to allow legacy {@code package.html} file to be used. 133 * 134 * @param allowLegacy whether to allow support. 135 * @since 5.0 136 */ 137 public void setAllowLegacy(boolean allowLegacy) { 138 this.allowLegacy = allowLegacy; 139 } 140 141}