Assert


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