2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
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.
|
|
|
|
|
-->
|
2003-08-21 00:34:27 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2005-04-29 18:58:16 +00:00
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
2003-08-21 00:34:27 +00:00
|
|
|
<title>Assertions type</title>
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
2018-02-08 16:59:52 +01:00
|
|
|
<h2 id="assertions">Assertions</h2>
|
2003-08-21 00:34:27 +00:00
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
The <code>assertions</code> 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>
|
2018-03-08 07:43:53 +01:00
|
|
|
and <a href="../Tasks/junit.html"><code><junit></code></a> to add extra validation to code.
|
2003-08-21 00:34:27 +00:00
|
|
|
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
Assertions are covered in
|
2018-03-08 07:43:53 +01:00
|
|
|
the <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html"
|
|
|
|
|
target="_top">Java SE documentation</a>, and
|
|
|
|
|
the <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-14.html#jls-14.10"
|
|
|
|
|
target="_top">Java Language Specification</a>.
|
2003-08-21 00:34:27 +00:00
|
|
|
|
|
|
|
|
<p>
|
2018-03-08 07:43:53 +01:00
|
|
|
The key points to note are that a <code>java.lang.AssertionError</code> 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 <var>source</var>=<q>1.4</q> (or later) in <code><javac></code> when the source is being
|
|
|
|
|
compiled, and that the code must contain <code>assert</code> 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.
|
2003-08-21 00:34:27 +00:00
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2018-03-08 07:43:53 +01:00
|
|
|
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.
|
|
|
|
|
</p>
|
|
|
|
|
|
2003-08-21 00:34:27 +00:00
|
|
|
<h4>Attributes</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2003-08-21 00:34:27 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2003-08-21 00:34:27 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>enableSystemAssertions</td>
|
|
|
|
|
<td>Flag to turn system assertions on or off.</td>
|
|
|
|
|
<td>No; default is <q>unspecified</q></td>
|
2003-08-21 00:34:27 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
When system assertions have been neither enabled nor disabled, then the JVM is not given any
|
2018-03-08 07:43:53 +01:00
|
|
|
assertion information—the default action of the current JVMs is to disable system assertions.
|
|
|
|
|
</p>
|
2003-08-21 00:34:27 +00:00
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
Note also that there is no apparent documentation for what parts of the JRE come with useful
|
|
|
|
|
assertions.
|
2018-03-08 07:43:53 +01:00
|
|
|
</p>
|
2003-08-21 00:34:27 +00:00
|
|
|
|
|
|
|
|
<h3>Nested elements</h3>
|
|
|
|
|
|
|
|
|
|
<h4>enable</h4>
|
|
|
|
|
<p>
|
2018-03-08 07:43:53 +01:00
|
|
|
Enable assertions in portions of code. If neither a package nor class is specified, assertions are
|
|
|
|
|
turned on in <em>all</em> (user) code.
|
2003-08-21 00:34:27 +00:00
|
|
|
</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2003-08-21 00:34:27 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2003-08-21 00:34:27 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>class</td>
|
|
|
|
|
<td>The name of a class on which to enable assertions.</td>
|
|
|
|
|
<td>No</td>
|
2003-08-21 00:34:27 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>package</td>
|
2018-03-08 07:43:53 +01:00
|
|
|
<td>The name of a package in which to enable assertions on all classes. (Includes subpackages.)
|
|
|
|
|
Use <q>...</q> for the anonymous package.</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No</td>
|
2003-08-21 00:34:27 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<h4>disable</h4>
|
|
|
|
|
<p>
|
|
|
|
|
Disable assertions in portions of code.
|
|
|
|
|
</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2003-08-21 00:34:27 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2003-08-21 00:34:27 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>class</td>
|
|
|
|
|
<td>The name of a class on which to disable assertions.</td>
|
|
|
|
|
<td>No</td>
|
2003-08-21 00:34:27 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>package</td>
|
2018-03-08 07:43:53 +01:00
|
|
|
<td>The name of a package in which to disable assertions on all classes. (Includes subpackages.)
|
|
|
|
|
Use <q>...</q> for the anonymous package.</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No</td>
|
2003-08-21 00:34:27 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
Because assertions are disabled by default, it only makes sense to disable assertions where they
|
|
|
|
|
have been enabled in a parent package.
|
|
|
|
|
</p>
|
2003-08-21 00:34:27 +00:00
|
|
|
<h4>Examples</h4>
|
|
|
|
|
|
2004-02-02 14:33:08 +00:00
|
|
|
<h5>Example: enable assertions in all user classes</h5>
|
|
|
|
|
|
2018-03-08 07:43:53 +01:00
|
|
|
<p>All classes not in the JRE (i.e. all non-system classes) will have assertions turned on.</p>
|
2004-02-02 14:33:08 +00:00
|
|
|
<pre>
|
|
|
|
|
<assertions>
|
|
|
|
|
<enable/>
|
2018-03-08 07:43:53 +01:00
|
|
|
</assertions></pre>
|
2004-02-02 14:33:08 +00:00
|
|
|
|
2003-08-21 00:34:27 +00:00
|
|
|
<h5>Example: enable a single class</h5>
|
|
|
|
|
|
2018-03-08 07:43:53 +01:00
|
|
|
<p>Enable assertions in a class called Test</p>
|
2003-08-21 00:34:27 +00:00
|
|
|
<pre>
|
2004-02-02 14:33:08 +00:00
|
|
|
<assertions>
|
|
|
|
|
<enable class="Test"/>
|
2018-03-08 07:43:53 +01:00
|
|
|
</assertions></pre>
|
2003-08-21 00:34:27 +00:00
|
|
|
|
|
|
|
|
<h5>Example: enable a package</h5>
|
|
|
|
|
|
2018-03-08 07:43:53 +01:00
|
|
|
<p>Enable assertions in the <code>org.apache</code> package and all packages starting with
|
|
|
|
|
the <code>org.apache.</code> prefix</p>
|
2003-08-21 00:34:27 +00:00
|
|
|
<pre>
|
2004-02-02 14:33:08 +00:00
|
|
|
<assertions>
|
|
|
|
|
<enable package="org.apache"/>
|
2018-03-08 07:43:53 +01:00
|
|
|
</assertions></pre>
|
2003-08-21 00:34:27 +00:00
|
|
|
|
|
|
|
|
<h5>Example: System assertions</h5>
|
|
|
|
|
|
2018-03-08 07:43:53 +01:00
|
|
|
<p>Enable system assertions and assertions in all <code>org.apache</code> packages except for Ant
|
|
|
|
|
(but including <code>org.apache.tools.ant.Main</code>)</p>
|
2003-08-21 00:34:27 +00:00
|
|
|
<pre>
|
2004-02-02 14:33:08 +00:00
|
|
|
<assertions enableSystemAssertions="true">
|
|
|
|
|
<enable package="org.apache"/>
|
|
|
|
|
<disable package="org.apache.tools.ant"/>
|
2003-08-21 00:34:27 +00:00
|
|
|
<enable class="org.apache.tools.ant.Main"/>
|
2018-03-08 07:43:53 +01:00
|
|
|
</assertions></pre>
|
2003-08-21 00:34:27 +00:00
|
|
|
|
|
|
|
|
<h5>Example: disabled and anonymous package assertions</h5>
|
|
|
|
|
|
2018-03-08 07:43:53 +01:00
|
|
|
<p>Disable system assertions; enable those in the anonymous package</p>
|
2003-08-21 00:34:27 +00:00
|
|
|
<pre>
|
2004-02-02 14:33:08 +00:00
|
|
|
<assertions enableSystemAssertions="false">
|
|
|
|
|
<enable package="..."/>
|
2018-03-08 07:43:53 +01:00
|
|
|
</assertions></pre>
|
2003-08-21 00:34:27 +00:00
|
|
|
|
|
|
|
|
<h5>Example: referenced assertions</h5>
|
|
|
|
|
|
2018-03-08 07:43:53 +01:00
|
|
|
<p>This type is a datatype, so you can declare assertions and use them later</p>
|
2003-08-21 00:34:27 +00:00
|
|
|
<pre>
|
2004-02-02 14:33:08 +00:00
|
|
|
<assertions id="project.assertions">
|
|
|
|
|
<enable package="org.apache.test"/>
|
2003-08-21 00:34:27 +00:00
|
|
|
</assertions>
|
|
|
|
|
|
2018-03-08 07:43:53 +01:00
|
|
|
<assertions refid="project.assertions"/></pre>
|
2003-08-22 09:20:12 +00:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
