Return-Path: Delivered-To: apmail-ant-dev-archive@ant.apache.org Received: (qmail 93998 invoked by uid 500); 21 Aug 2003 00:53:07 -0000 Mailing-List: contact dev-help@ant.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Ant Developers List" Reply-To: "Ant Developers List" Delivered-To: mailing list dev@ant.apache.org Received: (qmail 92984 invoked by uid 500); 21 Aug 2003 00:52:48 -0000 Received: (qmail 92629 invoked from network); 21 Aug 2003 00:52:41 -0000 Received: from minotaur.apache.org (209.237.227.194) by daedalus.apache.org with SMTP; 21 Aug 2003 00:52:41 -0000 Received: (qmail 56284 invoked by uid 1365); 21 Aug 2003 00:34:27 -0000 Date: 21 Aug 2003 00:34:27 -0000 Message-ID: <20030821003427.56283.qmail@minotaur.apache.org> From: stevel@apache.org To: ant-cvs@apache.org Subject: cvs commit: ant/docs/manual/CoreTypes assertions.html X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N stevel 2003/08/20 17:34:27 Added: docs/manual/CoreTypes assertions.html Log: Documented assertions..still need the tests Revision Changes Path 1.1 ant/docs/manual/CoreTypes/assertions.html Index: assertions.html =================================================================== 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

Attribute Description Required
enableSystemAssertions Flag 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.

Attribute Description Required
class The 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.

Attribute Description Required
class The 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" />
--------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org For additional commands, e-mail: dev-help@ant.apache.org