mirror of
https://github.com/apache/ant.git
synced 2025-05-18 14:04:48 +00:00
409 lines
17 KiB
HTML
409 lines
17 KiB
HTML
<!--
|
|
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>Java Task</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h2 id="java">Java</h2>
|
|
<h3>Description</h3>
|
|
<p>Executes a Java class within the running (Apache Ant) JVM or forks another JVM if specified.</p>
|
|
<p>If odd things go wrong when you run this task, set <var>fork</var>=<q>true</q> to use a new
|
|
JVM.</p>
|
|
|
|
<p><em>Since Ant 1.6.3</em>, you can interact with a forked JVM, as well as sending input to it via
|
|
the <var>input</var> and <var>inputstring</var> attributes.</p>
|
|
|
|
<h4 id="background">Running Ant as a background process on Unix(-like) systems</h4>
|
|
|
|
<p>If you run Ant as a background process (like <code>ant &</code>) and use
|
|
the <code><java></code> task with <var>spawn</var> set to <q>false</q> and <var>fork</var>
|
|
to <q>true</q>, you must provide explicit input to the forked process or Ant will be suspended
|
|
because it tries to read from the standard input.</p>
|
|
|
|
<h3>Parameters</h3>
|
|
<table class="attr">
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
<tr id="classname">
|
|
<td>classname</td>
|
|
<td>the Java class to execute.</td>
|
|
<td rowspan="3">Exactly one of the three</td>
|
|
</tr>
|
|
<tr>
|
|
<td>jar</td>
|
|
<td class="left">the location of the jar file to execute (must have a <code>Main-Class</code>
|
|
entry in the manifest). <var>fork</var> must be set to <q>true</q> if this option is selected.
|
|
See notes <a href="#jar-execute">below</a> for more details.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>module</td>
|
|
<td class="left">The initial or main module to resolve (must have a <code>Main-Class</code>
|
|
entry in the manifest). <var>fork</var> must be set to <q>true</q> if this option is
|
|
selected. <em>since Ant 1.9.7</em></td>
|
|
</tr>
|
|
<tr>
|
|
<td>args</td>
|
|
<td>the arguments for the class that is executed. <em><u>Deprecated</u>, use
|
|
nested <code><arg></code> elements instead.</em></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>classpath</td>
|
|
<td>the classpath to use.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>classpathref</td>
|
|
<td>the classpath to use, given as <a href="../using.html#references">reference</a> to
|
|
a <code>Path</code> defined elsewhere.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>modulepath</td>
|
|
<td>Specify where to find application modules. A list of directories of modules, module files or
|
|
exploded modules. <em>since Ant 1.9.7</em></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>modulepathref</td>
|
|
<td>The modulepath to use, given as <a href="../using.html#references">reference</a> to
|
|
a <code>Path</code> defined elsewhere. <em>since Ant 1.9.7</em></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>fork</td>
|
|
<td>if enabled triggers the class execution in another JVM.</td>
|
|
<td>No; default is <q>false</q></td>
|
|
</tr>
|
|
<tr>
|
|
<td>spawn</td>
|
|
<td>if enabled allows to start a process which will outlive Ant.<br/>Requires
|
|
that <var>fork</var> is <q>true</q>, and not compatible
|
|
with <var>timeout</var>, <var>input</var>, <var>output</var>, <var>error</var>, <var>result</var>
|
|
attributes</td>
|
|
<td>No; default is <q>false</q></td>
|
|
</tr>
|
|
<tr>
|
|
<td>jvm</td>
|
|
<td>the command used to invoke JVM. The command is resolved
|
|
by <code>java.lang.Runtime.exec()</code>. Ignored if <var>fork</var> is <q>false</q>.
|
|
</td>
|
|
<td>No, default is <q>java</q></td>
|
|
</tr>
|
|
<tr>
|
|
<td>jvmargs</td>
|
|
<td>the arguments to pass to the forked JVM, ignored if <var>fork</var> is
|
|
disabled. <em><u>Deprecated</u>, use nested <code><jvmarg></code> elements
|
|
instead.</em></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>maxmemory</td>
|
|
<td>Max amount of memory to allocate to the forked JVM, ignored if <var>fork</var>
|
|
is <q>false</q></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>failonerror</td>
|
|
<td>Stop the build process if the command exits with a return code other than <q>0</q>.</td>
|
|
<td>No; default is <q>false</q> (see <a href="#failonerror">note</a>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>resultproperty</td>
|
|
<td>The name of a property in which the return code of the command should be stored. Only of
|
|
interest if <var>failonerror</var> is <q>false</q> and if <var>fork</var> is <q>true</q>.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>dir</td>
|
|
<td>The directory to invoke the JVM in, ignored if <var>fork</var> is <q>false</q>.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>output</td>
|
|
<td>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>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>error</td>
|
|
<td>The file to which the standard error of the command should be redirected.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>logError</td>
|
|
<td>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 <var>error</var> or <var>errorProperty</var>
|
|
attributes, this will have no effect.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>append</td>
|
|
<td>Whether output and error files should be appended to or overwritten.</td>
|
|
<td>No; defaults to <q>false</q></td>
|
|
</tr>
|
|
<tr>
|
|
<td>outputproperty</td>
|
|
<td>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>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>errorproperty</td>
|
|
<td>The name of a property in which the standard error of the command should be stored.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>input</td>
|
|
<td>A file from which the executed command's standard input is taken. This attribute is mutually
|
|
exclusive with the <var>inputstring</var> attribute</td>
|
|
<td>No; default is to take standard input from console
|
|
unless <var>spawn</var> is <q>true</q></td>
|
|
</tr>
|
|
<tr>
|
|
<td>inputstring</td>
|
|
<td>A string which serves as the input stream for the executed command. This attribute is
|
|
mutually exclusive with the <var>input</var> attribute.</td>
|
|
<td>No; default is to take standard input from console unless <var>spawn</var>
|
|
is <q>true</q>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>newenvironment</td>
|
|
<td>Do not propagate old environment when new environment variables are specified.</td>
|
|
<td>No; default is <q>false</q>, ignored if <var>fork</var> is <q>false</q></td>
|
|
</tr>
|
|
<tr>
|
|
<td>timeout</td>
|
|
<td>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 <var>fork</var>
|
|
is <q>true</q>.</strong></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>clonevm</td>
|
|
<td>If set to <q>true</q>, then all system properties and the <var>bootclasspath</var> of the
|
|
forked JVM will be the same as those of the JVM running Ant. <em>since Ant 1.7</em></td>
|
|
<td>No; default is <q>false</q>, ignored if <var>fork</var> is <q>false</q></td>
|
|
</tr>
|
|
</table>
|
|
<h3>Parameters specified as nested elements</h3>
|
|
<h4>arg and jvmarg</h4>
|
|
<p>Use nested <code><arg></code> and <code><jvmarg></code> elements to specify arguments
|
|
for the Java class and the forked JVM respectively. See <a href="../using.html#arg">Command line
|
|
arguments</a>.</p>
|
|
<h4>sysproperty</h4>
|
|
<p>Use nested <code><sysproperty></code> elements to specify system properties required by the
|
|
class. These properties will be made available to JVM during the execution of the class (either
|
|
Ant's JVM or the forked JVM). The attributes for this element are the same as
|
|
for <a href="exec.html#env">environment variables</a>.</p>
|
|
|
|
<h4>syspropertyset</h4>
|
|
|
|
<p><em>Since Ant 1.6</em>.</p>
|
|
|
|
<p>You can specify a set of properties to be used as system properties
|
|
with <a href="../Types/propertyset.html">syspropertyset</a>s.</p>
|
|
|
|
<h4>classpath</h4>
|
|
<p><code>Java</code>'s <var>classpath</var> attribute is a <a href="../using.html#path">path-like
|
|
structure</a> and can also be set via a nested <code>classpath</code> element.</p>
|
|
|
|
<h4>bootclasspath</h4>
|
|
|
|
<p><em>Since Ant 1.6</em>.</p>
|
|
|
|
<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 <var>fork</var>
|
|
is not <q>true</q> or the target JVM doesn't support it (i.e. Java 1.1).</p>
|
|
|
|
<h4>env</h4>
|
|
<p>It is possible to specify environment variables to pass to the forked JVM via
|
|
nested <code>env</code> elements. See the description in the section
|
|
about <a href="exec.html#env">exec</a></p>
|
|
<p>Settings will be ignored if <var>fork</var> is <q>false</q>.</p>
|
|
|
|
<h4>permissions</h4>
|
|
|
|
<p><em>Since Ant 1.6</em>.</p>
|
|
|
|
<p>Security permissions can be revoked and granted during the execution of the class via a
|
|
nested <code>permissions</code> element. For more information please
|
|
see <a href="../Types/permissions.html">permissions</a>.</p>
|
|
<p>When the permission <code>RuntimePermission exitVM</code> has not been granted (or has been
|
|
revoked) the <code>System.exit()</code> call will be intercepted and treated like indicated
|
|
in <var>failonerror</var>.</p>
|
|
<p><strong>Note</strong>:<br/> If you do not specify permissions, a set of default permissions will
|
|
be added to your Java invocation to make sure that the Ant run will continue or terminated as
|
|
indicated by <var>failonerror</var>. All permissions not granted per default will be checked by
|
|
whatever security manager was already in place. <code>exitVM</code> will be disallowed.</p>
|
|
<p>Settings will be ignored if <var>fork</var> is <q>true</q>.</p>
|
|
|
|
<h4>assertions</h4>
|
|
|
|
<p><em>Since Ant 1.6</em>.</p>
|
|
|
|
<p>You can control enablement of Java 1.4 assertions with
|
|
an <a href="../Types/assertions.html"><code><assertions></code></a> subelement.</p>
|
|
|
|
<p>Assertion statements are currently ignored in non-forked mode.</p>
|
|
|
|
<h4 id="redirector">redirector</h4>
|
|
<em>Since Ant 1.6.2</em>
|
|
<p>A nested <a href="../Types/redirector.html">I/O Redirector</a> can be specified. In general, the
|
|
attributes of the redirector behave as the corresponding attributes available at the task level.
|
|
The most notable peculiarity stems from the retention of the <code><java></code> attributes
|
|
for backwards compatibility. Any file mapping is done using a <code>null</code> sourcefile;
|
|
therefore not all <a href="../Types/mapper.html">Mapper</a> types will return results. When no
|
|
results are returned, redirection specifications will fall back to the task level attributes. In
|
|
practice this means that defaults can be specified for <var>input</var>, <var>output</var>,
|
|
and <var>error</var> output files.</p>
|
|
<h3 id="failonerror">Errors and return codes</h3>
|
|
<p>By default, the return code of a <code><java></code> is ignored. Alternatively, you can
|
|
set <var>resultproperty</var> to the name of a property and have it assigned to the result code
|
|
(barring immutability, of course). When you set <var>failonerror</var>=<q>true</q>, the only
|
|
possible value for <var>resultproperty</var> is <q>0</q>. Any non-zero response is treated as an
|
|
error and would mean the build exits.</p>
|
|
<p>Similarly, if <var>failonerror</var>=<q>false</q> and <var>fork</var>=<q>false</q>,
|
|
then <code><java></code> <em>must</em> return <q>0</q> otherwise the build will exit, as the
|
|
class was run by the build JVM.</p>
|
|
|
|
<h4 id="modulepath">modulepath</h4>
|
|
<em>Since Ant 1.9.7</em>
|
|
<p><code>Java</code>'s <var>modulepath</var> attribute is a <a href="../using.html#path">path-like
|
|
structure</a> and can also be set via a nested <code>modulepath</code> element.</p>
|
|
|
|
<h4 id="upgrademodulepath">upgrademodulepath</h4>
|
|
<em>Since Ant 1.9.7</em>
|
|
<p>The location of modules that replace upgradeable modules in the runtime image can be specified
|
|
using this <a href="../using.html#path">path-like structure</a>.</p>
|
|
|
|
<h3 id="jar-execute">JAR file execution</h3>
|
|
|
|
<p>The parameter of the <var>jar</var> attribute is of type <code>File</code>; that is, the
|
|
parameter is resolved to an absolute file relative to the base directory of the
|
|
project, <em>not</em> the directory in which the Java task is run. If you need to locate a JAR file
|
|
relative to the directory the task will be run in, you need to explicitly create the full path to
|
|
the JAR file.</p>
|
|
<p>When using the <var>jar</var> attribute, all classpath settings are ignored according
|
|
to <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/java.html">Oracle's
|
|
specification</a>.
|
|
|
|
<h3>Examples</h3>
|
|
<pre>
|
|
<java classname="test.Main">
|
|
<arg value="-h"/>
|
|
<classpath>
|
|
<pathelement location="dist/test.jar"/>
|
|
<pathelement path="${java.class.path}"/>
|
|
</classpath>
|
|
</java></pre>
|
|
Run a class in this JVM with a new jar on the classpath
|
|
|
|
<pre>
|
|
<java jar="dist/test.jar"
|
|
fork="true"
|
|
failonerror="true"
|
|
maxmemory="128m">
|
|
<arg value="-h"/>
|
|
<classpath>
|
|
<pathelement location="dist/test.jar"/>
|
|
<pathelement path="${java.class.path}"/>
|
|
</classpath>
|
|
</java></pre>
|
|
<p>Run the JAR <samp>test.jar</samp> in this project's <samp>dist/lib</samp> directory. using the
|
|
manifest supplied entry point, forking (as required), and with a maximum memory of 128 MB. Any non
|
|
zero return code breaks the build.</p>
|
|
|
|
<pre>
|
|
<java dir="${exec.dir}"
|
|
jar="${exec.dir}/dist/test.jar"
|
|
fork="true"
|
|
failonerror="true"
|
|
maxmemory="128m">
|
|
<arg value="-h"/>
|
|
<classpath>
|
|
<pathelement location="dist/test.jar"/>
|
|
<pathelement path="${java.class.path}"/>
|
|
</classpath>
|
|
</java></pre>
|
|
<p>Run the JAR <samp>dist/test.jar</samp> relative to the directory <code>${exec.dir}</code>, this
|
|
being the same directory in which JVM is to start up.</p>
|
|
|
|
<pre><java classname="test.Main"/></pre>
|
|
<p>Runs a given class with the current classpath.</p>
|
|
|
|
<pre>
|
|
<java classname="test.Main"
|
|
fork="yes" >
|
|
<sysproperty key="DEBUG" value="true"/>
|
|
<arg value="-h"/>
|
|
<jvmarg value="-Xrunhprof:cpu=samples,file=log.txt,depth=3"/>
|
|
</java></pre>
|
|
<p>Add system properties and JVM properties to JVM as in <code>java
|
|
-Xrunhprof:cpu=samples,file=log.txt,depth=3 -DDEBUG=true test.Main</code>
|
|
|
|
<pre>
|
|
<java classname="ShowJavaVersion" classpath="."
|
|
jvm="path-to-java14-home/bin/java" fork="true"
|
|
taskname="java1.4"/></pre>
|
|
<p>Use a given Java implementation (other than the one Ant is currently using) to run the class.
|
|
For documentation in the log <var>taskname</var> is used to change the <q>[java]</q> log-prefix
|
|
to <q>[java1.4]</q>.</p>
|
|
|
|
<p><strong>Note</strong>: you can not specify the (highly deprecated) MS
|
|
JVM, <samp>jview.exe</samp>, as <var>jvm</var>, since it takes different parameters than other JVMs.
|
|
That JVM can be started from <code><exec></code> if required.</p>
|
|
|
|
<pre>
|
|
<java fork="true"
|
|
failonerror="true"
|
|
maxmemory="128m"
|
|
module="TestModule"
|
|
modulepath="lib:dist/test.jar"/></pre>
|
|
<p>Runs the module <samp>TestModule</samp> resolved on the
|
|
modulepath <samp>lib/:dist/test.jar</samp> with a maximum memory of 128 MB. Any non zero return code
|
|
breaks the build.</p>
|
|
|
|
<pre>
|
|
<java fork="true"
|
|
failonerror="true"
|
|
maxmemory="128m"
|
|
module="TestModule"
|
|
classname="Main">
|
|
<modulepath>
|
|
<pathelement location="lib"/>
|
|
<pathelement location="dist/test.jar"/>
|
|
</modulepath>
|
|
</java></pre>
|
|
<p>Runs the class <samp>Main</samp> in module <samp>TestModule</samp> resolved on the
|
|
modulepath <samp>lib/:dist/test.jar</samp> with a maximum memory of 128 MB. Any non zero return code
|
|
breaks the build.</p>
|
|
</body>
|
|
</html>
|