Assertions

When implementing and debugging a class, it is sometimes useful to state conditions that should be true at a particular point in a method. These conditions, called assertions, help ensure a program's validity by catching potential bugs and identifying possible logic errors during development. Preconditions and postconditions are two types of assertions. Preconditions are assertions about a program's state when a method is invoked, and postconditions are assertions about a program's state after a method finishes.

While assertions can be stated as comments to guide the programmer during development, Java includes two versions of the assert statement for validating assertions programatically. The assert statement evaluates a boolean expression and determines whether it is true or false. The first form of the assert statement is

 assert expression;

This statement evaluates expression and throws an AssertionError if the expression is false. The second form is

 assert expression1 : expression2;

This statement evaluates expression1 and throws an AssertionError with expression2 as the error message if expression1 is false.

You can use assertions to programmatically implement preconditions and postconditions or to verify any other intermediate states that help you ensure your code is working correctly. The example in Fig. 13.9 demonstrates the functionality of the assert statement. Line 11 prompts the user to enter a number between 0 and 10, then line 12 reads the number from the command line. The assert statement on line 15 determines whether the user entered a number within the valid range. If the user entered a number that is out of range, then the program reports an error. Otherwise, the program proceeds normally.

Figure 13.9. Checking with assert that a value is within range.

 1 // Fig. 13.9: AssertTest.java
 2 // Demonstrates the assert statement
 3 import java.util.Scanner;
 4
 5 public class AssertTest
 6 {
 7 public static void main( String args[] )
 8 {
 9 Scanner input = new Scanner( System.in );
10
11 System.out.print( "Enter a number between 0 and 10: " );
12 int number = input.nextInt();
13
14 // assert that the absolute value is >= 0
15 assert ( number >= 0 && number <= 10 ) : "bad number: " + number;
16
17 System.out.printf( "You entered %d
", number );
18 } // end main
19 } // end class AssertTest

 

Enter a number between 0 and 10: 5
You entered 5

 

 

Enter a number between 0 and 10: 50
Exception in thread "main" java.lang.AssertionError: bad number: 50
 at AssertTest.main(AssertTest.java:15)

 

Assertions are primarily used by the programmer for debugging and identifying logic errors in a application. By default, assertions are disabled when executing a program because they reduce performance and are unnecessary for the program's user. To enable assertions at runtime, use the -ea command-line option when to the java command. To execute the program in Fig. 13.9 with assertions enabled, type

java -ea AssertTest

You should not encounter any AssertionErrors through normal execution of a properly written program. Such errors should only indicate bugs in the implementation. As a result, you should never catch an AssertionError. Rather, you should allow the program to terminate when the error occurs, so you can see the error message, then you should locate and fix the source of the problem. Since application users can choose not to enable assertions at runtime, you should not use the assert statement to indicate runtime problems in production code. Rather, you should use the exception mechanism for this purpose.