1 /******************************************************************************* 2 * Copyright (c) 2011 Google, Inc. 3 * All rights reserved. This program and the accompanying materials 4 * are made available under the terms of the Eclipse Public License v1.0 5 * which accompanies this distribution, and is available at 6 * http://www.eclipse.org/legal/epl-v10.html 7 * 8 * Contributors: 9 * Google, Inc. - initial API and implementation 10 *******************************************************************************/ 11 package org.eclipse.wb.internal.core.utils.check; 12 13 import java.text.MessageFormat; 14 15 /** 16 * <code>Assert</code> is useful for for embedding runtime sanity checks in code. The predicate 17 * methods all test a condition and throw some type of unchecked exception if the condition does not 18 * hold. 19 * <p> 20 * Assertion failure exceptions, like most runtime exceptions, are thrown when something is 21 * misbehaving. Assertion failures are invariably unspecified behavior; consequently, clients should 22 * never rely on these being thrown (and certainly should not being catching them specifically). 23 * 24 * @author scheglov_ke 25 * @coverage core.util 26 */ 27 public final class Assert { 28 //////////////////////////////////////////////////////////////////////////// 29 // 30 // Constructor 31 // 32 //////////////////////////////////////////////////////////////////////////// 33 private Assert() { 34 } 35 36 //////////////////////////////////////////////////////////////////////////// 37 // 38 // "legal" 39 // 40 //////////////////////////////////////////////////////////////////////////// 41 /** 42 * Asserts that an argument is legal. If the given boolean is not <code>true</code>, an 43 * <code>IllegalArgumentException</code> is thrown. 44 * 45 * @param expression 46 * the boolean expression of the check 47 * @return <code>true</code> if the check passes (does not return if the check fails) 48 * @exception IllegalArgumentException 49 * if the legality test failed 50 */ 51 public static boolean isLegal(boolean expression) { 52 return isLegal(expression, ""); //$NON-NLS-1$ 53 } 54 55 /** 56 * Asserts that an argument is legal. If the given boolean is not <code>true</code>, an 57 * <code>IllegalArgumentException</code> is thrown. The given message is included in that 58 * exception, to aid debugging. 59 * 60 * @param expression 61 * the boolean expression of the check 62 * @param message 63 * the message to include in the exception 64 * @return <code>true</code> if the check passes (does not return if the check fails) 65 * @exception IllegalArgumentException 66 * if the legality test failed 67 */ 68 public static boolean isLegal(boolean expression, String message) { 69 if (!expression) { 70 throw new IllegalArgumentException(message); 71 } 72 return expression; 73 } 74 75 //////////////////////////////////////////////////////////////////////////// 76 // 77 // "null" 78 // 79 //////////////////////////////////////////////////////////////////////////// 80 /** 81 * Asserts that the given object is <code>null</code>. If this is not the case, some kind of 82 * unchecked exception is thrown. 83 * 84 * @param object 85 * the value to test 86 */ 87 public static void isNull(Object object) { 88 isNull(object, ""); //$NON-NLS-1$ 89 } 90 91 /** 92 * Asserts that the given object is <code>null</code>. If this is not the case, some kind of 93 * unchecked exception is thrown. The given message is included in that exception, to aid 94 * debugging. 95 * 96 * @param object 97 * the value to test 98 * @param message 99 * the message to include in the exception 100 */ 101 public static void isNull(Object object, String message) { 102 if (object != null) { 103 throw new AssertionFailedException("null argument expected: " + message); //$NON-NLS-1$ 104 } 105 } 106 107 /** 108 * Asserts that the given object is not <code>null</code>. If this is not the case, some kind of 109 * unchecked exception is thrown. The given message is included in that exception, to aid 110 * debugging. 111 * 112 * @param object 113 * the value to test 114 * @param errorFormat 115 * the format of error message to produce if the check fails, as expected by 116 * {@link String#format(String, Object...)}. For example 117 * <code>"Execution flow problem. %s expected, but %s found."</code>. 118 * @param args 119 * the arguments for {@code errorFormat} 120 */ 121 public static void isNull(Object object, String errorFormat, Object... args) { 122 if (object != null) { 123 fail("null argument expected: " + String.format(errorFormat, args)); //$NON-NLS-1$ 124 } 125 } 126 127 /** 128 * @param errorFormat 129 * the format of error message suitable for {@link MessageFormat}. 130 * @param errorFormat 131 * the format of error message to produce if the check fails, as expected by 132 * {@link MessageFormat}. For example 133 * <code>"Execution flow problem. {0} expected, but {1} found."</code>. 134 */ 135 public static void isNull2(Object object, String errorFormat, Object... args) { 136 if (object != null) { 137 String message = "null argument expected: " + MessageFormat.format(errorFormat, args); //$NON-NLS-1$ 138 fail(message); 139 } 140 } 141 142 //////////////////////////////////////////////////////////////////////////// 143 // 144 // not "null" 145 // 146 //////////////////////////////////////////////////////////////////////////// 147 /** 148 * Asserts that the given object is not <code>null</code>. If this is not the case, some kind of 149 * unchecked exception is thrown. 150 * 151 * @param object 152 * the value to test 153 */ 154 public static void isNotNull(Object object) { 155 isNotNull(object, ""); //$NON-NLS-1$ 156 } 157 158 /** 159 * Asserts that the given object is not <code>null</code>. If this is not the case, some kind of 160 * unchecked exception is thrown. The given message is included in that exception, to aid 161 * debugging. 162 * 163 * @param object 164 * the value to test 165 * @param message 166 * the message to include in the exception 167 */ 168 public static void isNotNull(Object object, String message) { 169 if (object == null) { 170 fail("null argument: " + message); //$NON-NLS-1$ 171 } 172 } 173 174 /** 175 * Asserts that the given object is not <code>null</code>. If this is not the case, some kind of 176 * unchecked exception is thrown. The given message is included in that exception, to aid 177 * debugging. 178 * 179 * @param object 180 * the value to test 181 * @param errorFormat 182 * the format of error message to produce if the check fails, as expected by 183 * {@link String#format(String, Object...)}. For example 184 * <code>"Execution flow problem. %s expected, but %s found."</code>. 185 * @param args 186 * the arguments for {@code errorFormat} 187 */ 188 public static void isNotNull(Object object, String errorFormat, Object... args) { 189 if (object == null) { 190 fail("null argument: " + String.format(errorFormat, args)); //$NON-NLS-1$ 191 } 192 } 193 194 /** 195 * @param errorFormat 196 * the format of error message suitable for {@link MessageFormat}. 197 * @param errorFormat 198 * the format of error message to produce if the check fails, as expected by 199 * {@link MessageFormat}. For example 200 * <code>"Execution flow problem. {0} expected, but {1} found."</code>. 201 */ 202 public static void isNotNull2(Object object, String errorFormat, Object... args) { 203 if (object == null) { 204 String message = "null argument: " + MessageFormat.format(errorFormat, args); //$NON-NLS-1$ 205 fail(message); 206 } 207 } 208 209 //////////////////////////////////////////////////////////////////////////// 210 // 211 // Fail 212 // 213 //////////////////////////////////////////////////////////////////////////// 214 /** 215 * Fails with given message. 216 * 217 * @param message 218 * the message to include in the exception 219 */ 220 public static void fail(String message) { 221 throw new AssertionFailedException(message); 222 } 223 224 /** 225 * @param errorFormat 226 * the format of error message to produce if the check fails, as expected by 227 * {@link MessageFormat}. For example <code>"{0} expected, but {1} found."</code>. 228 */ 229 public static void fail(String errorFormat, Object... args) { 230 String message = MessageFormat.format(errorFormat, args); 231 throw new AssertionFailedException(message); 232 } 233 234 //////////////////////////////////////////////////////////////////////////// 235 // 236 // "true" 237 // 238 //////////////////////////////////////////////////////////////////////////// 239 /** 240 * Asserts that the given boolean is <code>true</code>. If this is not the case, some kind of 241 * unchecked exception is thrown. 242 * 243 * @param expression 244 * the boolean expression of the check 245 * @return <code>true</code> if the check passes (does not return if the check fails) 246 */ 247 public static boolean isTrue(boolean expression) { 248 return isTrue(expression, ""); //$NON-NLS-1$ 249 } 250 251 /** 252 * Asserts that the given boolean is <code>true</code>. If this is not the case, some kind of 253 * unchecked exception is thrown. The given message is included in that exception, to aid 254 * debugging. 255 * 256 * @param expression 257 * the boolean expression of the check 258 * @param message 259 * the message to include in the exception 260 * @return <code>true</code> if the check passes (does not return if the check fails) 261 */ 262 public static boolean isTrue(boolean expression, String message) { 263 if (!expression) { 264 fail("assertion failed: " + message); //$NON-NLS-1$ 265 } 266 return expression; 267 } 268 269 /** 270 * Asserts that the given boolean is <code>true</code>. If this is not the case, some kind of 271 * unchecked exception is thrown. The given message is included in that exception, to aid 272 * debugging. 273 * 274 * @param expression 275 * the boolean expression of the check 276 * @param errorFormat 277 * the format of error message to produce if the check fails, as expected by 278 * {@link String#format(String, Object...)}. For example 279 * <code>"Execution flow problem. %s expected, but %s found."</code>. 280 * @param args 281 * the arguments for {@code errorFormat} 282 * @return <code>true</code> if the check passes (does not return if the check fails) 283 */ 284 public static boolean isTrue(boolean expression, String errorFormat, Object... args) { 285 if (!expression) { 286 fail("assertion failed: " + String.format(errorFormat, args)); //$NON-NLS-1$ 287 } 288 return expression; 289 } 290 291 /** 292 * Asserts that the given boolean is <code>true</code>. If this is not the case, some kind of 293 * unchecked exception is thrown. The given message is included in that exception, to aid 294 * debugging. 295 * 296 * @param expression 297 * the boolean expression to check. 298 * @param errorFormat 299 * the format of error message to produce if the check fails, as expected by 300 * {@link MessageFormat}. For example <code>"{0} expected, but {1} found."</code>. 301 */ 302 public static boolean isTrue2(boolean expression, String errorFormat, Object... args) { 303 if (!expression) { 304 fail(errorFormat, args); 305 } 306 return expression; 307 } 308 309 //////////////////////////////////////////////////////////////////////////// 310 // 311 // equals 312 // 313 //////////////////////////////////////////////////////////////////////////// 314 /** 315 * Asserts that given actual value equals expected value. If this is not the case, some kind of 316 * unchecked exception is thrown. 317 * 318 * @param expected 319 * the expected value 320 * @param the 321 * actual value to check 322 */ 323 public static void equals(int expected, int actual) { 324 equals(expected, actual, expected + " expected, but " + actual + " found"); 325 } 326 327 /** 328 * Asserts that given actual value equals expected value. If this is not the case, some kind of 329 * unchecked exception is thrown. The given message is included in that exception, to aid 330 * debugging. 331 * 332 * @param expected 333 * the expected value 334 * @param the 335 * actual value to check 336 * @param message 337 * the message to include in the exception 338 */ 339 public static void equals(int expected, int actual, String message) { 340 if (expected != actual) { 341 fail("assertation failed: " + message); 342 } 343 } 344 345 //////////////////////////////////////////////////////////////////////////// 346 // 347 // instanceOf 348 // 349 //////////////////////////////////////////////////////////////////////////// 350 /** 351 * Asserts that given object is not <code>null</code> and has class compatible with given. 352 */ 353 public static void instanceOf(Class<?> expectedClass, Object o) { 354 if (o == null) { 355 fail(expectedClass.getName() + " expected, but 'null' found."); 356 } 357 if (!expectedClass.isAssignableFrom(o.getClass())) { 358 fail(expectedClass.getName() + " expected, but " + o.getClass().getName() + " found."); 359 } 360 } 361 } 362
