diff --git a/docs/manual/CoreTypes/assertions.html b/docs/manual/CoreTypes/assertions.html new file mode 100644 index 000000000..f0533199d --- /dev/null +++ b/docs/manual/CoreTypes/assertions.html @@ -0,0 +1,177 @@ + + + + +Assertions type + + + + +

Assertions

+

+The assertion type enables or disables the Java1.4 assertion feature, +on a whole java program, or components of a program. It can be used +in <java> and <junit> to add extra validation to code. + +

+Assertions are covered in the + +Java 1.4.2 documentation, and the + +Java Language Specification + +

+The key points to note are that a java.lang.AssertionError error +is thrown when an assertion fails, and that the facility is only available +on Java1.4 and later. To enable assertions one must set source="1.4", + "1.5" 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 Ant itself currently contains no assertions. +

+ +When assertions are enabled (or disabled) in a task through nested +assertions elements, the classloader or command line is modified with the +appopriate options. This means that the JVM executed must be a Java1.4 +or later JVM, even if there are no assertions in the code. Attempting to +enable assertions on earlier VMs will result in an "Unrecognized option" +error and the JVM will not start. + +

+

Attributes

+

+ + +

+ + + + + + + + + + + +
AttributeDescriptionRequired
enableSystemAssertionsFlag to turn system assertions on or off.No, default is 'unspecified'
+

+When the System assertions have neither been enabled or 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 +system have built in assertions. + +

Nested elements

+ +

enable

+

+Enable assertions in portions of code. + +

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
classThe name of a class to enable assertions on.No
package + The name of a package to turn assertions on. Use "..." for + the anonymous package. + No
+ +

disable

+

+Disable assertions in portions of code. + +

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
classThe name of a class to disable assertions for.No
package + The name of a package to turn assertions off on. Use "..." for + the anonymous package. + No
+

+ +Because assertions are disabled by default, it only makes sense to disable +assertions where they have been enabled in a parent package. + + +

Examples

+ +
Example: enable a single class
+ +Enable assertions in a class called Test +
+<assertions >
+  <enable class="Test" />
+</assertions>
+
+ +
Example: enable a package
+ +Enable assertions in a all packages below org.apache +
+<assertions >
+  <enable package="org.apache" />
+</assertions>
+
+ +
Example: System assertions
+ +Example: set system assertions and all org.apache packages except +for ant, and the class org.apache.tools.ant.Main. +
+<assertions enableSystemAssertions="true" >
+  <enable package="org.apache" />
+  <disable package="org.apache.ant" />
+  <enable class="org.apache.tools.ant.Main"/>
+</assertions>
+
+ +
Example: disabled and anonymous package assertions
+ +Disable system assertions; enable those in the anonymous package +
+<assertions enableSystemAssertions="false" >
+  <enable package="..." />
+</assertions>
+
+ + +
Example: referenced assertions
+ +This type is a datatype, so you can declare assertions and use them later + +
+<assertions id="project.assertions" >
+  <enable project="org.apache.test" />
+</assertions>
+
+<assertions refid="project.assertions" />
+