How do I enable assertions?
Author: Deron Eriksson
Description: This tutorial describes how to enable assertions in Java.
Tutorial created using: Windows XP || JDK 1.5.0_09 || Eclipse Web Tools Platform 2.0 (Eclipse 3.3.0)


Assertions can be used in JavaSW to test for the validity of certain conditions in a Java application. If a particular assertion condition is found to be false, an AssertionError will be thrown. Notice that this is an Error and not an Exception. Errors are unchecked, so you don't need to catch them. Typically with assertions, you don't catch them and you let the application terminate as a result of throwing the AssertionError. However, the AssertTest class catches the AssertionError.

AssertTest.java

package test;

public class AssertTest {

	public static void main(String[] args) {
		try {
			System.out.println("testing...");
			assert true : "Condition is true, so we won't see this";
			assert false : "If assertions are on, we'll see this";
		} catch (AssertionError e) {
			e.printStackTrace();
		}
	}
}

Normally, assertions are off when we have the Java interpreter execute a class. So, the assert code is basically ignored when we execute a class normally:

java test.AssertTest

C:\projects\workspace\testing\bin>java test.AssertTest
testing...

Assertions can be enabled by including the -ea option (or -enableassertions option) to the Java interpreter. If we include this option when we execute AssertTest, we see the following:

java -ea test.AssertTest

C:\projects\workspace\testing\bin>java -ea test.AssertTest
testing...
java.lang.AssertionError: If assertions are on, we'll see this
        at test.AssertTest.main(AssertTest.java:9)

Let's look at a couple more examples. To do this, I'll use the Assert2Test class and the Assert3Test class.

Assert2Test.java

package test;

import test.three.Assert3Test;

public class Assert2Test {
	public static void main(String[] args) {
		assert false : "Message from Assert2Test";
		Assert3Test.howdy();
	}
}

Assert3Test.java

package test.three;

public class Assert3Test {
	public static void howdy() {
		assert false : "Message from Assert3Test";
	}
}

We can enable assertions for a package. Here, we say to enable assertions for the test package by using the -ea option followed by a colon followed by the name of the package followed by ellipses (...). This enables assertions for all classes in that package and all classes in all subpackages of test. We can see that we first hit the assertion in Assert2Test, and we exit.

java -ea:test... test.Assert2Test

C:\projects\workspace\testing\bin>java -ea:test... test.Assert2Test
Exception in thread "main" java.lang.AssertionError: Message from Assert2Test
        at test.Assert2Test.main(Assert2Test.java:8)

Next, I'll enable assertions in the test.three package. Since assertions are by default disabled in the test package, we don't hit the assertion in test.Assert2Test. However, we do hit the assertion in test.three.Assert3Test.

java -ea:test.three... test.Assert2Test

C:\projects\workspace\testing\bin>java -ea:test.three... test.Assert2Test
Exception in thread "main" java.lang.AssertionError: Message from Assert3Test
        at test.three.Assert3Test.howdy(Assert3Test.java:6)
        at test.Assert2Test.main(Assert2Test.java:9)

It's possible to disable assertions for a particular package by using the same ellipses form above but with the -da (or -disableassertions) option. This can be useful if they've been enabled for a particular package, but you want them disabled for a particular subpackage of that package.

We can also enable assertions for a particular class. This is done by specifying -ea followed by a colon followed by the fully qualified class name.

java -ea:test.three.Assert3Test test.Assert2Test

C:\projects\workspace\testing\bin>java -ea:test.three.Assert3Test test.Assert2Test
Exception in thread "main" java.lang.AssertionError: Message from Assert3Test
        at test.three.Assert3Test.howdy(Assert3Test.java:5)
        at test.Assert2Test.main(Assert2Test.java:8)

Most Java web developers that I know don't use assertions, but it's good to know that they exist. They probably are useful in particular fields of programming.