5.6 Assertions > 5.6.4 Enabling and disabling assertions at runtime

5.6.4 Enabling and disabling assertions at runtime

As we have seen, the assertion-aware code can be compiled with –source 1.4 option of Java compiler. A compiled assertion-aware code does not mean that the assertions take effect at runtime. The most impressive feature of assertions is that you can decide to either enable or disable them at runtime. When you run the code by disabling assertions, it runs as if the assertions don’t exist in the code.

Enabling assertions at runtime

Enabling assertions simply means they will be executed at the runtime. You can enable the assertions at runtime with either  –ea or –enableassertions option of the Java interpreter.

$ java –ea VotingTerminal

or

$ java –enableassertions VotingTerminal

When assertions are enabled, the assert statement is executed. If the assertion succeeds, the code executes its normal flow. If it fails, the AssertionError is thrown.

Disabling assertions at runtime

By default, the assertions are disabled. You can explicitly disable them at runtime with –da or –disableassertions option of Java interpreter.

$ java –da VotingTerminal

or

$ java –disableassertions VotingTerminal

When assertions are disabled, all the assert statements are ignored. Their execution is then equivalent to that of empty statements. Since the assertions are disabled by default, the –da and –disableassertions options of java might look redundant and useless. However, these options are useful when you selectively enable or disable assertions for classes in your applications.

Selective enabling-disabling of assertions

Java provides you with  the flexibility to selectively enable or disable assertions. When you are running your program, you can enable assertions for some classes and/or packages and disable them for others. Earlier we saw the simple options –ea and –da, to enable and disable assertions. The same options can be used for a selective enabling-disabling. Additionally, you can pass the class name or package name as an argument to these options. Table 5.10 summarizes the options used while running a Java program to do selective enabling and disabling of assertions.

Table 5.10 Runtime options for enabling and disabling the assertions

* The three dots ... after the : are important. They indicate that the name specified is a package name and not a class name, If no name is specified after … then it is the default package.

Enabling/disabling assertions for all classes (except the system classes):

When you run your Java program with –ea option, it has its assertions enabled. In addition, all the non-system classes loaded during its execution will have their assertions enabled. Say for instance, we have a VotingTerminal class that calls another class called Voter for its operation. Assume that both the VotingTerminal and the Voter class use assertions in their code. If you compile these classes with the -source 1.4 option, and run the VoteMachine class with –ea option, the assertions in the Voter class are automatically enabled.

The same thing is true with the –da option. For instance, if you run the VotingTerminal class with the -da option, the assertions in both the VotingTerminal and the Voter class are automatically disabled.

You can also enable assertions for certain classes while simultaneously disabling them for other classes. For instance, if you want to enable assertions in VotingTerminal class while disabling the assertions in Voter class at the time of running the VotingTerminal class, you can do so as:

$ java -ea:VotingTerminal -da:Voter VotingTerminal

Enabling/disabling assertions for a package:

You can selectively enable or disable assertions in the named package and any of its subpackages. For instance, suppose you have the Voter class in package example.elections and the VotingTerminal class in the package example.elections.voting. The directory structure for these classes after compilation will look something like this:

Suppose that both VotingTerminal and Voter use the assert statement and you want to run them with their assertions enabled. You can do so by enabling assertions for the package example.elections. Then you can run the VotingTerminal class as:

$java -ea:example.elections... example.elections.voting.VotingTerminal

The option –ea:example.elections... enables the assertions in all the classes in the package com.example.elections and all of its subpackages. Therefore, the assertions of both Voter and VotingTerminal are enabled. The following command line enables assertions of only the classes in the voting subpackage while running VotingTerminal.

$java -ea:example.elections.voting... example.elections.voting.VotingTerminal

The –ea: and –da: options for package applies to the package specified and all its subpackages, recursively. Therefore, you can enable the assertions for Voter and VotingTerminal by simply enabling assertions for the example package as:

$java -ea:example... com.example.elections.voting.VotingTerminal

.

Enabling/disabling assertions for the default package:

You can enable assertions in the default package by only giving the unnamed package ... to the –ea or –da option. For instance if you want to run the VotingTerminal with assertions enabled in all classes within the default package, you can do so:

$java -ea:... com.example.elections.voting.VotingTerminal

Enabling/disabling assertions for all system level classes:

The system classes are the classes in the Java platform libraries. In order to enable or disable assertions in all system classes, use the options –esa (or enablesystemassertions ) and –dsa (or disablesystemassertions). As it is with all the assertions, the system assertions are disabled by default. You can use the following command-line to enable assertions for all system classes. It also shows you how to use multiple options for enabling and/or disabling assertions while running a Java application VotingTerminal.

$java -esa -ea:example... -da:example.elections... VotingTerminal

This command enables assertions for all the system classes with the –esa option. It also enables assertions for all the classes and subpackages in the example package   with the –ea option, except the example.elections package. The –da option disables assertions for all classes and subpackages in package example.elections.