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