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