Java (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.taskdefs, class: Java

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

  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​(String output)`
  Handle output sent to System.err and flush the stream.
  `protected void`
  `handleErrorOutput​(String output)`
  Handle output sent to System.err.
  `protected void`
  `handleFlush​(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​(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​(String classname, Vector<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​(String s)`
  Deprecated: use nested arg instead.
  `void`
  `setClassname​(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​(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​(File error)`
  Set the File to which the error stream of the process is redirected.
  `void`
  `setErrorProperty​(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​(File input)`
  Set the input to use for the task.
  `void`
  `setInputString​(String inputString)`
  Set the string to use as input.
  `void`
  `setJar​(File jarfile)`
  Set the location of the JAR file to execute.
  `void`
  `setJvm​(String s)`
  Set the command used to start the VM (only if forking).
  `void`
  `setJvmargs​(String s)`
  Set the command line arguments for the JVM.
  `void`
  `setJVMVersion​(String value)`
  Set the JVM version.
  `void`
  `setLogError​(boolean logError)`
  Set whether error output of exec is logged.
  `void`
  `setMaxmemory​(String max)`
  Corresponds to -mx or -Xmx depending on VM version.
  `void`
  `setModule​(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​(File out)`
  Set the File to which the output of the process is redirected.
  `void`
  `setOutputproperty​(String outputProp)`
  Set the property name whose value should be set to the output of the process.
  `void`
  `setResultProperty​(String resultProperty)`
  Set the name of the property in which the return code of the command should be stored.
  `void`
  `setSourceFile​(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​(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 Details

  - ### redirector

    protected Redirector redirector

  - ### redirectorElement

    protected RedirectorElement redirectorElement

- ## Constructor Details

  - ### Java

    public Java()
    Normal constructor

  - ### Java

    public Java​(Task owner)
    create a bound task
    Parameters:
      `owner` - owner

- ## Method Details

  - ### 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​(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​(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​(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​(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​(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​(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​(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​(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​(File d)
    Set the working directory of the process.
    Parameters:
      `d` - working directory.

  - ### setOutput

    public void setOutput​(File out)
    Set the File to which the output of the process is redirected.
    Parameters:
      `out` - the output File.

  - ### setInput

    public void setInput​(File input)
    Set the input to use for the task.
    Parameters:
      `input` - name of the input file.

  - ### setInputString

    public void setInputString​(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​(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​(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​(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​(String max)
    Corresponds to -mx or -Xmx depending on VM version.
    Parameters:
      `max` - max memory parameter.

  - ### setJVMVersion

    public void setJVMVersion​(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​(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​(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 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:
      `IOException` - if the data cannot be read.
    Since:
      Ant 1.6

  - ### handleFlush

    protected void handleFlush​(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​(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​(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​(String classname, Vector<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