Executes a Java class within the running (Ant) VM or forks another VM if specified.
If odd things go wrong when you run this task, set fork="true" to use a new JVM.
As of Ant 1.6.3, you can interact with a forked VM, as well as
sending input to it via the input and inputstring
attributes.
| Attribute | Description | Required |
| classname | the Java class to execute. | Either jar or classname |
| jar | 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. See notes below for more details. | Either jar or classname |
| args | the arguments for the class that is
executed. deprecated, use nested <arg>
elements instead. |
No |
| classpath | the classpath to use. | No |
| classpathref | the classpath to use, given as reference to a PATH defined elsewhere. | No |
| fork | if enabled triggers the class execution in another VM (disabled by default) | No |
| spawn | if enabled allows to start a process which will outlive ant. Requires fork=true, and not compatible with timeout, input, output, error, result attributes. (disabled by default) |
No |
| jvm | 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. | No |
| jvmargs | the arguments to pass to the forked VM (ignored
if fork is disabled). deprecated, use nested
<jvmarg> elements instead. |
No |
| maxmemory | Max amount of memory to allocate to the forked VM (ignored if fork is disabled) | No |
| failonerror | Stop the buildprocess if the command exits with a returncode other than 0. Default is "false" (see note) | No |
| resultproperty | 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. | No |
| dir | The directory to invoke the VM in. (ignored if fork is disabled) | No |
| output | 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. | No |
| error | The file to which the standard error of the command should be redirected. | No |
| logError | 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 "error" or "errorProperty" attributes, this will have no effect. | No |
| append | Whether output and error files should be appended to or overwritten. Defaults to false. | No |
| outputproperty | 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. | No |
| errorproperty | The name of a property in which the standard error of the command should be stored. | No |
| input | A file from which the executed command's standard input is taken. This attribute is mutually exclusive with the inputstring attribute | No; default is to take standard input from console
(unless spawn="true") |
| inputstring | A string which serves as the input stream for the executed command. This attribute is mutually exclusive with the input attribute. | No; default is to take standard input from console
(unless spawn="true") |
| newenvironment | Do not propagate old environment when new environment variables are specified. Default is "false" (ignored if fork is disabled). | No |
| timeout | Stop the command if it doesn't finish within the specified time (given in milliseconds). It is highly recommended to use this feature only if fork is enabled. | No |
| clonevm | If set to true true, then all system properties and the bootclasspath of the forked Java Virtual Machine will be the same as those of the Java VM running Ant. Default is "false" (ignored if fork is disabled). since Ant 1.7 | No |
Use nested <arg> and <jvmarg>
elements to specify arguments for the Java class and the forked VM respectively.
See Command line arguments.
Use nested <sysproperty>
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 environment
variables.
You can specify a set of properties to be used as system properties with syspropertysets.
since Ant 1.6.
Java's classpath attribute is a PATH like structure and can also be set via a nested
classpath element.
The location of bootstrap class files can be specified using this
PATH like structure - will be ignored
if fork is not true or the target VM doesn't
support it (i.e. Java 1.1).
since Ant 1.6.
It is possible to specify environment variables to pass to the forked VM via nested env elements. See the description in the section about exec
Settings will be ignored if fork is disabled.
Security permissions can be revoked and granted during the execution of the class via a nested permissions element. For more information please see permissions
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 failonerror.
Note:
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
failonerror. All permissions not granted per default will be
checked by whatever security manager was already in place. exitVM will be
disallowed.
Settings will be ignored if fork is enabled.
since Ant 1.6.
You can control enablement of Java 1.4 assertions with an <assertions> subelement.
Assertion statements are currently ignored in non-forked mode.
since Ant 1.6.
A nested I/O Redirector
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 <java>
attributes for backwards compatibility. Any file mapping is done
using a null sourcefile; therefore not all
Mapper 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 input, output, and error output files.
<java> is ignored.
Alternatively, you can set resultproperty to the name
of a property and have it assigned to the result code (barring immutability,
of course).
When you set failonerror="true", the only possible value for
resultproperty is 0. Any non-zero response is treated as an
error and would mean the build exits.
Similarly, if failonerror="false" and fork="false"
, then <java> must return 0 otherwise the build will
exit, as the class was run by the build JVM.
The parameter of the jar attribute is of type File; that is, the parameter is resolved to an absolute file relative to the base directory of the project, not 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.
When using the jar attribute, all classpath settings are ignored according to Sun's specification.
<java classname="test.Main">
<arg value="-h"/>
<classpath>
<pathelement location="dist/test.jar"/>
<pathelement path="/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-launcher.jar:/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Classes/.compatibility/14compatibility.jar:/Users/antoine/dev/asf/ant-core/lib/optional/activation.jar:/Users/antoine/dev/asf/ant-core/lib/optional/ant-antunit-1.0Beta2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/antlrall.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bcel.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsf-2.4.0.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsh-2.0b4.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsh-core-2.0b4.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-logging-api.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-logging.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-net-1.4.0.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jai_codec.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jai_core.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jakarta-oro-2.0.8.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jakarta-regexp-1.2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jdepend.jar:/Users/antoine/dev/asf/ant-core/lib/optional/js-1.6R3.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jsch-0.1.29.jar:/Users/antoine/dev/asf/ant-core/lib/optional/junit-3.8.2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jython.jar:/Users/antoine/dev/asf/ant-core/lib/optional/log4j-1.2.9.jar:/Users/antoine/dev/asf/ant-core/lib/optional/mail.jar:/Users/antoine/dev/asf/ant-core/lib/optional/NetRexxC.jar:/Users/antoine/dev/asf/ant-core/lib/optional/NetRexxR.jar:/Users/antoine/dev/asf/ant-core/lib/optional/resolver.jar:/Users/antoine/dev/asf/ant-core/lib/optional/starteam-sdk.jar:/Users/antoine/dev/asf/ant-core/lib/optional/stylebook-1.0-b2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogic.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogicaux.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogicclasses.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xalan.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xalan1.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xercesSamples.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xmlParserAPIs.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xsltc.jar:/Users/antoine/dev/asf/ant-core/lib/optional:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-antlr.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-bcel.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-bsf.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-log4j.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-oro.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-regexp.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-resolver.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-commons-logging.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-commons-net.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jai.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-javamail.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jdepend.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jmf.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jsch.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-junit.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-launcher.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-netrexx.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-nodeps.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-starteam.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-stylebook.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-swing.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-testutil.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-trax.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-weblogic.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/xercesImpl.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/xml-apis.jar"/>
</classpath>
</java>
Run a class in this JVM with a new jar on the classpath
<java jar="dist/test.jar"
fork="true"
failonerror="true"
maxmemory="128m"
>
<arg value="-h"/>
<classpath>
<pathelement location="dist/test.jar"/>
<pathelement path="/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-launcher.jar:/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Classes/.compatibility/14compatibility.jar:/Users/antoine/dev/asf/ant-core/lib/optional/activation.jar:/Users/antoine/dev/asf/ant-core/lib/optional/ant-antunit-1.0Beta2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/antlrall.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bcel.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsf-2.4.0.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsh-2.0b4.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsh-core-2.0b4.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-logging-api.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-logging.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-net-1.4.0.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jai_codec.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jai_core.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jakarta-oro-2.0.8.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jakarta-regexp-1.2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jdepend.jar:/Users/antoine/dev/asf/ant-core/lib/optional/js-1.6R3.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jsch-0.1.29.jar:/Users/antoine/dev/asf/ant-core/lib/optional/junit-3.8.2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jython.jar:/Users/antoine/dev/asf/ant-core/lib/optional/log4j-1.2.9.jar:/Users/antoine/dev/asf/ant-core/lib/optional/mail.jar:/Users/antoine/dev/asf/ant-core/lib/optional/NetRexxC.jar:/Users/antoine/dev/asf/ant-core/lib/optional/NetRexxR.jar:/Users/antoine/dev/asf/ant-core/lib/optional/resolver.jar:/Users/antoine/dev/asf/ant-core/lib/optional/starteam-sdk.jar:/Users/antoine/dev/asf/ant-core/lib/optional/stylebook-1.0-b2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogic.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogicaux.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogicclasses.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xalan.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xalan1.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xercesSamples.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xmlParserAPIs.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xsltc.jar:/Users/antoine/dev/asf/ant-core/lib/optional:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-antlr.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-bcel.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-bsf.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-log4j.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-oro.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-regexp.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-resolver.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-commons-logging.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-commons-net.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jai.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-javamail.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jdepend.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jmf.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jsch.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-junit.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-launcher.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-netrexx.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-nodeps.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-starteam.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-stylebook.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-swing.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-testutil.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-trax.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-weblogic.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/xercesImpl.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/xml-apis.jar"/>
</classpath>
</java>
Run the JAR test.jar in this project's dist/lib directory.
using the manifest supplied entry point, forking (as required),
and with a maximum memory of 128MB. Any non zero return code breaks the build.
<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="/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-launcher.jar:/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Classes/.compatibility/14compatibility.jar:/Users/antoine/dev/asf/ant-core/lib/optional/activation.jar:/Users/antoine/dev/asf/ant-core/lib/optional/ant-antunit-1.0Beta2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/antlrall.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bcel.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsf-2.4.0.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsh-2.0b4.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsh-core-2.0b4.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-logging-api.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-logging.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-net-1.4.0.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jai_codec.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jai_core.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jakarta-oro-2.0.8.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jakarta-regexp-1.2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jdepend.jar:/Users/antoine/dev/asf/ant-core/lib/optional/js-1.6R3.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jsch-0.1.29.jar:/Users/antoine/dev/asf/ant-core/lib/optional/junit-3.8.2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jython.jar:/Users/antoine/dev/asf/ant-core/lib/optional/log4j-1.2.9.jar:/Users/antoine/dev/asf/ant-core/lib/optional/mail.jar:/Users/antoine/dev/asf/ant-core/lib/optional/NetRexxC.jar:/Users/antoine/dev/asf/ant-core/lib/optional/NetRexxR.jar:/Users/antoine/dev/asf/ant-core/lib/optional/resolver.jar:/Users/antoine/dev/asf/ant-core/lib/optional/starteam-sdk.jar:/Users/antoine/dev/asf/ant-core/lib/optional/stylebook-1.0-b2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogic.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogicaux.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogicclasses.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xalan.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xalan1.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xercesSamples.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xmlParserAPIs.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xsltc.jar:/Users/antoine/dev/asf/ant-core/lib/optional:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-antlr.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-bcel.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-bsf.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-log4j.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-oro.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-regexp.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-resolver.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-commons-logging.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-commons-net.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jai.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-javamail.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jdepend.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jmf.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jsch.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-junit.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-launcher.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-netrexx.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-nodeps.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-starteam.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-stylebook.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-swing.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-testutil.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-trax.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-weblogic.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/xercesImpl.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/xml-apis.jar"/>
</classpath>
</java>
Run the JAR dist/test.jar relative to the directory
${exec.dir}, this being the same directory into which the JVM
is to start up.
<java classname="test.Main"/>Runs a given class with the current classpath.
<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>
Add system properties and JVM-properties to the JVM as in
java ="-Xrunhprof:cpu=samples,file=log.txt,depth=3 -DDEBUG=true test.Main
<java classname="ShowJavaVersion" classpath="."
jvm="path-to-java14-home/bin/java" fork="true"
taskname="java1.4" >
Use a given Java implementation (another the one Ant is currently using) to run the class.
For documentation in the log taskname is used to change the [java]
log-prefix to [java1.4].
Note: 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 <exec> if required.