Java (Apache Ant API)

Package org.apache.tools.ant.taskdefs

## Class Java

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.tools.ant.taskdefs.Java

- All Implemented Interfaces:
    `java.lang.Cloneable`

      public class Java
      extends Task

  Launcher for Java applications. Allows use of the same JVM for the called application thus resulting in much faster operation.
  Since:
    Ant 1.1

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Redirector` | `redirector` |
    `protected RedirectorElement` | `redirectorElement` |

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Java()` | Normal constructor
    `Java​(Task owner)` | create a bound task

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addAssertions​(Assertions asserts)` | Add assertions to enable in this program (if fork=true).
    `void` | `addConfiguredRedirector​(RedirectorElement redirectorElement)` | Add a `RedirectorElement` to this task.
    `void` | `addEnv​(Environment.Variable var)` | Add an environment variable.
    `void` | `addSysproperty​(Environment.Variable sysp)` | Add a system property.
    `void` | `addSyspropertyset​(PropertySet sysp)` | Add a set of properties as system properties.
    `protected void` | `checkConfiguration()` | Check configuration.
    `void` | `clearArgs()` | Clear out the arguments to this java task.
    `Commandline.Argument` | `createArg()` | Add a command-line argument.
    `Path` | `createBootclasspath()` | Add a path to the bootclasspath.
    `Path` | `createClasspath()` | Add a path to the classpath.
    `Commandline.Argument` | `createJvmarg()` | Adds a JVM argument.
    `Path` | `createModulepath()` | Add a path to the modulepath.
    `Permissions` | `createPermissions()` | Set the permissions for the application run inside the same JVM.
    `Path` | `createUpgrademodulepath()` | Add a path to the upgrademodulepath.
    `protected ExecuteWatchdog` | `createWatchdog()` | Create the Watchdog to kill a runaway process.
    `void` | `execute()` | Do the execution.
    `int` | `executeJava()` | Do the execution and return a return code.
    `protected int` | `executeJava​(CommandlineJava commandLine)` | Execute the specified CommandlineJava.
    `CommandlineJava` | `getCommandLine()` | Accessor to the command line.
    `CommandlineJava.SysProperties` | `getSysProperties()` | Get the system properties of the command line.
    `protected void` | `handleErrorFlush​(java.lang.String output)` | Handle output sent to System.err and flush the stream.
    `protected void` | `handleErrorOutput​(java.lang.String output)` | Handle output sent to System.err.
    `protected void` | `handleFlush​(java.lang.String output)` | Pass output sent to System.out to specified output file.
    `int` | `handleInput​(byte[] buffer, int offset, int length)` | Handle an input request by this task.
    `protected void` | `handleOutput​(java.lang.String output)` | Pass output sent to System.out to specified output file.
    `protected void` | `maybeSetResultPropertyValue​(int result)` | Helper method to set result property to the passed in value if appropriate.
    `protected void` | `run​(java.lang.String classname, java.util.Vector<java.lang.String> args)` | Executes the given classname with the given arguments as if it were a command line application.
    `void` | `setAppend​(boolean append)` | If true, append output to existing file.
    `void` | `setArgs​(java.lang.String s)` | Deprecated: use nested arg instead.
    `void` | `setClassname​(java.lang.String s)` | Set the Java class to execute.
    `void` | `setClasspath​(Path s)` | Set the classpath to be used when running the Java class.
    `void` | `setClasspathRef​(Reference r)` | Set the classpath to use by reference.
    `void` | `setCloneVm​(boolean cloneVm)` | If set, system properties will be copied to the cloned VM--as well as the bootclasspath unless you have explicitly specified a bootclasspath.
    `void` | `setDir​(java.io.File d)` | Set the working directory of the process.
    `void` | `setDiscardError​(boolean discard)` | Whether error output should be discarded.
    `void` | `setDiscardOutput​(boolean discard)` | Whether output should be discarded.
    `void` | `setError​(java.io.File error)` | Set the File to which the error stream of the process is redirected.
    `void` | `setErrorProperty​(java.lang.String errorProperty)` | Set the property name whose value should be set to the error of the process.
    `void` | `setFailonerror​(boolean fail)` | If true, then fail if the command exits with a returncode other than zero.
    `void` | `setFork​(boolean s)` | If true, execute in a new VM.
    `void` | `setInput​(java.io.File input)` | Set the input to use for the task.
    `void` | `setInputString​(java.lang.String inputString)` | Set the string to use as input.
    `void` | `setJar​(java.io.File jarfile)` | Set the location of the JAR file to execute.
    `void` | `setJvm​(java.lang.String s)` | Set the command used to start the VM (only if forking).
    `void` | `setJvmargs​(java.lang.String s)` | Set the command line arguments for the JVM.
    `void` | `setJVMVersion​(java.lang.String value)` | Set the JVM version.
    `void` | `setLogError​(boolean logError)` | Set whether error output of exec is logged.
    `void` | `setMaxmemory​(java.lang.String max)` | Corresponds to -mx or -Xmx depending on VM version.
    `void` | `setModule​(java.lang.String module)` | Set the Java module to execute.
    `void` | `setModulepath​(Path mp)` | Set the modulepath to be used when running the Java class.
    `void` | `setModulepathRef​(Reference r)` | Set the modulepath to use by reference.
    `void` | `setNewenvironment​(boolean newenv)` | If true, use a completely new environment.
    `void` | `setOutput​(java.io.File out)` | Set the File to which the output of the process is redirected.
    `void` | `setOutputproperty​(java.lang.String outputProp)` | Set the property name whose value should be set to the output of the process.
    `void` | `setResultProperty​(java.lang.String resultProperty)` | Set the name of the property in which the return code of the command should be stored.
    `void` | `setSourceFile​(java.lang.String sourceFile)` | Set the Java source-file to execute.
    `void` | `setSpawn​(boolean spawn)` | Set whether or not you want the process to be spawned; default is not spawned.
    `void` | `setTimeout​(java.lang.Long value)` | Set the timeout in milliseconds after which the process will be killed.
    `protected void` | `setupRedirector()` | Set up properties on the redirector that we needed to store locally.

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### redirector

          protected Redirector redirector

    - #### redirectorElement

          protected RedirectorElement redirectorElement

  - ### Constructor Detail

    - #### Java

          public Java()

      Normal constructor

    - #### Java

          public Java​(Task owner)

      create a bound task
      Parameters:
        `owner` - owner

  - ### Method Detail

    - #### execute

          public void execute()
                       throws BuildException

      Do the execution.
      Overrides:
        `execute` in class `Task`
      Throws:
        `BuildException` - if failOnError is set to true and the application returns a nonzero result code.

    - #### executeJava

          public int executeJava()
                          throws BuildException

      Do the execution and return a return code.
      Returns:
        the return code from the execute java class if it was executed in a separate VM (fork = "yes") or a security manager was installed that prohibits ExitVM (default).
      Throws:
        `BuildException` - if required parameters are missing.

    - #### checkConfiguration

          protected void checkConfiguration()
                                     throws BuildException

      Check configuration.
      Throws:
        `BuildException` - if required parameters are missing.

    - #### executeJava

          protected int executeJava​(CommandlineJava commandLine)

      Execute the specified CommandlineJava.
      Parameters:
        `commandLine` - CommandLineJava instance.
      Returns:
        the exit value of the process if forked, 0 otherwise.

    - #### setSpawn

          public void setSpawn​(boolean spawn)

      Set whether or not you want the process to be spawned; default is not spawned.
      Parameters:
        `spawn` - if true you do not want Ant to wait for the end of the process.
      Since:
        Ant 1.6

    - #### setClasspath

          public void setClasspath​(Path s)

      Set the classpath to be used when running the Java class.
      Parameters:
        `s` - an Ant Path object containing the classpath.

    - #### createClasspath

          public Path createClasspath()

      Add a path to the classpath.
      Returns:
        created classpath.

    - #### createBootclasspath

          public Path createBootclasspath()

      Add a path to the bootclasspath.
      Returns:
        created bootclasspath.
      Since:
        Ant 1.6

    - #### setModulepath

          public void setModulepath​(Path mp)

      Set the modulepath to be used when running the Java class.
      Parameters:
        `mp` - an Ant Path object containing the modulepath.
      Since:
        1.9.7

    - #### createModulepath

          public Path createModulepath()

      Add a path to the modulepath.
      Returns:
        created modulepath.
      Since:
        1.9.7

    - #### setModulepathRef

          public void setModulepathRef​(Reference r)

      Set the modulepath to use by reference.
      Parameters:
        `r` - a reference to an existing modulepath.
      Since:
        1.9.7

    - #### createUpgrademodulepath

          public Path createUpgrademodulepath()

      Add a path to the upgrademodulepath.
      Returns:
        created upgrademodulepath.
      Since:
        1.9.7

    - #### createPermissions

          public Permissions createPermissions()

      Set the permissions for the application run inside the same JVM.
      Returns:
        Permissions.
      Since:
        Ant 1.6

    - #### setClasspathRef

          public void setClasspathRef​(Reference r)

      Set the classpath to use by reference.
      Parameters:
        `r` - a reference to an existing classpath.

    - #### setJar

          public void setJar​(java.io.File jarfile)
                      throws BuildException

      Set the location of the JAR file to execute.
      Parameters:
        `jarfile` - the jarfile to execute.
      Throws:
        `BuildException` - if there is also a `classname`, `module` or `sourcefile` attribute specified

    - #### setClassname

          public void setClassname​(java.lang.String s)
                            throws BuildException

      Set the Java class to execute.
      Parameters:
        `s` - the name of the main class.
      Throws:
        `BuildException` - if there is also a `jar` or `sourcefile` attribute specified

    - #### setModule

          public void setModule​(java.lang.String module)
                         throws BuildException

      Set the Java module to execute.
      Parameters:
        `module` - the name of the module.
      Throws:
        `BuildException` - if there is also a `jar` or `sourcefile` attribute specified
      Since:
        1.9.7

    - #### setSourceFile

          public void setSourceFile​(java.lang.String sourceFile)
                             throws BuildException

      Set the Java source-file to execute. Support for single file source program execution, in Java, is only available since Java 11.
      Parameters:
        `sourceFile` - The path to the source file
      Throws:
        `BuildException` - if there is also a `jar`, `classname` or `module` attribute specified
      Since:
        Ant 1.10.5

    - #### setArgs

          public void setArgs​(java.lang.String s)

      Deprecated: use nested arg instead. Set the command line arguments for the class.
      Parameters:
        `s` - arguments.

    - #### setCloneVm

          public void setCloneVm​(boolean cloneVm)

      If set, system properties will be copied to the cloned VM--as well as the bootclasspath unless you have explicitly specified a bootclasspath.

      Doesn't have any effect unless fork is true.

      Parameters:
        `cloneVm` - if true copy system properties.
      Since:
        Ant 1.7

    - #### createArg

          public Commandline.Argument createArg()

      Add a command-line argument.
      Returns:
        created argument.

    - #### setResultProperty

          public void setResultProperty​(java.lang.String resultProperty)

      Set the name of the property in which the return code of the command should be stored. Only of interest if failonerror=false.
      Parameters:
        `resultProperty` - name of property.
      Since:
        Ant 1.6

    - #### maybeSetResultPropertyValue

          protected void maybeSetResultPropertyValue​(int result)

      Helper method to set result property to the passed in value if appropriate.
      Parameters:
        `result` - the exit code

    - #### setFork

          public void setFork​(boolean s)

      If true, execute in a new VM.
      Parameters:
        `s` - do you want to run Java in a new VM.

    - #### setJvmargs

          public void setJvmargs​(java.lang.String s)

      Set the command line arguments for the JVM.
      Parameters:
        `s` - jvmargs.

    - #### createJvmarg

          public Commandline.Argument createJvmarg()

      Adds a JVM argument.
      Returns:
        JVM argument created.

    - #### setJvm

          public void setJvm​(java.lang.String s)

      Set the command used to start the VM (only if forking).
      Parameters:
        `s` - command to start the VM.

    - #### addSysproperty

          public void addSysproperty​(Environment.Variable sysp)

      Add a system property.
      Parameters:
        `sysp` - system property.

    - #### addSyspropertyset

          public void addSyspropertyset​(PropertySet sysp)

      Add a set of properties as system properties.
      Parameters:
        `sysp` - set of properties to add.
      Since:
        Ant 1.6

    - #### setFailonerror

          public void setFailonerror​(boolean fail)

      If true, then fail if the command exits with a returncode other than zero.
      Parameters:
        `fail` - if true fail the build when the command exits with a nonzero returncode.

    - #### setDir

          public void setDir​(java.io.File d)

      Set the working directory of the process.
      Parameters:
        `d` - working directory.

    - #### setOutput

          public void setOutput​(java.io.File out)

      Set the File to which the output of the process is redirected.
      Parameters:
        `out` - the output File.

    - #### setInput

          public void setInput​(java.io.File input)

      Set the input to use for the task.
      Parameters:
        `input` - name of the input file.

    - #### setInputString

          public void setInputString​(java.lang.String inputString)

      Set the string to use as input.
      Parameters:
        `inputString` - the string which is used as the input source.

    - #### setLogError

          public void setLogError​(boolean logError)

      Set whether error output of exec is logged. This is only useful when output is being redirected and error output is desired in the Ant log.
      Parameters:
        `logError` - get in the ant log the messages coming from stderr in the case that fork = true.

    - #### setError

          public void setError​(java.io.File error)

      Set the File to which the error stream of the process is redirected.
      Parameters:
        `error` - file getting the error stream.
      Since:
        Ant 1.6

    - #### setOutputproperty

          public void setOutputproperty​(java.lang.String outputProp)

      Set the property name whose value should be set to the output of the process.
      Parameters:
        `outputProp` - property name.

    - #### setErrorProperty

          public void setErrorProperty​(java.lang.String errorProperty)

      Set the property name whose value should be set to the error of the process.
      Parameters:
        `errorProperty` - property name.
      Since:
        Ant 1.6

    - #### setMaxmemory

          public void setMaxmemory​(java.lang.String max)

      Corresponds to -mx or -Xmx depending on VM version.
      Parameters:
        `max` - max memory parameter.

    - #### setJVMVersion

          public void setJVMVersion​(java.lang.String value)

      Set the JVM version.
      Parameters:
        `value` - JVM version.

    - #### addEnv

          public void addEnv​(Environment.Variable var)

      Add an environment variable.

      Will be ignored if we are not forking a new VM.

      Parameters:
        `var` - new environment variable.
      Since:
        Ant 1.5

    - #### setNewenvironment

          public void setNewenvironment​(boolean newenv)

      If true, use a completely new environment.

      Will be ignored if we are not forking a new VM.

      Parameters:
        `newenv` - if true, use a completely new environment.
      Since:
        Ant 1.5

    - #### setAppend

          public void setAppend​(boolean append)

      If true, append output to existing file.
      Parameters:
        `append` - if true, append output to existing file.
      Since:
        Ant 1.5

    - #### setDiscardOutput

          public void setDiscardOutput​(boolean discard)

      Whether output should be discarded.

      Defaults to false.

      Parameters:
        `discard` - if true output streams are discarded.
      Since:
        Ant 1.10.10
      See Also:
        `setDiscardError(boolean)`

    - #### setDiscardError

          public void setDiscardError​(boolean discard)

      Whether error output should be discarded.

      Defaults to false.

      Parameters:
        `discard` - if true error streams are discarded.
      Since:
        Ant 1.10.10
      See Also:
        `setDiscardOutput(boolean)`

    - #### setTimeout

          public void setTimeout​(java.lang.Long value)

      Set the timeout in milliseconds after which the process will be killed.
      Parameters:
        `value` - timeout in milliseconds.
      Since:
        Ant 1.5

    - #### addAssertions

          public void addAssertions​(Assertions asserts)

      Add assertions to enable in this program (if fork=true).
      Parameters:
        `asserts` - assertion set.
      Since:
        Ant 1.6

    - #### addConfiguredRedirector

          public void addConfiguredRedirector​(RedirectorElement redirectorElement)

      Add a `RedirectorElement` to this task.
      Parameters:
        `redirectorElement` - `RedirectorElement`.

    - #### handleOutput

          protected void handleOutput​(java.lang.String output)

      Pass output sent to System.out to specified output file.
      Overrides:
        `handleOutput` in class `Task`
      Parameters:
        `output` - a string of output on its way to the handlers.
      Since:
        Ant 1.5

    - #### handleInput

          public int handleInput​(byte[] buffer,
                                 int offset,
                                 int length)
                          throws java.io.IOException

      Handle an input request by this task.
      Overrides:
        `handleInput` in class `Task`
      Parameters:
        `buffer` - the buffer into which data is to be read.
        `offset` - the offset into the buffer at which data is stored.
        `length` - the amount of data to read.
      Returns:
        the number of bytes read.
      Throws:
        `java.io.IOException` - if the data cannot be read.
      Since:
        Ant 1.6

    - #### handleFlush

          protected void handleFlush​(java.lang.String output)

      Pass output sent to System.out to specified output file.
      Overrides:
        `handleFlush` in class `Task`
      Parameters:
        `output` - string of output on its way to its handlers.
      Since:
        Ant 1.5.2

    - #### handleErrorOutput

          protected void handleErrorOutput​(java.lang.String output)

      Handle output sent to System.err.
      Overrides:
        `handleErrorOutput` in class `Task`
      Parameters:
        `output` - string of stderr.
      Since:
        Ant 1.5

    - #### handleErrorFlush

          protected void handleErrorFlush​(java.lang.String output)

      Handle output sent to System.err and flush the stream.
      Overrides:
        `handleErrorFlush` in class `Task`
      Parameters:
        `output` - string of stderr.
      Since:
        Ant 1.5.2

    - #### setupRedirector

          protected void setupRedirector()

      Set up properties on the redirector that we needed to store locally.

    - #### run

          protected void run​(java.lang.String classname,
                             java.util.Vector<java.lang.String> args)
                      throws BuildException

      Executes the given classname with the given arguments as if it were a command line application.
      Parameters:
        `classname` - the name of the class to run.
        `args` - arguments for the class.
      Throws:
        `BuildException` - in case of IOException in the execution.

    - #### clearArgs

          public void clearArgs()

      Clear out the arguments to this java task.

    - #### createWatchdog

          protected ExecuteWatchdog createWatchdog()
                                            throws BuildException

      Create the Watchdog to kill a runaway process.
      Returns:
        new watchdog.
      Throws:
        `BuildException` - under unknown circumstances.
      Since:
        Ant 1.5

    - #### getCommandLine

          public CommandlineJava getCommandLine()

      Accessor to the command line.
      Returns:
        the current command line.
      Since:
        1.6.3

    - #### getSysProperties

          public CommandlineJava.SysProperties getSysProperties()

      Get the system properties of the command line.
      Returns:
        the current properties of this java invocation.
      Since:
        1.6.3