assertions type enables or disables the Java 1.4 assertions feature, on a whole
Java program, or components of a program. It can be used
<junit> to add extra validation to code.
Assertions are covered in the Java SE documentation, and the Java Language Specification.
The key points to note are that a
java.lang.AssertionError is thrown when an assertion
fails, and that the facility is only available on Java 1.4 and later. To enable assertions one must
1.4 (or later) in
<javac> when the source is being
compiled, and that the code must contain
assert statements to be tested. The result of
such an action is code that neither compiles or runs on earlier versions of Java. For this reason
Apache Ant itself currently contains no assertions.
When assertions are enabled (or disabled) in a task through nested assertions elements, the class loader or command line is modified with the appropriate options. This means that the JVM executed must be of version 1.4 or later, even if there are no assertions in the code. Attempting to enable assertions on earlier JVMs will result in an "Unrecognized option" error and the JVM will not start.
|enableSystemAssertions||Flag to turn system assertions on or off.||No; default is
When system assertions have been neither enabled nor disabled, then the JVM is not given any assertion information—the default action of the current JVMs is to disable system assertions.
Note also that there is no apparent documentation for what parts of the JRE come with useful assertions.
Enable assertions in portions of code. If neither a package nor class is specified, assertions are turned on in all (user) code.
|class||The name of a class on which to enable assertions.||No|
|package||The name of a package in which to enable assertions on all classes. (Includes subpackages.)
...for the anonymous package.
Disable assertions in portions of code.
|class||The name of a class on which to disable assertions.||No|
|package||The name of a package in which to disable assertions on all classes. (Includes subpackages.)
...for the anonymous package.
Because assertions are disabled by default, it only makes sense to disable assertions where they have been enabled in a parent package.
All classes not in the JRE (i.e. all non-system classes) will have assertions turned on.
<assertions> <enable/> </assertions>
Enable assertions in a class called Test
<assertions> <enable class="Test"/> </assertions>
Enable assertions in the
org.apache package and all packages starting with
<assertions> <enable package="org.apache"/> </assertions>
Enable system assertions and assertions in all
org.apache packages except for Ant
<assertions enableSystemAssertions="true"> <enable package="org.apache"/> <disable package="org.apache.tools.ant"/> <enable class="org.apache.tools.ant.Main"/> </assertions>
Disable system assertions; enable those in the anonymous package
<assertions enableSystemAssertions="false"> <enable package="..."/> </assertions>
This type is a datatype, so you can declare assertions and use them later
<assertions id="project.assertions"> <enable package="org.apache.test"/> </assertions> <assertions refid="project.assertions"/>