001/* 002 * Copyright (C) 2013 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.base; 016 017import static com.google.common.base.Strings.lenientFormat; 018 019import com.google.common.annotations.GwtCompatible; 020import com.google.errorprone.annotations.CanIgnoreReturnValue; 021import org.checkerframework.checker.nullness.qual.Nullable; 022 023/** 024 * Static convenience methods that serve the same purpose as Java language <a 025 * href="https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html">assertions</a>, 026 * except that they are always enabled. These methods should be used instead of Java assertions 027 * whenever there is a chance the check may fail "in real life". Example: 028 * 029 * <pre>{@code 030 * Bill bill = remoteService.getLastUnpaidBill(); 031 * 032 * // In case bug 12345 happens again we'd rather just die 033 * Verify.verify(bill.status() == Status.UNPAID, 034 * "Unexpected bill status: %s", bill.status()); 035 * }</pre> 036 * 037 * <h3>Comparison to alternatives</h3> 038 * 039 * <p><b>Note:</b> In some cases the differences explained below can be subtle. When it's unclear 040 * which approach to use, <b>don't worry</b> too much about it; just pick something that seems 041 * reasonable and it will be fine. 042 * 043 * <ul> 044 * <li>If checking whether the <i>caller</i> has violated your method or constructor's contract 045 * (such as by passing an invalid argument), use the utilities of the {@link Preconditions} 046 * class instead. 047 * <li>If checking an <i>impossible</i> condition (which <i>cannot</i> happen unless your own 048 * class or its <i>trusted</i> dependencies is badly broken), this is what ordinary Java 049 * assertions are for. Note that assertions are not enabled by default; they are essentially 050 * considered "compiled comments." 051 * <li>An explicit {@code if/throw} (as illustrated below) is always acceptable; we still 052 * recommend using our {@link VerifyException} exception type. Throwing a plain {@link 053 * RuntimeException} is frowned upon. 054 * <li>Use of {@link java.util.Objects#requireNonNull(Object)} is generally discouraged, since 055 * {@link #verifyNotNull(Object)} and {@link Preconditions#checkNotNull(Object)} perform the 056 * same function with more clarity. 057 * </ul> 058 * 059 * <h3>Warning about performance</h3> 060 * 061 * <p>Remember that parameter values for message construction must all be computed eagerly, and 062 * autoboxing and varargs array creation may happen as well, even when the verification succeeds and 063 * the message ends up unneeded. Performance-sensitive verification checks should continue to use 064 * usual form: 065 * 066 * <pre>{@code 067 * Bill bill = remoteService.getLastUnpaidBill(); 068 * if (bill.status() != Status.UNPAID) { 069 * throw new VerifyException("Unexpected bill status: " + bill.status()); 070 * } 071 * }</pre> 072 * 073 * <h3>Only {@code %s} is supported</h3> 074 * 075 * <p>As with {@link Preconditions}, {@code Verify} uses {@link Strings#lenientFormat} to format 076 * error message template strings. This only supports the {@code "%s"} specifier, not the full range 077 * of {@link java.util.Formatter} specifiers. However, note that if the number of arguments does not 078 * match the number of occurrences of {@code "%s"} in the format string, {@code Verify} will still 079 * behave as expected, and will still include all argument values in the error message; the message 080 * will simply not be formatted exactly as intended. 081 * 082 * <h3>More information</h3> 083 * 084 * See <a href="https://github.com/google/guava/wiki/ConditionalFailuresExplained">Conditional 085 * failures explained</a> in the Guava User Guide for advice on when this class should be used. 086 * 087 * @since 17.0 088 */ 089@GwtCompatible 090public final class Verify { 091 /** 092 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with no 093 * message otherwise. 094 * 095 * @throws VerifyException if {@code expression} is {@code false} 096 * @see Preconditions#checkState Preconditions.checkState() 097 */ 098 public static void verify(boolean expression) { 099 if (!expression) { 100 throw new VerifyException(); 101 } 102 } 103 104 /** 105 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 106 * custom message otherwise. 107 * 108 * @param expression a boolean expression 109 * @param errorMessageTemplate a template for the exception message should the check fail. The 110 * message is formed by replacing each {@code %s} placeholder in the template with an 111 * argument. These are matched by position - the first {@code %s} gets {@code 112 * errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in 113 * square braces. Unmatched placeholders will be left as-is. 114 * @param errorMessageArgs the arguments to be substituted into the message template. Arguments 115 * are converted to strings using {@link String#valueOf(Object)}. 116 * @throws VerifyException if {@code expression} is {@code false} 117 * @see Preconditions#checkState Preconditions.checkState() 118 */ 119 public static void verify( 120 boolean expression, 121 @Nullable String errorMessageTemplate, 122 @Nullable Object @Nullable ... errorMessageArgs) { 123 if (!expression) { 124 throw new VerifyException(lenientFormat(errorMessageTemplate, errorMessageArgs)); 125 } 126 } 127 128 /** 129 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 130 * custom message otherwise. 131 * 132 * <p>See {@link #verify(boolean, String, Object...)} for details. 133 * 134 * @since 23.1 (varargs overload since 17.0) 135 */ 136 public static void verify(boolean expression, @Nullable String errorMessageTemplate, char p1) { 137 if (!expression) { 138 throw new VerifyException(lenientFormat(errorMessageTemplate, p1)); 139 } 140 } 141 142 /** 143 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 144 * custom message otherwise. 145 * 146 * <p>See {@link #verify(boolean, String, Object...)} for details. 147 * 148 * @since 23.1 (varargs overload since 17.0) 149 */ 150 public static void verify(boolean expression, @Nullable String errorMessageTemplate, int p1) { 151 if (!expression) { 152 throw new VerifyException(lenientFormat(errorMessageTemplate, p1)); 153 } 154 } 155 156 /** 157 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 158 * custom message otherwise. 159 * 160 * <p>See {@link #verify(boolean, String, Object...)} for details. 161 * 162 * @since 23.1 (varargs overload since 17.0) 163 */ 164 public static void verify(boolean expression, @Nullable String errorMessageTemplate, long p1) { 165 if (!expression) { 166 throw new VerifyException(lenientFormat(errorMessageTemplate, p1)); 167 } 168 } 169 170 /** 171 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 172 * custom message otherwise. 173 * 174 * <p>See {@link #verify(boolean, String, Object...)} for details. 175 * 176 * @since 23.1 (varargs overload since 17.0) 177 */ 178 public static void verify( 179 boolean expression, @Nullable String errorMessageTemplate, @Nullable Object p1) { 180 if (!expression) { 181 throw new VerifyException(lenientFormat(errorMessageTemplate, p1)); 182 } 183 } 184 185 /** 186 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 187 * custom message otherwise. 188 * 189 * <p>See {@link #verify(boolean, String, Object...)} for details. 190 * 191 * @since 23.1 (varargs overload since 17.0) 192 */ 193 public static void verify( 194 boolean expression, @Nullable String errorMessageTemplate, char p1, char p2) { 195 if (!expression) { 196 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 197 } 198 } 199 200 /** 201 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 202 * custom message otherwise. 203 * 204 * <p>See {@link #verify(boolean, String, Object...)} for details. 205 * 206 * @since 23.1 (varargs overload since 17.0) 207 */ 208 public static void verify( 209 boolean expression, @Nullable String errorMessageTemplate, int p1, char p2) { 210 if (!expression) { 211 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 212 } 213 } 214 215 /** 216 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 217 * custom message otherwise. 218 * 219 * <p>See {@link #verify(boolean, String, Object...)} for details. 220 * 221 * @since 23.1 (varargs overload since 17.0) 222 */ 223 public static void verify( 224 boolean expression, @Nullable String errorMessageTemplate, long p1, char p2) { 225 if (!expression) { 226 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 227 } 228 } 229 230 /** 231 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 232 * custom message otherwise. 233 * 234 * <p>See {@link #verify(boolean, String, Object...)} for details. 235 * 236 * @since 23.1 (varargs overload since 17.0) 237 */ 238 public static void verify( 239 boolean expression, @Nullable String errorMessageTemplate, @Nullable Object p1, char p2) { 240 if (!expression) { 241 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 242 } 243 } 244 245 /** 246 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 247 * custom message otherwise. 248 * 249 * <p>See {@link #verify(boolean, String, Object...)} for details. 250 * 251 * @since 23.1 (varargs overload since 17.0) 252 */ 253 public static void verify( 254 boolean expression, @Nullable String errorMessageTemplate, char p1, int p2) { 255 if (!expression) { 256 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 257 } 258 } 259 260 /** 261 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 262 * custom message otherwise. 263 * 264 * <p>See {@link #verify(boolean, String, Object...)} for details. 265 * 266 * @since 23.1 (varargs overload since 17.0) 267 */ 268 public static void verify( 269 boolean expression, @Nullable String errorMessageTemplate, int p1, int p2) { 270 if (!expression) { 271 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 272 } 273 } 274 275 /** 276 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 277 * custom message otherwise. 278 * 279 * <p>See {@link #verify(boolean, String, Object...)} for details. 280 * 281 * @since 23.1 (varargs overload since 17.0) 282 */ 283 public static void verify( 284 boolean expression, @Nullable String errorMessageTemplate, long p1, int p2) { 285 if (!expression) { 286 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 287 } 288 } 289 290 /** 291 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 292 * custom message otherwise. 293 * 294 * <p>See {@link #verify(boolean, String, Object...)} for details. 295 * 296 * @since 23.1 (varargs overload since 17.0) 297 */ 298 public static void verify( 299 boolean expression, @Nullable String errorMessageTemplate, @Nullable Object p1, int p2) { 300 if (!expression) { 301 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 302 } 303 } 304 305 /** 306 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 307 * custom message otherwise. 308 * 309 * <p>See {@link #verify(boolean, String, Object...)} for details. 310 * 311 * @since 23.1 (varargs overload since 17.0) 312 */ 313 public static void verify( 314 boolean expression, @Nullable String errorMessageTemplate, char p1, long p2) { 315 if (!expression) { 316 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 317 } 318 } 319 320 /** 321 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 322 * custom message otherwise. 323 * 324 * <p>See {@link #verify(boolean, String, Object...)} for details. 325 * 326 * @since 23.1 (varargs overload since 17.0) 327 */ 328 public static void verify( 329 boolean expression, @Nullable String errorMessageTemplate, int p1, long p2) { 330 if (!expression) { 331 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 332 } 333 } 334 335 /** 336 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 337 * custom message otherwise. 338 * 339 * <p>See {@link #verify(boolean, String, Object...)} for details. 340 * 341 * @since 23.1 (varargs overload since 17.0) 342 */ 343 public static void verify( 344 boolean expression, @Nullable String errorMessageTemplate, long p1, long p2) { 345 if (!expression) { 346 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 347 } 348 } 349 350 /** 351 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 352 * custom message otherwise. 353 * 354 * <p>See {@link #verify(boolean, String, Object...)} for details. 355 * 356 * @since 23.1 (varargs overload since 17.0) 357 */ 358 public static void verify( 359 boolean expression, @Nullable String errorMessageTemplate, @Nullable Object p1, long p2) { 360 if (!expression) { 361 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 362 } 363 } 364 365 /** 366 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 367 * custom message otherwise. 368 * 369 * <p>See {@link #verify(boolean, String, Object...)} for details. 370 * 371 * @since 23.1 (varargs overload since 17.0) 372 */ 373 public static void verify( 374 boolean expression, @Nullable String errorMessageTemplate, char p1, @Nullable Object p2) { 375 if (!expression) { 376 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 377 } 378 } 379 380 /** 381 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 382 * custom message otherwise. 383 * 384 * <p>See {@link #verify(boolean, String, Object...)} for details. 385 * 386 * @since 23.1 (varargs overload since 17.0) 387 */ 388 public static void verify( 389 boolean expression, @Nullable String errorMessageTemplate, int p1, @Nullable Object p2) { 390 if (!expression) { 391 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 392 } 393 } 394 395 /** 396 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 397 * custom message otherwise. 398 * 399 * <p>See {@link #verify(boolean, String, Object...)} for details. 400 * 401 * @since 23.1 (varargs overload since 17.0) 402 */ 403 public static void verify( 404 boolean expression, @Nullable String errorMessageTemplate, long p1, @Nullable Object p2) { 405 if (!expression) { 406 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 407 } 408 } 409 410 /** 411 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 412 * custom message otherwise. 413 * 414 * <p>See {@link #verify(boolean, String, Object...)} for details. 415 * 416 * @since 23.1 (varargs overload since 17.0) 417 */ 418 public static void verify( 419 boolean expression, 420 @Nullable String errorMessageTemplate, 421 @Nullable Object p1, 422 @Nullable Object p2) { 423 if (!expression) { 424 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); 425 } 426 } 427 428 /** 429 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 430 * custom message otherwise. 431 * 432 * <p>See {@link #verify(boolean, String, Object...)} for details. 433 * 434 * @since 23.1 (varargs overload since 17.0) 435 */ 436 public static void verify( 437 boolean expression, 438 @Nullable String errorMessageTemplate, 439 @Nullable Object p1, 440 @Nullable Object p2, 441 @Nullable Object p3) { 442 if (!expression) { 443 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3)); 444 } 445 } 446 447 /** 448 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a 449 * custom message otherwise. 450 * 451 * <p>See {@link #verify(boolean, String, Object...)} for details. 452 * 453 * @since 23.1 (varargs overload since 17.0) 454 */ 455 public static void verify( 456 boolean expression, 457 @Nullable String errorMessageTemplate, 458 @Nullable Object p1, 459 @Nullable Object p2, 460 @Nullable Object p3, 461 @Nullable Object p4) { 462 if (!expression) { 463 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4)); 464 } 465 } 466 467 /** 468 * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a default 469 * message otherwise. 470 * 471 * @return {@code reference}, guaranteed to be non-null, for convenience 472 * @throws VerifyException if {@code reference} is {@code null} 473 * @see Preconditions#checkNotNull Preconditions.checkNotNull() 474 */ 475 @CanIgnoreReturnValue 476 public static <T> T verifyNotNull(@Nullable T reference) { 477 return verifyNotNull(reference, "expected a non-null reference"); 478 } 479 480 /** 481 * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a custom 482 * message otherwise. 483 * 484 * @param errorMessageTemplate a template for the exception message should the check fail. The 485 * message is formed by replacing each {@code %s} placeholder in the template with an 486 * argument. These are matched by position - the first {@code %s} gets {@code 487 * errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in 488 * square braces. Unmatched placeholders will be left as-is. 489 * @param errorMessageArgs the arguments to be substituted into the message template. Arguments 490 * are converted to strings using {@link String#valueOf(Object)}. 491 * @return {@code reference}, guaranteed to be non-null, for convenience 492 * @throws VerifyException if {@code reference} is {@code null} 493 * @see Preconditions#checkNotNull Preconditions.checkNotNull() 494 */ 495 @CanIgnoreReturnValue 496 public static <T> T verifyNotNull( 497 @Nullable T reference, 498 @Nullable String errorMessageTemplate, 499 @Nullable Object @Nullable ... errorMessageArgs) { 500 verify(reference != null, errorMessageTemplate, errorMessageArgs); 501 return reference; 502 } 503 504 // TODO(kevinb): consider <T> T verifySingleton(Iterable<T>) to take over for 505 // Iterables.getOnlyElement() 506 507 private Verify() {} 508}