rev 13428 : jfr backport

   1 /*
   2  * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.
   8  *
   9  * This code is distributed in the hope that it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * version 2 for more details (a copy is included in the LICENSE file that
  13  * accompanied this code).
  14  *
  15  * You should have received a copy of the GNU General Public License version
  16  * 2 along with this work; if not, write to the Free Software Foundation,
  17  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  18  *
  19  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  20  * or visit www.oracle.com if you need additional information or have any
  21  * questions.
  22  */
  23 
  24 package jdk.testlibrary;
  25 
  26 import java.util.Objects;
  27 
  28 /**
  29  * Asserts that can be used for verifying assumptions in tests.
  30  *
  31  * An assertion will throw a {@link RuntimeException} if the assertion isn't
  32  * valid.  All the asserts can be imported into a test by using a static
  33  * import:
  34  *
  35  * <pre>
  36  * {@code
  37  * import static com.oracle.java.testlibrary.Asserts.*;
  38  * }
  39  *
  40  * Always provide a message describing the assumption if the line number of the
  41  * failing assertion isn't enough to understand why the assumption failed. For
  42  * example, if the assertion is in a loop or in a method that is called
  43  * multiple times, then the line number won't provide enough context to
  44  * understand the failure.
  45  * </pre>
  46  */
  47 public class Asserts {
  48 
  49     /**
  50      * Shorthand for {@link #assertLessThan(T, T)}.
  51      *
  52      * @see #assertLessThan(T, T)
  53      */
  54     public static <T extends Comparable<T>> void assertLT(T lhs, T rhs) {
  55         assertLessThan(lhs, rhs);
  56     }
  57 
  58     /**
  59      * Shorthand for {@link #assertLessThan(T, T, String)}.
  60      *
  61      * @see #assertLessThan(T, T, String)
  62      */
  63     public static <T extends Comparable<T>> void assertLT(T lhs, T rhs, String msg) {
  64         assertLessThan(lhs, rhs, msg);
  65     }
  66 
  67     /**
  68      * Calls {@link #assertLessThan(T, T, String)} with a default message.
  69      *
  70      * @see #assertLessThan(T, T, String)
  71      */
  72     public static <T extends Comparable<T>> void assertLessThan(T lhs, T rhs) {
  73         String msg = "Expected that " + format(lhs) + " < " + format(rhs);
  74         assertLessThan(lhs, rhs, msg);
  75     }
  76 
  77     /**
  78      * Asserts that {@code lhs} is less than {@code rhs}.
  79      *
  80      * @param lhs The left hand side of the comparison.
  81      * @param rhs The right hand side of the comparison.
  82      * @param msg A description of the assumption.
  83      * @throws RuntimeException if the assertion isn't valid.
  84      */
  85     public static <T extends Comparable<T>>void assertLessThan(T lhs, T rhs, String msg) {
  86         assertTrue(compare(lhs, rhs, msg) < 0, msg);
  87     }
  88 
  89     /**
  90      * Shorthand for {@link #assertLessThanOrEqual(T, T)}.
  91      *
  92      * @see #assertLessThanOrEqual(T, T)
  93      */
  94     public static <T extends Comparable<T>> void assertLTE(T lhs, T rhs) {
  95         assertLessThanOrEqual(lhs, rhs);
  96     }
  97 
  98     /**
  99      * Shorthand for {@link #assertLessThanOrEqual(T, T, String)}.
 100      *
 101      * @see #assertLessThanOrEqual(T, T, String)
 102      */
 103     public static <T extends Comparable<T>> void assertLTE(T lhs, T rhs, String msg) {
 104         assertLessThanOrEqual(lhs, rhs, msg);
 105     }
 106 
 107     /**
 108      * Calls {@link #assertLessThanOrEqual(T, T, String)} with a default message.
 109      *
 110      * @see #assertLessThanOrEqual(T, T, String)
 111      */
 112     public static <T extends Comparable<T>> void assertLessThanOrEqual(T lhs, T rhs) {
 113         String msg = "Expected that " + format(lhs) + " <= " + format(rhs);
 114         assertLessThanOrEqual(lhs, rhs, msg);
 115     }
 116 
 117     /**
 118      * Asserts that {@code lhs} is less than or equal to {@code rhs}.
 119      *
 120      * @param lhs The left hand side of the comparison.
 121      * @param rhs The right hand side of the comparison.
 122      * @param msg A description of the assumption.
 123      * @throws RuntimeException if the assertion isn't valid.
 124      */
 125     public static <T extends Comparable<T>> void assertLessThanOrEqual(T lhs, T rhs, String msg) {
 126         assertTrue(compare(lhs, rhs, msg) <= 0, msg);
 127     }
 128 
 129     /**
 130      * Shorthand for {@link #assertEquals(T, T)}.
 131      *
 132      * @see #assertEquals(T, T)
 133      */
 134     public static void assertEQ(Object lhs, Object rhs) {
 135         assertEquals(lhs, rhs);
 136     }
 137 
 138     /**
 139      * Shorthand for {@link #assertEquals(T, T, String)}.
 140      *
 141      * @see #assertEquals(T, T, String)
 142      */
 143     public static void assertEQ(Object lhs, Object rhs, String msg) {
 144         assertEquals(lhs, rhs, msg);
 145     }
 146 
 147     /**
 148      * Calls {@link #assertEquals(T, T, String)} with a default message.
 149      *
 150      * @see #assertEquals(T, T, String)
 151      */
 152     public static void assertEquals(Object lhs, Object rhs) {
 153         String msg = "Expected " + format(lhs) + " to equal " + format(rhs);
 154         assertEquals(lhs, rhs, msg);
 155     }
 156 
 157     /**
 158      * Asserts that {@code lhs} is equal to {@code rhs}.
 159      *
 160      * @param lhs The left hand side of the comparison.
 161      * @param rhs The right hand side of the comparison.
 162      * @param msg A description of the assumption.
 163      * @throws RuntimeException if the assertion isn't valid.
 164      */
 165     public static void assertEquals(Object lhs, Object rhs, String msg) {
 166         if (lhs == null) {
 167             if (rhs != null) {
 168                 error(msg);
 169             }
 170         } else {
 171             assertTrue(lhs.equals(rhs), msg);
 172         }
 173     }
 174 
 175     /**
 176      * Calls {@link #assertSame(java.lang.Object, java.lang.Object, java.lang.String)} with a default message.
 177      *
 178      * @param lhs The left hand side of the comparison.
 179      * @param rhs The right hand side of the comparison.
 180      * @see #assertSame(Object, Object, String)
 181      */
 182     public static void assertSame(Object lhs, Object rhs) {
 183         assertSame(lhs, rhs, null);
 184     }
 185 
 186     /**
 187      * Asserts that {@code lhs} is the same as {@code rhs}.
 188      *
 189      * @param lhs The left hand side of the comparison.
 190      * @param rhs The right hand side of the comparison.
 191      * @param msg A description of the assumption; {@code null} for a default message.
 192      * @throws RuntimeException if the assertion is not true.
 193      */
 194     public static void assertSame(Object lhs, Object rhs, String msg) {
 195         if (lhs != rhs) {
 196             msg = Objects.toString(msg, "assertSame")
 197                     + ": expected " + Objects.toString(lhs)
 198                     + " to equal " + Objects.toString(rhs);
 199             throw new RuntimeException(msg);
 200         }
 201     }
 202 
 203     /**
 204      * Shorthand for {@link #assertGreaterThanOrEqual(T, T)}.
 205      *
 206      * @see #assertGreaterThanOrEqual(T, T)
 207      */
 208     public static <T extends Comparable<T>> void assertGTE(T lhs, T rhs) {
 209         assertGreaterThanOrEqual(lhs, rhs);
 210     }
 211 
 212     /**
 213      * Shorthand for {@link #assertGreaterThanOrEqual(T, T, String)}.
 214      *
 215      * @see #assertGreaterThanOrEqual(T, T, String)
 216      */
 217     public static <T extends Comparable<T>> void assertGTE(T lhs, T rhs, String msg) {
 218         assertGreaterThanOrEqual(lhs, rhs, msg);
 219     }
 220 
 221     /**
 222      * Calls {@link #assertGreaterThanOrEqual(T, T, String)} with a default message.
 223      *
 224      * @see #assertGreaterThanOrEqual(T, T, String)
 225      */
 226     public static <T extends Comparable<T>> void assertGreaterThanOrEqual(T lhs, T rhs) {
 227         String msg = "Expected that " + format(lhs) + " >= " + format(rhs);
 228         assertGreaterThanOrEqual(lhs, rhs, msg);
 229     }
 230 
 231     /**
 232      * Asserts that {@code lhs} is greater than or equal to {@code rhs}.
 233      *
 234      * @param lhs The left hand side of the comparison.
 235      * @param rhs The right hand side of the comparison.
 236      * @param msg A description of the assumption.
 237      * @throws RuntimeException if the assertion isn't valid.
 238      */
 239     public static <T extends Comparable<T>> void assertGreaterThanOrEqual(T lhs, T rhs, String msg) {
 240         assertTrue(compare(lhs, rhs, msg) >= 0, msg);
 241     }
 242 
 243     /**
 244      * Shorthand for {@link #assertGreaterThan(T, T)}.
 245      *
 246      * @see #assertGreaterThan(T, T)
 247      */
 248     public static <T extends Comparable<T>> void assertGT(T lhs, T rhs) {
 249         assertGreaterThan(lhs, rhs);
 250     }
 251 
 252     /**
 253      * Shorthand for {@link #assertGreaterThan(T, T, String)}.
 254      *
 255      * @see #assertGreaterThan(T, T, String)
 256      */
 257     public static <T extends Comparable<T>> void assertGT(T lhs, T rhs, String msg) {
 258         assertGreaterThan(lhs, rhs, msg);
 259     }
 260 
 261     /**
 262      * Calls {@link #assertGreaterThan(T, T, String)} with a default message.
 263      *
 264      * @see #assertGreaterThan(T, T, String)
 265      */
 266     public static <T extends Comparable<T>> void assertGreaterThan(T lhs, T rhs) {
 267         String msg = "Expected that " + format(lhs) + " > " + format(rhs);
 268         assertGreaterThan(lhs, rhs, msg);
 269     }
 270 
 271     /**
 272      * Asserts that {@code lhs} is greater than {@code rhs}.
 273      *
 274      * @param lhs The left hand side of the comparison.
 275      * @param rhs The right hand side of the comparison.
 276      * @param msg A description of the assumption.
 277      * @throws RuntimeException if the assertion isn't valid.
 278      */
 279     public static <T extends Comparable<T>> void assertGreaterThan(T lhs, T rhs, String msg) {
 280         assertTrue(compare(lhs, rhs, msg) > 0, msg);
 281     }
 282 
 283     /**
 284      * Shorthand for {@link #assertNotEquals(T, T)}.
 285      *
 286      * @see #assertNotEquals(T, T)
 287      */
 288     public static void assertNE(Object lhs, Object rhs) {
 289         assertNotEquals(lhs, rhs);
 290     }
 291 
 292     /**
 293      * Shorthand for {@link #assertNotEquals(T, T, String)}.
 294      *
 295      * @see #assertNotEquals(T, T, String)
 296      */
 297     public static void assertNE(Object lhs, Object rhs, String msg) {
 298         assertNotEquals(lhs, rhs, msg);
 299     }
 300 
 301     /**
 302      * Calls {@link #assertNotEquals(T, T, String)} with a default message.
 303      *
 304      * @see #assertNotEquals(T, T, String)
 305      */
 306     public static void assertNotEquals(Object lhs, Object rhs) {
 307         String msg = "Expected " + format(lhs) + " to not equal " + format(rhs);
 308         assertNotEquals(lhs, rhs, msg);
 309     }
 310 
 311     /**
 312      * Asserts that {@code lhs} is not equal to {@code rhs}.
 313      *
 314      * @param lhs The left hand side of the comparison.
 315      * @param rhs The right hand side of the comparison.
 316      * @param msg A description of the assumption.
 317      * @throws RuntimeException if the assertion isn't valid.
 318      */
 319     public static void assertNotEquals(Object lhs, Object rhs, String msg) {
 320         if (lhs == null) {
 321             if (rhs == null) {
 322                 error(msg);
 323             }
 324         } else {
 325             assertFalse(lhs.equals(rhs), msg);
 326         }
 327     }
 328 
 329     /**
 330      * Calls {@link #assertNull(Object, String)} with a default message.
 331      *
 332      * @see #assertNull(Object, String)
 333      */
 334     public static void assertNull(Object o) {
 335         assertNull(o, "Expected " + format(o) + " to be null");
 336     }
 337 
 338     /**
 339      * Asserts that {@code o} is null.
 340      *
 341      * @param o The reference assumed to be null.
 342      * @param msg A description of the assumption.
 343      * @throws RuntimeException if the assertion isn't valid.
 344      */
 345     public static void assertNull(Object o, String msg) {
 346         assertEquals(o, null, msg);
 347     }
 348 
 349     /**
 350      * Calls {@link #assertNotNull(Object, String)} with a default message.
 351      *
 352      * @see #assertNotNull(Object, String)
 353      */
 354     public static void assertNotNull(Object o) {
 355         assertNotNull(o, "Expected non null reference");
 356     }
 357 
 358     /**
 359      * Asserts that {@code o} is <i>not</i> null.
 360      *
 361      * @param o The reference assumed <i>not</i> to be null,
 362      * @param msg A description of the assumption.
 363      * @throws RuntimeException if the assertion isn't valid.
 364      */
 365     public static void assertNotNull(Object o, String msg) {
 366         assertNotEquals(o, null, msg);
 367     }
 368 
 369     /**
 370      * Calls {@link #assertFalse(boolean, String)} with a default message.
 371      *
 372      * @see #assertFalse(boolean, String)
 373      */
 374     public static void assertFalse(boolean value) {
 375         assertFalse(value, "Expected value to be false");
 376     }
 377 
 378     /**
 379      * Asserts that {@code value} is {@code false}.
 380      *
 381      * @param value The value assumed to be false.
 382      * @param msg A description of the assumption.
 383      * @throws RuntimeException if the assertion isn't valid.
 384      */
 385     public static void assertFalse(boolean value, String msg) {
 386         assertTrue(!value, msg);
 387     }
 388 
 389     /**
 390      * Calls {@link #assertTrue(boolean, String)} with a default message.
 391      *
 392      * @see #assertTrue(boolean, String)
 393      */
 394     public static void assertTrue(boolean value) {
 395         assertTrue(value, "Expected value to be true");
 396     }
 397 
 398     /**
 399      * Asserts that {@code value} is {@code true}.
 400      *
 401      * @param value The value assumed to be true.
 402      * @param msg A description of the assumption.
 403      * @throws RuntimeException if the assertion isn't valid.
 404      */
 405     public static void assertTrue(boolean value, String msg) {
 406         if (!value) {
 407             error(msg);
 408         }
 409     }
 410 
 411     /**
 412      * Fails a test with the default message.
 413      */
 414     public static void fail() {
 415         error("Test failed");
 416     }
 417 
 418     /**
 419      * Fails a test with the given message.
 420      *
 421      * @param msg A description of the failure.
 422      */
 423     public static void fail(String msg) {
 424         error(msg);
 425     }
 426 
 427     private static <T extends Comparable<T>> int compare(T lhs, T rhs, String msg) {
 428         assertNotNull(lhs, msg);
 429         assertNotNull(rhs, msg);
 430         return lhs.compareTo(rhs);
 431     }
 432 
 433     private static String format(Object o) {
 434         return o == null? "null" : o.toString();
 435     }
 436 
 437     private static void error(String msg) {
 438         throw new RuntimeException(msg);
 439     }
 440 
 441 }
--- EOF ---