youys
/
ant

 
			
			   
				 
					
						
						
							
							<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Java Task</title>
</head>

<body>

<h2><a name="java">Java</a></h2>
<h3>Description</h3>
<p>Executes a Java class within the running (Ant) VM or forks another VM if
specified.</p>
<p>
If odd things go wrong when you run this task, set fork="true" to use a new
JVM.

<p>Note that you cannot interact with a forked VM, the only way to
send input to it is via the input and inputstring attributes. Also note that
in Ant 1.6, any attempt to read input in the forked VM will receive an
EOF (-1). This is a change from Ant 1.5, where such an attempt would block.</p>

<h3>Parameters</h3>
<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">classname</td>
    <td valign="top">the Java class to execute.</td>
    <td align="center" valign="top">Either jar or classname</td>
  </tr>
  <tr>
    <td valign="top">jar</td>
    <td valign="top">the location of the jar file to execute (must have a
    Main-Class entry in the manifest). Fork must be set to true if this option is selected.</td>
    <td align="center" valign="top">Either jar or classname</td>
  </tr>
  <tr>
    <td valign="top">args</td>
    <td valign="top">the arguments for the class that is
      executed. <b>deprecated, use nested <code>&lt;arg&gt;</code>
      elements instead.</b></td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">classpath</td>
    <td valign="top">the classpath to use.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">classpathref</td>
    <td valign="top">the classpath to use, given as <a
      href="../using.html#references">reference</a> to a PATH defined elsewhere.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">fork</td>
    <td valign="top">if enabled triggers the class execution in another VM
      (disabled by default)</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">spawn</td>
    <td valign="top">if enabled allows to start a process which will outlive ant.<br/>
    Requires fork=true, and not compatible
    with timeout, input, output, error, result attributes.<br/>
      (disabled by default)</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">jvm</td>
    <td valign="top">the command used to invoke the Java Virtual Machine,
      default is 'java'.  The command is resolved by java.lang.Runtime.exec().
      Ignored if fork is disabled.
    </td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">jvmargs</td>
    <td valign="top">the arguments to pass to the forked VM (ignored
      if fork is disabled). <b>deprecated, use nested
      <code>&lt;jvmarg&gt;</code> elements instead.</b></td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">maxmemory</td>
    <td valign="top">Max amount of memory to allocate to the forked VM
      (ignored if fork is disabled)</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">failonerror</td>
    <td valign="top">Stop the buildprocess if the command exits with a
      returncode other than 0. Default is "false" (see <a href="#failonerror">note)</a></td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">resultproperty</td>
    <td valign="top">The name of a property in which the return code of the
      command should be stored. Only of interest if failonerror=false
      and if fork=true.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">The directory to invoke the VM in.  (ignored if
      fork is disabled)</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">output</td>
    <td valign="top">Name of a file to which to write the output. If the error stream
      is not also redirected to a file or property, it will appear in this output.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">error</td>
    <td valign="top">The file to which the standard error of the command should be
      redirected. </td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">logError</td>
    <td valign="top">This attribute is used when you wish to see error output in Ant's
                     log and you are redirecting output to a file/property. The error
                     output will not be included in the output file/property. If you
                     redirect error with the &quot;error&quot; or &quot;errorProperty&quot;
                     attributes, this will have no effect.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">append</td>
    <td valign="top">Whether output and error files should be appended to or overwritten.
    Defaults to false.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">outputproperty</td>
    <td valign="top">The name of a property in which the output of the
      command should be stored. Unless the error stream is redirected to a separate
      file or stream, this property will include the error output.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">errorproperty</td>
    <td valign="top">The name of a property in which the standard error of the
      command should be stored.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">input</td>
    <td valign="top">A file from which the executed command's standard input
                     is taken. This attribute is mutually exclusive with the
                     inputstring attribute</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">inputstring</td>
    <td valign="top">A string which serves as the input stream for the
                     executed command. This attribute is mutually exclusive with the
                     input attribute.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">newenvironment</td>
    <td valign="top">Do not propagate old environment when new
      environment variables are specified. Default is &quot;false&quot;
      (ignored if fork is disabled).</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">timeout</td>
    <td valign="top">Stop the command if it doesn't finish within the
    specified time (given in milliseconds).  <strong>It is highly
    recommended to use this feature only if fork is enabled.</strong></td>
    <td align="center" valign="top">No</td>
  </tr>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>arg and jvmarg</h4>
<p>Use nested <code>&lt;arg&gt;</code> and <code>&lt;jvmarg&gt;</code>
elements to specify arguments for the Java class and the forked VM respectively.
See <a href="../using.html#arg">Command line arguments</a>.</p>
<h4>sysproperty</h4>
<p>Use nested <code>&lt;sysproperty&gt;</code>
elements to specify system properties required by the class.
These properties will be made available to the VM during the execution
of the class (either ANT's VM or the forked VM). The attributes
for this element are the same as for <a href="exec.html#env">environment
variables</a>.</p>

<h4>syspropertyset</h4>

<p>You can specify a set of properties to be used as system properties
with <a href="../CoreTypes/propertyset.html">syspropertyset</a>s.</p>

<p><em>since Ant 1.6</em>.</p>

<h4>classpath</h4>
<p><code>Java</code>'s <i>classpath</i> attribute is a <a
href="../using.html#path">PATH like structure</a> and can also be set via a nested
<i>classpath</i> element.</p>

<h4>bootclasspath</h4>

<p>The location of bootstrap class files can be specified using this
<a href="../using.html#path">PATH like structure</a> - will be ignored
if <i>fork</i> is not <code>true</code> or the target VM doesn't
support it (i.e. Java 1.1).</p>

<p><em>since Ant 1.6</em>.</p>

<h4>env</h4>
<p>It is possible to specify environment variables to pass to the
forked VM via nested <i>env</i> elements. See the description in the
section about <a href="exec.html#env">exec</a></p>
<p>Settings will be ignored if fork is disabled.</p>

<h4>permissions</h4>
<p>Security permissions can be revoked and granted during the execution of the
class via a nested <i>permissions</i> element. For more information please
see <a href="../CoreTypes/permissions.html">permissions</a></p>
<p>When the permission RuntimePermission exitVM has not been granted (or has
been revoked) the System.exit() call will be intercepted
and treated like indicated in <i>failonerror</i>.</p>
<p><a name="failonerror"/>
If you specify <code>failonerror=&quot;true&quot;</code> and you do not specify permissions,
a set of default permissions will be added to your java invocation making sure that
a non zero return code will lead to a <code>BuildException</code>.
</p>
<p>Settings will be ignored if fork is enabled.</p>

<p><em>since Ant 1.6</em>.</p>

<h4>assertions</h4>

<p>You can control enablement of Java 1.4 assertions with an
<a href="../CoreTypes/assertions.html"><tt>&lt;assertions&gt;</tt></a>
subelement.</p>
 
<p><em>since Ant 1.6.</em></p>

<h3>Errors and return codes</h3>
By default the return code of a &lt;java&gt; is ignored. Alternatively, you can set <code>resultproperty</code> to the name
of a property and have it assigned to the result code (barring immutability,
of course).
When you set <code>failonerror="true"</code>, the only possible value for <code>resultproperty</code> is 0. Any non zero response is treated as an
error and would mean the build exits.
<p> Similarly, if <code>failonerror="false"</code> and <code>fork="false"</code>
, then <code>&lt;java&gt;</code> <b>must</b> return 0 otherwise the build will exit, as the class was run by the build jvm.</p>

<h3>Examples</h3>
<pre>
       &lt;java classname=&quot;test.Main&quot;&gt;
         &lt;arg value=&quot;-h&quot;/&gt;
         &lt;classpath&gt;
           &lt;pathelement location=&quot;dist/test.jar&quot;/&gt;
           &lt;pathelement path=&quot;${java.class.path}&quot;/&gt;
         &lt;/classpath&gt;
       &lt;/java&gt;
</pre>
Run a class in this JVM with a new jar on the classpath

<pre>        &lt;java jar=&quot;dist/test.jar&quot;
           fork="true"
           failonerror="true"
           maxmemory="128m"
           &gt;
         &lt;arg value=&quot;-h&quot;/&gt;
         &lt;classpath&gt;
           &lt;pathelement location=&quot;dist/test.jar&quot;/&gt;
           &lt;pathelement path=&quot;${java.class.path}&quot;/&gt;
         &lt;/classpath&gt;
       &lt;/java&gt;
</pre>
Run the jar using the manifest supplied entry point, forking (as required),
and with a maximum memory of 128MB. Any non zero return code breaks the build.

<pre>  &lt;java classname=&quot;test.Main&quot;/&gt;</pre>
<pre>  &lt;java classname=&quot;test.Main&quot;
        fork=&quot;yes&quot; &gt;
    &lt;sysproperty key=&quot;DEBUG&quot; value=&quot;true&quot;/&gt;
    &lt;arg value=&quot;-h&quot;/&gt;
    &lt;jvmarg value=&quot;-Xrunhprof:cpu=samples,file=log.txt,depth=3&quot;/&gt;
  &lt;/java&gt;
</pre>
<strong>Note</strong>: you can not specify the (highly deprecated) MSJVM, "jview.exe" as the
JVM, as it takes different parameters for other JVMs,
That JVM can be started from &lt;exec&gt; if required.
<hr>
<p align="center">Copyright &copy; 2000-2004 Apache Software Foundation. All rights
Reserved.</p>

</body>
</html>