Assert


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 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.jface.text;
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   * <p>
26   * Note that an <code>assert</code> statement is slated to be added to the
27   * Java language in JDK 1.4, rending this class obsolete.
28   * </p>
29   * 
30   * @deprecated As of 3.3, replaced by {@link org.eclipse.core.runtime.Assert}
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           * <p>
43           * This class is not intended to be serialized.
44           * </p>
45           */
46          private static class AssertionFailedException extends RuntimeException   {
47  
48              /**
49               * Serial version UID for this class.
50               * <p>
51               * Note: This class is not intended to be serialized.
52               * </p>
53               * @since 3.1
54               */
55              private static final long serialVersionUID= 3689918374733886002L;
56  
57              /**
58               * Constructs a new exception.
59               */
60              public AssertionFailedException() {
61              }
62  
63              /**
64               * Constructs a new exception with the given message.
65               *
66               * @param detail the detailed message
67               */
68              public AssertionFailedException(String   detail) {
69                  super(detail);
70              }
71          }
72  
73      /* This class is not intended to be instantiated. */
74      private Assert() {
75      }
76  
77      /**
78       * Asserts that an argument is legal. If the given boolean is
79       * not <code>true</code>, an <code>IllegalArgumentException</code>
80       * is thrown.
81       *
82       * @param expression the outcome of the check
83       * @return <code>true</code> if the check passes (does not return
84       *    if the check fails)
85       * @exception IllegalArgumentException if the legality test failed
86       */
87      public static boolean isLegal(boolean expression) {
88          // succeed as quickly as possible
89          if (expression) {
90              return true;
91          }
92          return isLegal(expression, "");//$NON-NLS-1$
93      }
94  
95      /**
96       * Asserts that an argument is legal. If the given boolean is
97       * not <code>true</code>, an <code>IllegalArgumentException</code>
98       * is thrown.
99       * The given message is included in that exception, to aid debugging.
100      *
101      * @param expression the outcome of the check
102      * @param message the message to include in the exception
103      * @return <code>true</code> if the check passes (does not return
104      *    if the check fails)
105      * @exception IllegalArgumentException if the legality test failed
106      */
107     public static boolean isLegal(boolean expression, String   message) {
108         if (!expression)
109             throw new IllegalArgumentException  ("assertion failed; " + message); //$NON-NLS-1$
110         return expression;
111     }
112 
113     /**
114      * Asserts that the given object is not <code>null</code>. If this
115      * is not the case, some kind of unchecked exception is thrown.
116      * <p>
117      * As a general rule, parameters passed to API methods must not be
118      * <code>null</code> unless <b>explicitly</b> allowed in the method's
119      * specification. Similarly, results returned from API methods are never
120      * <code>null</code> unless <b>explicitly</b> allowed in the method's
121      * specification. Implementations are encouraged to make regular use of
122      * <code>Assert.isNotNull</code> to ensure that <code>null</code>
123      * parameters are detected as early as possible.
124      * </p>
125      *
126      * @param object the value to test
127      * @exception RuntimeException an unspecified unchecked exception if the object
128      *   is <code>null</code>
129      */
130     public static void isNotNull(Object   object) {
131         // succeed as quickly as possible
132         if (object != null) {
133             return;
134         }
135         isNotNull(object, "");//$NON-NLS-1$
136     }
137 
138     /**
139      * Asserts that the given object is not <code>null</code>. If this
140      * is not the case, some kind of unchecked exception is thrown.
141      * The given message is included in that exception, to aid debugging.
142      * <p>
143      * As a general rule, parameters passed to API methods must not be
144      * <code>null</code> unless <b>explicitly</b> allowed in the method's
145      * specification. Similarly, results returned from API methods are never
146      * <code>null</code> unless <b>explicitly</b> allowed in the method's
147      * specification. Implementations are encouraged to make regular use of
148      * <code>Assert.isNotNull</code> to ensure that <code>null</code>
149      * parameters are detected as early as possible.
150      * </p>
151      *
152      * @param object the value to test
153      * @param message the message to include in the exception
154      * @exception RuntimeException an unspecified unchecked exception if the object
155      *   is <code>null</code>
156      */
157     public static void isNotNull(Object   object, String   message) {
158         if (object == null)
159             throw new AssertionFailedException("null argument;" + message);//$NON-NLS-1$
160     }
161 
162     /**
163      * Asserts that the given boolean is <code>true</code>. If this
164      * is not the case, some kind of unchecked exception is thrown.
165      *
166      * @param expression the outcome of the check
167      * @return <code>true</code> if the check passes (does not return
168      *    if the check fails)
169      */
170     public static boolean isTrue(boolean expression) {
171         // succeed as quickly as possible
172         if (expression) {
173             return true;
174         }
175         return isTrue(expression, "");//$NON-NLS-1$
176     }
177 
178     /**
179      * Asserts that the given boolean is <code>true</code>. If this
180      * is not the case, some kind of unchecked exception is thrown.
181      * The given message is included in that exception, to aid debugging.
182      *
183      * @param expression the outcome of the check
184      * @param message the message to include in the exception
185      * @return <code>true</code> if the check passes (does not return
186      *    if the check fails)
187      */
188     public static boolean isTrue(boolean expression, String   message) {
189         if (!expression)
190             throw new AssertionFailedException("Assertion failed: "+message);//$NON-NLS-1$
191         return expression;
192     }
193 }
194
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags