001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2023 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 headerFile} - Specify the name of the file containing the required header. 059 * Type is {@code java.net.URI}. 060 * Default value is {@code null}. 061 * </li> 062 * <li> 063 * Property {@code charset} - Specify the character encoding to use when reading the headerFile. 064 * Type is {@code java.lang.String}. 065 * Default value is {@code the charset property of the parent 066 * <a href="https://checkstyle.org/config.html#Checker">Checker</a> module}. 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), see examples below. 072 * Type is {@code java.lang.String}. 073 * Default value is {@code null}. 074 * </li> 075 * <li> 076 * Property {@code ignoreLines} - Specify the line numbers to ignore. 077 * Type is {@code int[]}. 078 * Default value is {@code ""}. 079 * </li> 080 * <li> 081 * Property {@code fileExtensions} - Specify the file type extension of files to process. 082 * Type is {@code java.lang.String[]}. 083 * Default value is {@code ""}. 084 * </li> 085 * </ul> 086 * <p> 087 * To configure the check such that no violations arise. 088 * Default values of properties are used. 089 * </p> 090 * <pre> 091 * <module name="Header"/> 092 * </pre> 093 * <p> 094 * To configure the check to use header file {@code "config/java.header"} 095 * and ignore lines {@code 2}, {@code 3}, and {@code 4} and only process Java files: 096 * </p> 097 * <pre> 098 * <module name="Header"> 099 * <property name="headerFile" value="config/java.header"/> 100 * <property name="ignoreLines" value="2, 3, 4"/> 101 * <property name="fileExtensions" value="java"/> 102 * </module> 103 * </pre> 104 * <p> 105 * To configure the check to verify that each file starts with the header 106 * </p> 107 * <pre> 108 * // Copyright (C) 2004 MyCompany 109 * // All rights reserved 110 * </pre> 111 * <p> 112 * without the need for an external header file: 113 * </p> 114 * <pre> 115 * <module name="Header"> 116 * <property name="header" 117 * value="// Copyright (C) 2004 MyCompany\n// All rights reserved"/> 118 * </module> 119 * </pre> 120 * <p> 121 * Parent is {@code com.puppycrawl.tools.checkstyle.Checker} 122 * </p> 123 * <p> 124 * Violation Message Keys: 125 * </p> 126 * <ul> 127 * <li> 128 * {@code header.mismatch} 129 * </li> 130 * <li> 131 * {@code header.missing} 132 * </li> 133 * </ul> 134 * 135 * @since 6.9 136 */ 137@StatelessCheck 138public class HeaderCheck extends AbstractHeaderCheck { 139 140 /** 141 * A key is pointing to the warning message text in "messages.properties" 142 * file. 143 */ 144 public static final String MSG_MISSING = "header.missing"; 145 146 /** 147 * A key is pointing to the warning message text in "messages.properties" 148 * file. 149 */ 150 public static final String MSG_MISMATCH = "header.mismatch"; 151 152 /** Specify the line numbers to ignore. */ 153 private BitSet ignoreLines = new BitSet(); 154 155 /** 156 * Returns true if lineNo is header lines or false. 157 * 158 * @param lineNo a line number 159 * @return if {@code lineNo} is one of the ignored header lines. 160 */ 161 private boolean isIgnoreLine(int lineNo) { 162 return ignoreLines.get(lineNo); 163 } 164 165 /** 166 * Checks if a code line matches the required header line. 167 * 168 * @param lineNumber the line number to check against the header 169 * @param line the line contents 170 * @return true if and only if the line matches the required header line 171 */ 172 private boolean isMatch(int lineNumber, String line) { 173 // skip lines we are meant to ignore 174 return isIgnoreLine(lineNumber + 1) 175 || getHeaderLines().get(lineNumber).equals(line); 176 } 177 178 /** 179 * Setter to specify the line numbers to ignore. 180 * 181 * @param lines line numbers to ignore in header. 182 */ 183 public void setIgnoreLines(int... lines) { 184 ignoreLines = TokenUtil.asBitSet(lines); 185 } 186 187 @Override 188 protected void processFiltered(File file, FileText fileText) { 189 if (getHeaderLines().size() > fileText.size()) { 190 log(1, MSG_MISSING); 191 } 192 else { 193 for (int i = 0; i < getHeaderLines().size(); i++) { 194 if (!isMatch(i, fileText.get(i))) { 195 log(i + 1, MSG_MISMATCH, getHeaderLines().get(i)); 196 break; 197 } 198 } 199 } 200 } 201 202 @Override 203 protected void postProcessHeaderLines() { 204 // no code 205 } 206 207}