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 *******************************************************************************/
11package org.eclipse.wb.internal.core.utils.check;
12
13import 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 */
27public 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