// Routines used for testing assertions. // (c) 2001 duane a. bailey package structure; /** * A library of assertion testing and debugging procedures. *
* This class of static methods provides basic assertion testing facilities. * An assertion is a condition that is expected to be true at a certain * point in the code. Each of the assertion-based routines in this class * perform a verification of the condition, and do nothing (aside from * testing side-effects) if the condition holds. If the condition fails, * however, the assertion throws an exception and prints the associated * message, that describes the condition that failed. Basic support is * provided for testing general conditions, and pre- and postconditions. * There is also a facility for throwing a failed condition for code that * should not be executed. *
* Features similar to assertion testing are expected to be incorporated * into the Java 2 language beginning in SDK 1.4. *
* The debugging facilities provide control that is slightly improved
* over print statements.
*
* @author, 2001 duane a. bailey
* @version $Id: Assert.java,v 1.1 2005/09/22 22:01:13 terescoj Exp $
* @since Java Structures, 1st edition
*/
//+interface
public class Assert
{
//-interface
/**
* The current level of debugging; generally 0 upward.
* A level of 0 is generally considered off.
*/
protected static int debugLevel = 0;
/**
* @pre An Assert cannot be constructed
*/
private Assert()
{
Assert.fail("Attempt to construct an Assert!?");
}
/**
* Increase the verbosity of the debugging messages.
*
* @post debugging level is increased
*/
public static void debugging()
{
debugLevel++;
}
/**
* Explictly set the debugging level (0 = none)
*
* @param level the desired level of verosity
* @pre level >= 0
* @post the level of debugging is set to level
* @return the old level
*/
public static int debugLevel(int level)
{
int oldLevel = debugLevel;
debugLevel = level;
return oldLevel;
}
/**
* Set up a level 1 debugging message.
*
* @param message a string to be printed if debugging level is 1 or more
* @post prints message if the debugging level is 1 or more
*/
public static void debug(String message)
{
debug(1,message);
}
/**
* Set up a debugging message at a specific level.
*
* @param level the level that triggers the printing of message
* @param message the message to be printed at the desired level
* @pre level >= 1 and message is non-null
* @post prints message if debugging level is level
or more
*/
public static void debug(int level,String message)
{
if (level <= debugLevel) System.err.println(message);
}
//+interface
//+pre
/**
* Test a precondition. If the assertion fails the message
* indicates that a precondition failed. A precondition is something
* you require to be true for the method to be executed correctly.
*
* @param test A boolean expression describing precondition.
* @param message A string describing precondition.
* @pre Result of precondition test
* @post Does nothing if test true, otherwise abort w/message
*/
static public void pre(boolean test, String message)
//-interface
{
if (test == false) throw new FailedPrecondition(message);
}
//-pre
//+interface
//+post
/**
* Test a postcondition. If the assertion fails, the message
* indicates that a postcondition failed. A postcondition is
* something expected to be true after a method invocation,
* provided the preconditions are met.
*
* @param test A boolean expression describing postcondition.
* @param message A string describing postcondition.
* @pre Result of postcondition test
* @post Does nothing if test true, otherwise abort w/message
*/
static public void post(boolean test, String message)
//-interface
{
if (test == false) {
throw new FailedPostcondition(message);
}
}
//-post
//+interface
//+condition
/**
* Test a general condition. If the assertion fails, the message
* indicates that a general condition failed. The condition may
* be anything that needs to be verified during the course of program
* execution.
*
* @param test A boolean expression describing the condition.
* @param message A string describing the condition.
* @pre result of general condition test
* @post does nothing if test true, otherwise abort w/message
*/
static public void condition(boolean test, String message)
//-interface
{
if (test == false) throw new FailedAssertion(message);
}
//-condition
//+interface
//+condition
/**
* Test a loop invariant. If the assertion fails, the message
* indicates that an invariant failed. The condition may
* be anything that needs to be verified during the course of program
* execution.
*
* @param test A boolean expression describing the condition.
* @param message A string describing the condition.
* @pre result of an invariant test
* @post does nothing if test true, otherwise abort w/message
*/
static public void invariant(boolean test, String message)
//-interface
{
if (test == false) throw new FailedInvariant(message);
}
//-condition
//+interface
//+fail
/**
* Indicate certain failure. Stops the program with a message
* indicating why failure occurred.
*
* @param message A string describing the reason for failure.
* @post Throws error with message
*/
static public void fail(String message)
//-interface
{
throw new FailedAssertion(message);
}
//-fail
//+interface
}
//-interface