Assertion Facility

An assertion is understood to be a statement containing a boolean expression that the programmer believes to be true at the time the statement is executed. For example, after unmarshalling all of the arguments from a data buffer, a programmer might assert that the number of bytes of data remaining in the buffer is zero. The system executes the assertion by evaluating the boolean expression and reporting an error if the expression evaluates to false. By verifying that the boolean expression is indeed true, the system corroborates the programmer's knowledge of the program thus increasing the possibility that the program is free of errors.

Assertion checking may be disabled for increased performance. Typically, assertion checking is enabled during program development and testing and disabled for deployment.

Because assertions may be disabled, programs must not assume that the boolean expressions contained in assertions will be evaluated. Thus these expressions should be free of side effects. That is, evaluating such an expression should not affect any state that is visible after the evaluation is complete. Although it is not illegal for a boolean expression contained in an assertion to have a side effect, it is generally inappropriate, as it could cause program behavior to vary depending on whether assertions are enabled or disabled.

Similarly, assertions should not be used for argument checking in public methods. Argument checking is typically part of the contract of a method, and this contract must be upheld whether assertions are enabled or disabled. Another problem with using assertions for argument checking is that erroneous arguments should result in an appropriate runtime exception (such as IllegalArgumentException, IndexOutOfBoundsException or NullPointerException). An assertion failure will not throw an appropriate exception.

For more details, choose from the following links:

Compiling

In order for the javac bytecode compiler to accept code containing assertions, you must use the -source 1.4 command-line option as in this example:
javac -source 1.4 MyClass.java

Syntax

A new keyword is added to the language. Use of the assert keyword is governed by one modified production and one new production in the grammar:
StatementWithoutTrailingSubstatement: <All current possibilities, as per JLS, Section 14.4> AssertStatement AssertStatement: assert Expression₁; assert Expression₁ : Expression₂;

In both forms of the assert statement, Expression₁ must be of type boolean or a compile-time error occurs.

Semantics

If assertions are disabled in a class, the assert statements contained in that class have no effect. If assertions are enabled, the first expression is evaluated. If it evaluates to false, an AssertionError is thrown. If the assertion contains a second expression (preceded by a colon), this expression is evaluated and passed to the constructor of the AssertionError; otherwise the parameterless constructor is used. (If the first expression evaluates to true, the second expression is not evaluated.)

If an exception is thrown while either expression is being evaluated, the assert statement completes abruptly, throwing this exception.

Enabling and Disabling Assertions

By default, assertions are disabled. Two command-line switches allow you to selectively enable or disable assertions.

The following switch enables assertions at various granularities:
java [ -enableassertions | -ea ] [:<package name>"..." | :<class name> ]

With no arguments, the switch enables assertions by default. With one argument ending in "...", assertions are enabled in the specified package and any subpackages by default. If the argument is simply "...", assertions are enabled in the unnamed package in the current working directory. With one argument not ending in "...", assertions are enabled in the specified class.

The following switch disables assertions in similar fashion:
java [ -disableassertions | -da ] [:<package name>"..." | :<class name> ]

If a single command line contains multiple instances of these switches, they are processed in order before loading any classes. For example, to run a program with assertions enabled only in package com.wombat.fruitbat (and any subpackages), the following command could be used:
java -ea:com.wombat.fruitbat... java -ea:com.wombat.fruitbat... <Main class>

To run a program with assertions enabled in package com.wombat.fruitbat but disabled in class com.wombat.fruitbat.Brickbat, the following command could be used:
java -ea:com.wombat.fruitbat... -da:com.wombat.fruitbat.Brickbat <class>

The above switches apply to all class loaders, and to system classes (which do not have a class loader). There is one exception to this rule: in their no-argument form, the switches do not apply to system classes. This makes it easy to turn on asserts in all classes except for system classes. A separate switch is provided to enable asserts in all system classes (i.e., to set the default assertion status for system classes to true).
java [ -enablesystemassertions | -esa ]

For symmetry, a corresponding switch is provided to enable asserts in all system classes.
java [ -disablesystemassertions | -dsa ]

Enabling and Disabling Assertions Programmatically

Most programmers will not need to use the following methods. They are provided for those writing interpreters or other execution environments.

Setting the Default Assertion Status for a Class Loader

Each class loader maintains a default assertion status, a boolean value that determines whether assertions are, by default, enabled or disabled in new classes that are subsequently initialized by the class loader. A newly created class loader's default assertion status is false (disabled). It can be changed at any time by invoking a new method in class ClassLoader:

public void setDefaultAssertionStatus(boolean enabled)

If, at the time that a class is loaded, its class loader has been given specific instructions regarding the assertion status of the class's package name or its class name (via either of the two new methods in ClassLoader described below), those instructions take precedence over the class loader's default assertion status. Otherwise, the class's assertions are enabled or disabled as specified by its class loader's default assertion status.

Setting the Assertion Status for a Package and its Subpackages

The following method allows the invoker to set a per-package default assertion status. Note that a per-package default actually applies to a package and any subpackages.

public void setPackageAssertionStatus(String packageName, boolean enabled);