Java

Description

Executes a Java class within the running (Apache 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.

Running Ant as a background process on Unix(-like) systems

If you run Ant as a background process (like ant &) and use the <java> task with spawn set to false and fork to true, you must provide explicit input to the forked process or Ant will be suspended because it tries to read from the standard input.

Parameters

Parameters specified as nested elements

arg and jvmarg

Use nested <arg> and <jvmarg> elements to specify arguments for the Java class and the forked VM respectively. See Command line arguments.

sysproperty

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.

syspropertyset

You can specify a set of properties to be used as system properties with syspropertysets.

since Ant 1.6.

classpath

Java's classpath attribute is a PATH like structure and can also be set via a nested classpath element.

bootclasspath

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.

env

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.

permissions

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.

assertions

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.

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.

Java's modulepath attribute is a PATH like structure and can also be set via a nested modulepath element.

The location of modules that replace upgradeable modules in the runtime image can be specified using this PATH like structure.

JAR file execution

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 Oracle's specification.

Examples

       <java classname="test.Main">
         <arg value="-h"/>
         <classpath>
           <pathelement location="dist/test.jar"/>
           <pathelement path="${java.class.path}"/>
         </classpath>
       </java>

       <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>

       <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>

  <java classname="test.Main"/>

  <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>

  <java classname="ShowJavaVersion" classpath="."
        jvm="path-to-java14-home/bin/java" fork="true"
        taskname="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.

       <java
           fork="true"
           failonerror="true"
           maxmemory="128m"
           module="TestModule"
           modulepath="lib:dist/test.jar"/>

       <java
           fork="true"
           failonerror="true"
           maxmemory="128m"
           module="TestModule"
           classname="Main">
         <modulepath>
           <pathelement location="lib"/>
           <pathelement location="dist/test.jar"/>
         </modulepath>
       </java>