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.header; 021 022import java.io.File; 023import java.util.BitSet; 024 025import com.puppycrawl.tools.checkstyle.StatelessCheck; 026import com.puppycrawl.tools.checkstyle.api.FileText; 027import com.puppycrawl.tools.checkstyle.utils.TokenUtil; 028 029/** 030 * <div> 031 * Checks that a source file begins with a specified header. 032 * Property {@code headerFile} specifies a file that contains the required header. 033 * Alternatively, the header specification can be set directly in the 034 * {@code header} property without the need for an external file. 035 * </div> 036 * 037 * <p> 038 * Property {@code ignoreLines} specifies the line numbers to ignore when matching 039 * lines in a header file. This property is very useful for supporting headers 040 * that contain copyright dates. For example, consider the following header: 041 * </p> 042 * <pre> 043 * line 1: //////////////////////////////////////////////////////////////////// 044 * line 2: // checkstyle: 045 * line 3: // Checks Java source code for adherence to a set of rules. 046 * line 4: // Copyright (C) 2002 Oliver Burn 047 * line 5: //////////////////////////////////////////////////////////////////// 048 * </pre> 049 * 050 * <p> 051 * Since the year information will change over time, you can tell Checkstyle 052 * to ignore line 4 by setting property {@code ignoreLines} to {@code 4}. 053 * </p> 054 * 055 * <p> 056 * In default configuration, if header is not specified, the default value 057 * of header is set to {@code null} and the check does not rise any violations. 058 * </p> 059 * <ul> 060 * <li> 061 * Property {@code charset} - Specify the character encoding to use when reading the headerFile. 062 * Type is {@code java.lang.String}. 063 * Default value is {@code the charset property of the parent 064 * <a href="https://checkstyle.org/config.html#Checker">Checker</a> module}. 065 * </li> 066 * <li> 067 * Property {@code fileExtensions} - Specify the file extensions of the files to process. 068 * Type is {@code java.lang.String[]}. 069 * Default value is {@code ""}. 070 * </li> 071 * <li> 072 * Property {@code header} - Specify the required header specified inline. 073 * Individual header lines must be separated by the string {@code "\n"} 074 * (even on platforms with a different line separator). 075 * Type is {@code java.lang.String}. 076 * Default value is {@code null}. 077 * </li> 078 * <li> 079 * Property {@code headerFile} - Specify the name of the file containing the required header. 080 * Type is {@code java.net.URI}. 081 * Default value is {@code null}. 082 * </li> 083 * <li> 084 * Property {@code ignoreLines} - Specify the line numbers to ignore. 085 * Type is {@code int[]}. 086 * Default value is {@code ""}. 087 * </li> 088 * </ul> 089 * 090 * <p> 091 * Parent is {@code com.puppycrawl.tools.checkstyle.Checker} 092 * </p> 093 * 094 * <p> 095 * Violation Message Keys: 096 * </p> 097 * <ul> 098 * <li> 099 * {@code header.mismatch} 100 * </li> 101 * <li> 102 * {@code header.missing} 103 * </li> 104 * </ul> 105 * 106 * @since 6.9 107 */ 108@StatelessCheck 109public class HeaderCheck extends AbstractHeaderCheck { 110 111 /** 112 * A key is pointing to the warning message text in "messages.properties" 113 * file. 114 */ 115 public static final String MSG_MISSING = "header.missing"; 116 117 /** 118 * A key is pointing to the warning message text in "messages.properties" 119 * file. 120 */ 121 public static final String MSG_MISMATCH = "header.mismatch"; 122 123 /** Specify the line numbers to ignore. */ 124 private BitSet ignoreLines = new BitSet(); 125 126 /** 127 * Returns true if lineNo is header lines or false. 128 * 129 * @param lineNo a line number 130 * @return if {@code lineNo} is one of the ignored header lines. 131 */ 132 private boolean isIgnoreLine(int lineNo) { 133 return ignoreLines.get(lineNo); 134 } 135 136 /** 137 * Checks if a code line matches the required header line. 138 * 139 * @param lineNumber the line number to check against the header 140 * @param line the line contents 141 * @return true if and only if the line matches the required header line 142 */ 143 private boolean isMatch(int lineNumber, String line) { 144 // skip lines we are meant to ignore 145 return isIgnoreLine(lineNumber + 1) 146 || getHeaderLines().get(lineNumber).equals(line); 147 } 148 149 /** 150 * Setter to specify the line numbers to ignore. 151 * 152 * @param lines line numbers to ignore in header. 153 * @since 3.2 154 */ 155 public void setIgnoreLines(int... lines) { 156 ignoreLines = TokenUtil.asBitSet(lines); 157 } 158 159 @Override 160 protected void processFiltered(File file, FileText fileText) { 161 if (getHeaderLines().size() > fileText.size()) { 162 log(1, MSG_MISSING); 163 } 164 else { 165 for (int i = 0; i < getHeaderLines().size(); i++) { 166 if (!isMatch(i, fileText.get(i))) { 167 log(i + 1, MSG_MISMATCH, getHeaderLines().get(i)); 168 break; 169 } 170 } 171 } 172 } 173 174 @Override 175 protected void postProcessHeaderLines() { 176 // no code 177 } 178 179}