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