1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
<title>Assertions type</title>
</head>
<body>
<h2><a name="assertions">Assertions</a></h2>
<p>
The <tt>assertions</tt> type enables or disables the Java 1.4 assertions feature,
on a whole Java program, or components of a program. It can be used
in <a href="../Tasks/java.html"><code><java></code></a> and
<a href="../Tasks/junit.html"><code><junit></code></a> to add extra validation to code.
<p>
Assertions are covered in the
<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/language/assert.html">Java SE documentation</a>,
and the
<a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-14.html#jls-14.10">Java Language Specification</a>.
<p>
The key points to note are that a <tt>java.lang.AssertionError</tt>
is thrown when an assertion fails, and that the facility is only available
on Java 1.4 and later. To enable assertions one must set <tt>source="1.4"</tt>
(or later) in <tt><javac></tt> when the source is being compiled, and
that the code must contain <tt>assert</tt> 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.
<p>
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 a Java 1.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.
<p>
<h4>Attributes</h4>
<p>
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">enableSystemAssertions</td>
<td valign="top">Flag to turn system assertions on or off.</td>
<td valign="top" align="center">No; default is "unspecified"</td>
</tr>
</table>
<p>
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.
<p>
Note also that there is no apparent documentation for what parts of the
JRE come with useful assertions.
<h3>Nested elements</h3>
<h4>enable</h4>
<p>
Enable assertions in portions of code.
If neither a package nor class is specified, assertions are turned on in <i>all</i> (user) code.
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">class</td>
<td valign="top">The name of a class on which to enable assertions.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">package</td>
<td valign="top">
The name of a package in which to enable assertions on all classes. (Includes subpackages.)
Use "<tt>...</tt>" for the anonymous package.
</td>
<td valign="top" align="center">No</td>
</tr>
</table>
<h4>disable</h4>
<p>
Disable assertions in portions of code.
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">class</td>
<td valign="top">The name of a class on which to disable assertions.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">package</td>
<td valign="top">
The name of a package in which to disable assertions on all classes. (Includes subpackages.)
Use "<tt>...</tt>" for the anonymous package.
</td>
<td valign="top" align="center">No</td>
</tr>
</table>
<p>
Because assertions are disabled by default, it only makes sense to disable
assertions where they have been enabled in a parent package.
<h4>Examples</h4>
<h5>Example: enable assertions in all user classes</h5>
All classes not in the JRE (i.e. all non-system classes) will have assertions turned on.
<pre>
<assertions>
<enable/>
</assertions>
</pre>
<h5>Example: enable a single class</h5>
Enable assertions in a class called Test
<pre>
<assertions>
<enable class="Test"/>
</assertions>
</pre>
<h5>Example: enable a package</h5>
Enable assertions in the <tt>org.apache</tt> package
and all packages starting with the <tt>org.apache.</tt> prefix
<pre>
<assertions>
<enable package="org.apache"/>
</assertions>
</pre>
<h5>Example: System assertions</h5>
Example: enable system assertions and assertions in all <tt>org.apache</tt> packages except
for Ant (but including <tt>org.apache.tools.ant.Main</tt>)
<pre>
<assertions enableSystemAssertions="true">
<enable package="org.apache"/>
<disable package="org.apache.tools.ant"/>
<enable class="org.apache.tools.ant.Main"/>
</assertions>
</pre>
<h5>Example: disabled and anonymous package assertions</h5>
Disable system assertions; enable those in the anonymous package
<pre>
<assertions enableSystemAssertions="false">
<enable package="..."/>
</assertions>
</pre>
<h5>Example: referenced assertions</h5>
This type is a datatype, so you can declare assertions and use them later
<pre>
<assertions id="project.assertions">
<enable package="org.apache.test"/>
</assertions>
<assertions refid="project.assertions"/>
</pre>
</body>
</html>
|
