ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ste...@apache.org
Subject cvs commit: ant/docs/manual/CoreTypes assertions.html
Date Thu, 21 Aug 2003 00:34:27 GMT
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
  ===================================================================
  <html>
  
  <head>
  <meta http-equiv="Content-Language" content="en-us">
  <title>Assertions type</title>
  </head>
  
  <body>
  
  <h2><a name="assertions">Assertions</a></h2>
  <p>
  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 &lt;java&gt; and &lt;junit&gt; to add extra validation to code.   
  
  <p>
  Assertions are covered in the 
  <a href="http://java.sun.com/j2se/1.4.2/docs/guide/lang/assert.html">
  Java 1.4.2</a> documentation, and the 
  <a href="http://java.sun.com/docs/books/jls/assert-spec.html">
  Java Language Specification</a>
  
  <p>
  The key points to note are that a <tt>java.lang.AssertionError</tt> 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 <tt>source="1.4"</tt>,
   "1.5" or later in &lt;javac&gt; 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 Ant itself currently contains no assertions.
  <p>
  
  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.  
  
  <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 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. 
  <p>
  Note also that there is no apparent documentation for what parts of the
  system have built in assertions. 
  
  <h3>Nested elements</h3>
  
  <h4>enable</h4>
  <p>
  Enable 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 to enable assertions on.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">package</td>
      <td valign="top">
      The name of a package to turn assertions on. Use "..." 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 to disable assertions for.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">package</td>
      <td valign="top">
      The name of a package to turn assertions off on. Use "..." 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 a single class</h5>
  
  Enable assertions in a class called Test
  <pre>
  &lt;assertions &gt;
    &lt;enable class="Test" /&gt;
  &lt;/assertions&gt;
  </pre>
  
  <h5>Example: enable a package</h5>
  
  Enable assertions in a all packages below org.apache
  <pre>
  &lt;assertions &gt;
    &lt;enable package="org.apache" /&gt;
  &lt;/assertions&gt;
  </pre>
  
  <h5>Example: System assertions</h5>
  
  Example: set system assertions and all org.apache packages except
  for ant, and the class org.apache.tools.ant.Main.
  <pre>
  &lt;assertions enableSystemAssertions="true" &gt;
    &lt;enable package="org.apache" /&gt;
    &lt;disable package="org.apache.ant" /&gt;
    &lt;enable class="org.apache.tools.ant.Main"/&gt;
  &lt;/assertions&gt;
  </pre>
  
  <h5>Example: disabled and anonymous package assertions</h5>
  
  Disable system assertions; enable those in the anonymous package
  <pre>
  &lt;assertions enableSystemAssertions="false" &gt;
    &lt;enable package="..." /&gt;
  &lt;/assertions&gt;
  </pre>
  
  
  <h5>Example: referenced assertions</h5>
  
  This type is a datatype, so you can declare assertions and use them later
  
  <pre>
  &lt;assertions id="project.assertions" &gt;
    &lt;enable project="org.apache.test" /&gt;
  &lt;/assertions&gt;
  
  &lt;assertions refid="project.assertions" /&gt;
  </pre>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message