net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/internal/corext/Assert.java

   1 /*
   2  * (c) Copyright IBM Corp. 2000, 2001.
   3  * All Rights Reserved.
   4  */
   5 package net.sourceforge.phpdt.internal.corext;
   6
   7 // import
   8 // org.phpeclipse.phpdt.internal.corext.refactoring.RefactoringCoreMessages;
   9
  10 /**
  11  * <code>Assert</code> is useful for for embedding runtime sanity checks in
  12  * code. The static predicate methods all test a condition and throw some type
  13  * of unchecked exception if the condition does not hold.
  14  * <p>
  15  * Assertion failure exceptions, like most runtime exceptions, are thrown when
  16  * something is misbehaving. Assertion failures are invariably unspecified
  17  * behavior; consequently, clients should never rely on these being thrown (or
  18  * not thrown). <b>If you find yourself in the position where you need to catch
  19  * an assertion failure, you have most certainly written your program
  20  * incorrectly.</b>
  21  * </p>
  22  * <p>
  23  * Note that an <code>assert</code> statement is slated to be added to the
  24  * Java language in JDK 1.4, rending this class obsolete.
  25  * </p>
  26  */
  27 public final class Assert {
  28
  29         /**
  30          * <code>AssertionFailedException</code> is a runtime exception thrown by
  31          * some of the methods in <code>Assert</code>.
  32          * <p>
  33          * This class is not declared public to prevent some misuses; programs that
  34          * catch or otherwise depend on assertion failures are susceptible to
  35          * unexpected breakage when assertions in the code are added or removed.
  36          * </p>
  37          */
  38         public static class AssertionFailedException extends RuntimeException {
  39
  40                 /**
  41                  * Constructs a new exception.
  42                  */
  43                 public AssertionFailedException() {
  44                 }
  45
  46                 /**
  47                  * Constructs a new exception with the given message.
  48                  */
  49                 public AssertionFailedException(String detail) {
  50                         super(detail);
  51                 }
  52         }
  53
  54         /* This class is not intended to be instantiated. */
  55         private Assert() {
  56         }
  57
  58         /**
  59          * Asserts that the given object is not <code>null</code>. If this is not
  60          * the case, some kind of unchecked exception is thrown.
  61          * <p>
  62          * As a general rule, parameters passed to API methods must not be
  63          * <code>null</code> unless <b>explicitly</b> allowed in the method's
  64          * specification. Similarly, results returned from API methods are never
  65          * <code>null</code> unless <b>explicitly</b> allowed in the method's
  66          * specification. Implementations are encouraged to make regular use of
  67          * <code>Assert.isNotNull</code> to ensure that <code>null</code>
  68          * parameters are detected as early as possible.
  69          * </p>
  70          *
  71          * @param object
  72          *            the value to test
  73          */
  74         public static void isNotNull(Object object) {
  75                 // succeed as quickly as possible
  76                 if (object != null) {
  77                         return;
  78                 }
  79                 isNotNull(object, ""); //$NON-NLS-1$
  80         }
  81
  82         /**
  83          * Asserts that the given object is not <code>null</code>. If this is not
  84          * the case, some kind of unchecked exception is thrown. The given message
  85          * is included in that exception, to aid debugging.
  86          * <p>
  87          * As a general rule, parameters passed to API methods must not be
  88          * <code>null</code> unless <b>explicitly</b> allowed in the method's
  89          * specification. Similarly, results returned from API methods are never
  90          * <code>null</code> unless <b>explicitly</b> allowed in the method's
  91          * specification. Implementations are encouraged to make regular use of
  92          * <code>Assert.isNotNull</code> to ensure that <code>null</code>
  93          * parameters are detected as early as possible.
  94          * </p>
  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 isNotNull(Object object, String message) {
 102                 if (object == null)
 103                         throw new AssertionFailedException("nullargument" + message); //$NON-NLS-1$
 104         }
 105
 106         /**
 107          * Asserts that the given boolean is <code>true</code>. If this is not
 108          * the case, some kind of unchecked exception is thrown.
 109          *
 110          * @param expression
 111          *            the outcome of the check
 112          * @return <code>true</code> if the check passes (does not return if the
 113          *         check fails)
 114          */
 115         public static boolean isTrue(boolean expression) {
 116                 // succeed as quickly as possible
 117                 if (expression) {
 118                         return true;
 119                 }
 120                 return isTrue(expression, ""); //$NON-NLS-1$
 121         }
 122
 123         /**
 124          * Asserts that the given boolean is <code>true</code>. If this is not
 125          * the case, some kind of unchecked exception is thrown. The given message
 126          * is included in that exception, to aid debugging.
 127          *
 128          * @param expression
 129          *            the outcome of the check
 130          * @param message
 131          *            the message to include in the exception
 132          * @return <code>true</code> if the check passes (does not return if the
 133          *         check fails)
 134          */
 135         public static boolean isTrue(boolean expression, String message) {
 136                 if (!expression)
 137                         throw new AssertionFailedException("assertion failed" + message); //$NON-NLS-1$
 138                 return expression;
 139         }
 140
 141 }