Assert


1   /*******************************************************************************
2    * Copyright (c) 2000, 2004 IBM Corporation and others.
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    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.update.internal.core;
12   
13  /**
14   * <code>Assert</code> is useful for for embedding runtime sanity checks
15   * in code. The static predicate methods all test a condition and throw some
16   * type of unchecked exception if the condition does not hold.
17   * <p>
18   * Assertion failure exceptions, like most runtime exceptions, are
19   * thrown when something is misbehaving. Assertion failures are invariably
20   * unspecified behavior; consequently, clients should never rely on
21   * these being thrown (or not thrown). <b>If you find yourself in the
22   * position where you need to catch an assertion failure, you have most 
23   * certainly written your program incorrectly.</b>
24   * </p>
25   */
26  public final class Assert {
27      
28      /**
29       * <code>AssertionFailedException</code> is a runtime exception thrown
30       * by some of the methods in <code>Assert</code>.
31       * <p>
32       * This class is not declared public to prevent some misuses; programs that catch 
33       * or otherwise depend on assertion failures are susceptible to unexpected
34       * breakage when assertions in the code are added or removed.
35       * </p>
36       */
37      private static class AssertionFailedException extends RuntimeException   {
38  
39          private static final long serialVersionUID = 1L;
40  
41          /**
42           * Constructs a new exception.
43           */
44          public AssertionFailedException() {
45          }
46          
47          /**
48           * Constructs a new exception with the given message.
49           */
50          public AssertionFailedException(String   detail) {
51              super(detail);
52          }
53      }
54  /* This class is not intended to be instantiated. */
55  private Assert() {
56  }
57  /**
58   * Asserts that an argument is legal. If the given boolean is
59   * not <code>true</code>, an <code>IllegalArgumentException</code>
60   * is thrown.
61   *
62   * @param expression the outcome of the check
63   * @return <code>true</code> if the check passes (does not return
64   *    if the check fails)
65   * @exception IllegalArgumentException if the legality test failed
66   */
67  public static boolean isLegal(boolean expression) {
68      // succeed as quickly as possible
69      if (expression) {
70          return true;
71      }
72      return isLegal(expression, "");//$NON-NLS-1$
73  }
74  /**
75   * Asserts that an argument is legal. If the given boolean is
76   * not <code>true</code>, an <code>IllegalArgumentException</code>
77   * is thrown.
78   * The given message is included in that exception, to aid debugging.
79   *
80   * @param expression the outcome of the check
81   * @param message the message to include in the exception
82   * @return <code>true</code> if the check passes (does not return
83   *    if the check fails)
84   * @exception IllegalArgumentException if the legality test failed
85   */
86  public static boolean isLegal(boolean expression, String   message) {
87      if (!expression)
88          throw new IllegalArgumentException  (message);
89      return expression;
90  }
91  /**
92   * Asserts that the given object is not <code>null</code>. If this
93   * is not the case, some kind of unchecked exception is thrown.
94   * <p>
95   * As a general rule, parameters passed to API methods must not be
96   * <code>null</code> unless <b>explicitly</b> allowed in the method's
97   * specification. Similarly, results returned from API methods are never
98   * <code>null</code> unless <b>explicitly</b> allowed in the method's
99   * specification. Implementations are encouraged to make regular use of 
100  * <code>Assert.isNotNull</code> to ensure that <code>null</code> 
101  * parameters are detected as early as possible.
102  * </p>
103  * Method throws an unspecified unchecked exception if the object
104  *   is <code>null</code>
105  * @param object the value to test
106  */
107 public static void isNotNull(Object   object) {
108     // succeed as quickly as possible
109     if (object != null) {
110         return;
111     }
112     isNotNull(object, "");//$NON-NLS-1$
113 }
114 /**
115  * Asserts that the given object is not <code>null</code>. If this
116  * is not the case, some kind of unchecked exception is thrown.
117  * The given message is included in that exception, to aid debugging.
118  * <p>
119  * As a general rule, parameters passed to API methods must not be
120  * <code>null</code> unless <b>explicitly</b> allowed in the method's
121  * specification. Similarly, results returned from API methods are never
122  * <code>null</code> unless <b>explicitly</b> allowed in the method's
123  * specification. Implementations are encouraged to make regular use of 
124  * <code>Assert.isNotNull</code> to ensure that <code>null</code> 
125  * parameters are detected as early as possible.
126  * </p>
127  * An unspecified unchecked exception is thrown if the object
128  *   is <code>null</code>
129  * @param object the value to test
130  * @param message the message to include in the exception
131  */
132 public static void isNotNull(Object   object, String   message) {
133     if (object == null)
134         throw new AssertionFailedException("null argument;" + message);//$NON-NLS-1$
135 }
136 /**
137  * Asserts that the given boolean is <code>true</code>. If this
138  * is not the case, some kind of unchecked exception is thrown.
139  *
140  * @param expression the outcome of the check
141  * @return <code>true</code> if the check passes (does not return
142  *    if the check fails)
143  */
144 public static boolean isTrue(boolean expression) {
145     // succeed as quickly as possible
146     if (expression) {
147         return true;
148     }
149     return isTrue(expression, "");//$NON-NLS-1$
150 }
151 /**
152  * Asserts that the given boolean is <code>true</code>. If this
153  * is not the case, some kind of unchecked exception is thrown.
154  * The given message is included in that exception, to aid debugging.
155  *
156  * @param expression the outcome of the check
157  * @param message the message to include in the exception
158  * @return <code>true</code> if the check passes (does not return
159  *    if the check fails)
160  */
161 public static boolean isTrue(boolean expression, String   message) {
162     if (!expression)
163         throw new AssertionFailedException("assertion failed; "+message);//$NON-NLS-1$
164     return expression;
165 }
166 }
167 
168 
169
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags