001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2026 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.api; 021 022import java.text.MessageFormat; 023import java.util.Arrays; 024import java.util.Locale; 025import java.util.Objects; 026 027import javax.annotation.Nullable; 028 029import com.puppycrawl.tools.checkstyle.LocalizedMessage; 030import com.puppycrawl.tools.checkstyle.utils.UnmodifiableCollectionUtil; 031 032/** 033 * Represents a violation that can be localised. The translations come from 034 * message.properties files. The underlying implementation uses java.text.MessageFormat. 035 * 036 * @noinspection ClassWithTooManyConstructors 037 * @noinspectionreason ClassWithTooManyConstructors - immutable nature of class requires a 038 * bunch of constructors 039 */ 040public final class Violation implements Comparable<Violation> { 041 042 /** The default severity level if one is not specified. */ 043 private static final SeverityLevel DEFAULT_SEVERITY = SeverityLevel.ERROR; 044 045 /** The line number. */ 046 private final int lineNo; 047 /** The column number. */ 048 private final int columnNo; 049 /** The column char index. */ 050 private final int columnCharIndex; 051 /** The token type constant. See {@link TokenTypes}. */ 052 private final int tokenType; 053 054 /** The severity level. */ 055 private final SeverityLevel severityLevel; 056 057 /** The id of the module generating the violation. */ 058 private final String moduleId; 059 060 /** Key for the violation format. */ 061 private final String key; 062 063 /** Arguments for MessageFormat. */ 064 private final Object[] args; 065 066 /** Name of the resource bundle to get violations from. */ 067 private final String bundle; 068 069 /** Class of the source for this Violation. */ 070 private final Class<?> sourceClass; 071 072 /** A custom violation overriding the default violation from the bundle. */ 073 @Nullable 074 private final String customMessage; 075 076 /** 077 * Creates a new {@code Violation} instance. The column number defaults to 0. 078 * 079 * @param lineNo line number associated with the violation 080 * @param bundle name of a resource bundle that contains audit event violations 081 * @param key the key to locate the translation 082 * @param args arguments for the translation 083 * @param moduleId the id of the module the violation is associated with 084 * @param sourceClass the name of the source for the violation 085 * @param customMessage optional custom violation overriding the default 086 */ 087 public Violation( 088 int lineNo, 089 String bundle, 090 String key, 091 Object[] args, 092 String moduleId, 093 Class<?> sourceClass, 094 @Nullable String customMessage) { 095 this(lineNo, 0, bundle, key, args, DEFAULT_SEVERITY, moduleId, 096 sourceClass, customMessage); 097 } 098 099 /** 100 * Creates a new {@code Violation} instance. 101 * 102 * @param lineNo line number associated with the violation 103 * @param columnNo column number associated with the violation 104 * @param bundle resource bundle name 105 * @param key the key to locate the translation 106 * @param args arguments for the translation 107 * @param moduleId the id of the module the violation is associated with 108 * @param sourceClass the Class that is the source of the violation 109 * @param customMessage optional custom violation overriding the default 110 * @noinspection ConstructorWithTooManyParameters 111 * @noinspectionreason ConstructorWithTooManyParameters - immutable class requires a large 112 * number of arguments 113 */ 114 // -@cs[ParameterNumber] Class is immutable, we need that amount of arguments. 115 public Violation(int lineNo, 116 int columnNo, 117 String bundle, 118 String key, 119 Object[] args, 120 String moduleId, 121 Class<?> sourceClass, 122 @Nullable String customMessage) { 123 this(lineNo, 124 columnNo, 125 bundle, 126 key, 127 args, 128 DEFAULT_SEVERITY, 129 moduleId, 130 sourceClass, 131 customMessage); 132 } 133 134 /** 135 * Creates a new {@code Violation} instance. 136 * 137 * @param lineNo line number associated with the violation 138 * @param bundle resource bundle name 139 * @param key the key to locate the translation 140 * @param args arguments for the translation 141 * @param severityLevel severity level for the violation 142 * @param moduleId the id of the module the violation is associated with 143 * @param sourceClass the source class for the violation 144 * @param customMessage optional custom violation overriding the default 145 * @noinspection ConstructorWithTooManyParameters 146 * @noinspectionreason ConstructorWithTooManyParameters - immutable class requires a large 147 * number of arguments 148 */ 149 // -@cs[ParameterNumber] Class is immutable, we need that amount of arguments. 150 public Violation(int lineNo, 151 String bundle, 152 String key, 153 Object[] args, 154 SeverityLevel severityLevel, 155 String moduleId, 156 Class<?> sourceClass, 157 @Nullable String customMessage) { 158 this(lineNo, 0, bundle, key, args, severityLevel, moduleId, 159 sourceClass, customMessage); 160 } 161 162 /** 163 * Creates a new {@code Violation} instance. 164 * 165 * @param lineNo line number associated with the violation 166 * @param columnNo column number associated with the violation 167 * @param bundle resource bundle name 168 * @param key the key to locate the translation 169 * @param args arguments for the translation 170 * @param severityLevel severity level for the violation 171 * @param moduleId the id of the module the violation is associated with 172 * @param sourceClass the Class that is the source of the violation 173 * @param customMessage optional custom violation overriding the default 174 * @noinspection ConstructorWithTooManyParameters 175 * @noinspectionreason ConstructorWithTooManyParameters - immutable class requires a large 176 * number of arguments 177 */ 178 // -@cs[ParameterNumber] Class is immutable, we need that amount of arguments. 179 public Violation(int lineNo, 180 int columnNo, 181 String bundle, 182 String key, 183 Object[] args, 184 SeverityLevel severityLevel, 185 String moduleId, 186 Class<?> sourceClass, 187 @Nullable String customMessage) { 188 this(lineNo, columnNo, 0, bundle, key, args, severityLevel, moduleId, sourceClass, 189 customMessage); 190 } 191 192 /** 193 * Creates a new {@code Violation} instance. 194 * 195 * @param lineNo line number associated with the violation 196 * @param columnNo column number associated with the violation 197 * @param tokenType token type of the event associated with violation. See {@link TokenTypes} 198 * @param bundle resource bundle name 199 * @param key the key to locate the translation 200 * @param args arguments for the translation 201 * @param severityLevel severity level for the violation 202 * @param moduleId the id of the module the violation is associated with 203 * @param sourceClass the Class that is the source of the violation 204 * @param customMessage optional custom violation overriding the default 205 * @noinspection ConstructorWithTooManyParameters 206 * @noinspectionreason ConstructorWithTooManyParameters - immutable class requires a large 207 * number of arguments 208 */ 209 // -@cs[ParameterNumber] Class is immutable, we need that amount of arguments. 210 public Violation(int lineNo, 211 int columnNo, 212 int tokenType, 213 String bundle, 214 String key, 215 Object[] args, 216 SeverityLevel severityLevel, 217 String moduleId, 218 Class<?> sourceClass, 219 @Nullable String customMessage) { 220 this(lineNo, columnNo, columnNo, tokenType, bundle, key, args, severityLevel, moduleId, 221 sourceClass, customMessage); 222 } 223 224 /** 225 * Creates a new {@code Violation} instance. 226 * 227 * @param lineNo line number associated with the violation 228 * @param columnNo column number associated with the violation 229 * @param columnCharIndex column char index associated with the violation 230 * @param tokenType token type of the event associated with violation. See {@link TokenTypes} 231 * @param bundle resource bundle name 232 * @param key the key to locate the translation 233 * @param args arguments for the translation 234 * @param severityLevel severity level for the violation 235 * @param moduleId the id of the module the violation is associated with 236 * @param sourceClass the Class that is the source of the violation 237 * @param customMessage optional custom violation overriding the default 238 * @noinspection ConstructorWithTooManyParameters 239 * @noinspectionreason ConstructorWithTooManyParameters - immutable class requires a large 240 * number of arguments 241 */ 242 // -@cs[ParameterNumber] Class is immutable, we need that amount of arguments. 243 public Violation(int lineNo, 244 int columnNo, 245 int columnCharIndex, 246 int tokenType, 247 String bundle, 248 String key, 249 Object[] args, 250 SeverityLevel severityLevel, 251 String moduleId, 252 Class<?> sourceClass, 253 @Nullable String customMessage) { 254 this.lineNo = lineNo; 255 this.columnNo = columnNo; 256 this.columnCharIndex = columnCharIndex; 257 this.tokenType = tokenType; 258 this.key = key; 259 260 if (args == null) { 261 this.args = null; 262 } 263 else { 264 this.args = UnmodifiableCollectionUtil.copyOfArray(args, args.length); 265 } 266 this.bundle = bundle; 267 this.severityLevel = severityLevel; 268 this.moduleId = moduleId; 269 this.sourceClass = sourceClass; 270 this.customMessage = customMessage; 271 } 272 273 /** 274 * Gets the line number. 275 * 276 * @return the line number 277 */ 278 public int getLineNo() { 279 return lineNo; 280 } 281 282 /** 283 * Gets the column number. 284 * 285 * @return the column number 286 */ 287 public int getColumnNo() { 288 return columnNo; 289 } 290 291 /** 292 * Gets the column char index. 293 * 294 * @return the column char index 295 */ 296 public int getColumnCharIndex() { 297 return columnCharIndex; 298 } 299 300 /** 301 * Gets the token type. 302 * 303 * @return the token type 304 */ 305 public int getTokenType() { 306 return tokenType; 307 } 308 309 /** 310 * Gets the severity level. 311 * 312 * @return the severity level 313 */ 314 public SeverityLevel getSeverityLevel() { 315 return severityLevel; 316 } 317 318 /** 319 * Returns id of module. 320 * 321 * @return the module identifier. 322 */ 323 public String getModuleId() { 324 return moduleId; 325 } 326 327 /** 328 * Returns the violation key to locate the translation, can also be used 329 * in IDE plugins to map audit event violations to corrective actions. 330 * 331 * @return the violation key 332 */ 333 public String getKey() { 334 return key; 335 } 336 337 /** 338 * Gets the name of the source for this Violation. 339 * 340 * @return the name of the source for this Violation 341 */ 342 public String getSourceName() { 343 return sourceClass.getName(); 344 } 345 346 /** 347 * Indicates whether some other object is "equal to" this one. 348 * Suppression on enumeration is needed so code stays consistent. 349 * 350 * @noinspection EqualsCalledOnEnumConstant 351 * @noinspectionreason EqualsCalledOnEnumConstant - enumeration is needed to keep 352 * code consistent 353 */ 354 // -@cs[CyclomaticComplexity] equals - a lot of fields to check. 355 @Override 356 @SuppressWarnings("OverlyComplexBooleanExpression") 357 public boolean equals(Object object) { 358 if (this == object) { 359 return true; 360 } 361 if (object == null || getClass() != object.getClass()) { 362 return false; 363 } 364 final Violation violation = (Violation) object; 365 return lineNo == violation.lineNo 366 && columnNo == violation.columnNo 367 && columnCharIndex == violation.columnCharIndex 368 && tokenType == violation.tokenType 369 && Objects.equals(severityLevel, violation.severityLevel) 370 && Objects.equals(moduleId, violation.moduleId) 371 && Objects.equals(key, violation.key) 372 && Objects.equals(bundle, violation.bundle) 373 && Objects.equals(sourceClass, violation.sourceClass) 374 && Objects.equals(customMessage, violation.customMessage) 375 && Arrays.equals(args, violation.args); 376 } 377 378 @Override 379 public int hashCode() { 380 return Objects.hash(lineNo, columnNo, columnCharIndex, tokenType, severityLevel, moduleId, 381 key, bundle, sourceClass, customMessage, Arrays.hashCode(args)); 382 } 383 384 //////////////////////////////////////////////////////////////////////////// 385 // Interface Comparable methods 386 //////////////////////////////////////////////////////////////////////////// 387 388 /** 389 * {@inheritDoc} 390 * 391 * <p>The same fields as in {@link #equals(Object)} take part in the 392 * comparison, so that a result of zero is consistent with equality, as the 393 * {@link Comparable} contract recommends. Line, column, module id, source 394 * class, and the rendered violation stay the leading criteria; the 395 * remaining fields only break a tie between violations that would 396 * otherwise be reported at the same place with the same text. 397 */ 398 @Override 399 public int compareTo(Violation other) { 400 int result = compareLocation(other); 401 if (result == 0) { 402 result = compareContent(other); 403 } 404 return result; 405 } 406 407 /** 408 * Compares the place and the text a violation is reported with. 409 * 410 * @param other the violation to compare against 411 * @return the value {@code 0} if the violations are reported the same way 412 */ 413 private int compareLocation(Violation other) { 414 int result = Integer.compare(lineNo, other.lineNo); 415 if (result == 0) { 416 result = Integer.compare(columnNo, other.columnNo); 417 } 418 if (result == 0) { 419 result = compareNullable(moduleId, other.moduleId); 420 } 421 if (result == 0) { 422 result = compareNullable(getSourceClassName(), other.getSourceClassName()); 423 } 424 if (result == 0) { 425 result = getViolation().compareTo(other.getViolation()); 426 } 427 return result; 428 } 429 430 /** 431 * Compares the fields that two violations reported at the same place with 432 * the same text can still differ in. 433 * 434 * @param other the violation to compare against 435 * @return the value {@code 0} if the violations carry the same content 436 */ 437 private int compareContent(Violation other) { 438 int result = Integer.compare(columnCharIndex, other.columnCharIndex); 439 if (result == 0) { 440 result = Integer.compare(tokenType, other.tokenType); 441 } 442 if (result == 0) { 443 result = severityLevel.compareTo(other.severityLevel); 444 } 445 if (result == 0) { 446 result = compareNullable(key, other.key); 447 } 448 if (result == 0) { 449 result = compareNullable(bundle, other.bundle); 450 } 451 if (result == 0) { 452 result = compareNullable(customMessage, other.customMessage); 453 } 454 if (result == 0) { 455 result = Arrays.deepToString(args).compareTo(Arrays.deepToString(other.args)); 456 } 457 return result; 458 } 459 460 /** 461 * Compares two values that may be {@code null}, ordering {@code null} before any other value. 462 * 463 * @param first the first value 464 * @param second the second value 465 * @return a negative integer, zero, or a positive integer as the first 466 * value is less than, equal to, or greater than the second 467 */ 468 private static int compareNullable(@Nullable String first, @Nullable String second) { 469 final int result; 470 if (first == null) { 471 if (second == null) { 472 result = 0; 473 } 474 else { 475 result = -1; 476 } 477 } 478 else if (second == null) { 479 result = 1; 480 } 481 else { 482 result = first.compareTo(second); 483 } 484 return result; 485 } 486 487 /** 488 * Gets the source class name or {@code null} when no source class is set. 489 * 490 * @return the source class name or {@code null} 491 */ 492 @Nullable 493 private String getSourceClassName() { 494 final String name; 495 if (sourceClass == null) { 496 name = null; 497 } 498 else { 499 name = sourceClass.getName(); 500 } 501 return name; 502 } 503 504 /** 505 * Gets the translated violation. 506 * 507 * @return the translated violation 508 */ 509 public String getViolation() { 510 final String violation; 511 512 if (customMessage != null) { 513 violation = new MessageFormat(customMessage, Locale.ROOT).format(args); 514 } 515 else { 516 violation = new LocalizedMessage(bundle, sourceClass, key, args).getMessage(); 517 } 518 519 return violation; 520 } 521 522}