Top Description Fields Constructors Methods
org.apache.tools.ant.taskdefs

public Class Java

extends Task
Class Inheritance
Imports
java.io.File, .IOException, java.util.Vector, org.apache.tools.ant.BuildException, .ExitException, .ExitStatusException, .Project, .Task, org.apache.tools.ant.taskdefs.condition.Os, org.apache.tools.ant.types.Assertions, .Commandline, .CommandlineJava, .Environment, .Path, .Permissions, .PropertySet, .RedirectorElement, .Reference, org.apache.tools.ant.util.KeepAliveInputStream, .SecurityManagerUtil, .StringUtils
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

Modifier and TypeField and Description
private CommandlineJava
cmdl

private File
dir

private Environment
env

private File
error

private boolean
failOnError

private boolean
fork

private boolean
incompatibleWithSpawn

private File
input

private String
inputString

private boolean
newEnvironment

private File
output

private Permissions
perm

protected Redirector
redirector

protected RedirectorElement
redirectorElement

private String
resultProperty

private boolean
spawn

private Long
timeout

private static final String
TIMEOUT_MESSAGE

Inherited from org.apache.tools.ant.Task:
targettaskNametaskTypewrapper

Constructor Summary

AccessConstructor and Description
public
Java()

Normal constructor

public
Java(Task
owner
owner)

create a bound task

Method Summary

Modifier and TypeMethod and Description
public void
addAssertions(Assertions
assertion set.
asserts)

Add assertions to enable in this program (if fork=true).

public void
addConfiguredRedirector(RedirectorElement
RedirectorElement.
redirectorElement)

Add a RedirectorElement to this task.

public void
addEnv(Environment.Variable
new environment variable.
var)

Add an environment variable.

public void
addSysproperty(Environment.Variable
system property.
sysp)

Add a system property.

public void
addSyspropertyset(PropertySet
set of properties to add.
sysp)

Add a set of properties as system properties.

protected void
checkConfiguration()

Check configuration.

public void
clearArgs()

Clear out the arguments to this java task.

public Commandline.Argument

Returns:

created argument.
createArg()

Add a command-line argument.

public Path

Returns:

created bootclasspath.
createBootclasspath()

Add a path to the bootclasspath.

public Path

Returns:

created classpath.
createClasspath()

Add a path to the classpath.

public Commandline.Argument

Returns:

JVM argument created.
createJvmarg()

Adds a JVM argument.

public Path

Returns:

created modulepath.
createModulepath()

Add a path to the modulepath.

public Permissions

Returns:

Permissions.
createPermissions()

Set the permissions for the application run inside the same JVM.

public Path

Returns:

created upgrademodulepath.
createUpgrademodulepath()

Add a path to the upgrademodulepath.

protected ExecuteWatchdog

Returns:

new watchdog.
createWatchdog()

Create the Watchdog to kill a runaway process.

public void
execute()

Overrides org.apache.tools.ant.Task.execute.

Do the execution.
public int

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).
executeJava()

Do the execution and return a return code.

protected int

Returns:

the exit value of the process if forked, 0 otherwise.
executeJava(CommandlineJava
CommandLineJava instance.
commandLine)

Execute the specified CommandlineJava.

private int
fork(String[]
String[] of command-line arguments.
command)

Executes the given source-file or classname with the given arguments in a separate VM.

public CommandlineJava

Returns:

the current command line.
getCommandLine()

Accessor to the command line.

public CommandlineJava.SysProperties

Returns:

the current properties of this java invocation.
getSysProperties()

Get the system properties of the command line.

protected void
handleErrorFlush(String
string of stderr.
output)

Overrides org.apache.tools.ant.Task.handleErrorFlush.

Handle output sent to System.err and flush the stream.
protected void
handleErrorOutput(String
string of stderr.
output)

Overrides org.apache.tools.ant.Task.handleErrorOutput.

Handle output sent to System.err.
protected void
handleFlush(String
string of output on its way to its handlers.
output)

Overrides org.apache.tools.ant.Task.handleFlush.

Pass output sent to System.out to specified output file.
public int

Returns:

the number of bytes read.
handleInput(byte[]
the buffer into which data is to be read.
buffer, int
the offset into the buffer at which data is stored.
offset, int
the amount of data to read.
length)

Overrides org.apache.tools.ant.Task.handleInput.

Handle an input request by this task.
protected void
handleOutput(String
a string of output on its way to the handlers.
output)

Overrides org.apache.tools.ant.Task.handleOutput.

Pass output sent to System.out to specified output file.
private void
log(Throwable
the Throwable to log.
t)

Log the specified Throwable.

protected void
maybeSetResultPropertyValue(int
the exit code
result)

Helper method to set result property to the passed in value if appropriate.

private void
run(CommandlineJava
CommandlineJava.
command)

Executes the given classname with the given arguments as it were a command line application.

protected void
run(String
the name of the class to run.
classname, Vector<String>
arguments for the class.
args)

Executes the given classname with the given arguments as if it were a command line application.

public void
setAppend(boolean
if true, append output to existing file.
append)

If true, append output to existing file.

public void
setArgs(String
arguments.
s)

Deprecated: use nested arg instead.

public void
setClassname(String
the name of the main class.
s)

Set the Java class to execute.

public void
setClasspath(Path
an Ant Path object containing the classpath.
s)

Set the classpath to be used when running the Java class.

public void
setClasspathRef(Reference
a reference to an existing classpath.
r)

Set the classpath to use by reference.

public void
setCloneVm(boolean
if true copy system properties.
cloneVm)

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

public void
setDir(File
working directory.
d)

Set the working directory of the process.

public void
setDiscardError(final boolean
if true error streams are discarded.
discard)

Whether error output should be discarded.

public void
setDiscardOutput(final boolean
if true output streams are discarded.
discard)

Whether output should be discarded.

public void
setError(File
file getting the error stream.
error)

Set the File to which the error stream of the process is redirected.

public void
setErrorProperty(String
property name.
errorProperty)

Set the property name whose value should be set to the error of the process.

public void
setFailonerror(boolean
if true fail the build when the command exits with a nonzero returncode.
fail)

If true, then fail if the command exits with a returncode other than zero.

public void
setFork(boolean
do you want to run Java in a new VM.
s)

If true, execute in a new VM.

public void
setInput(File
name of the input file.
input)

Set the input to use for the task.

public void
setInputString(String
the string which is used as the input source.
inputString)

Set the string to use as input.

public void
setJar(File
the jarfile to execute.
jarfile)

Set the location of the JAR file to execute.

public void
setJvm(String
command to start the VM.
s)

Set the command used to start the VM (only if forking).

public void
setJvmargs(String
jvmargs.
s)

Set the command line arguments for the JVM.

public void
setJVMVersion(String
JVM version.
value)

Set the JVM version.

public void
setLogError(boolean
get in the ant log the messages coming from stderr in the case that fork = true.
logError)

Set whether error output of exec is logged.

public void
setMaxmemory(String
max memory parameter.
max)

Corresponds to -mx or -Xmx depending on VM version.

public void
setModule(String
the name of the module.
module)

Set the Java module to execute.

public void
setModulepath(Path
an Ant Path object containing the modulepath.
mp)

Set the modulepath to be used when running the Java class.

public void
setModulepathRef(Reference
a reference to an existing modulepath.
r)

Set the modulepath to use by reference.

public void
setNewenvironment(boolean
if true, use a completely new environment.
newenv)

If true, use a completely new environment.

public void
setOutput(File
the output File.
out)

Set the File to which the output of the process is redirected.

public void
setOutputproperty(String
property name.
outputProp)

Set the property name whose value should be set to the output of the process.

public void
setResultProperty(String
name of property.
resultProperty)

Set the name of the property in which the return code of the command should be stored.

public void
setSourceFile(final String
The path to the source file
sourceFile)

Set the Java source-file to execute.

public void
setSpawn(boolean
if true you do not want Ant to wait for the end of the process.
spawn)

Set whether or not you want the process to be spawned; default is not spawned.

public void
setTimeout(Long
timeout in milliseconds.
value)

Set the timeout in milliseconds after which the process will be killed.

private void
setupCommandLine(Execute
executable.
exe, String[]
command to execute.
command)

Set the command line for the exe.

private void
setupCommandLineForVMS(Execute
executable.
exe, String[]
command to execute.
command)

On VMS platform, we need to create a special java options file containing the arguments and classpath for the java command.

private void
setupEnvironment(Execute
executable.
exe)

Set up our environment variables.

private void
setupExecutable(Execute
executable.
exe, String[]
command to execute.
command)

Do all configuration for an executable that is common across the fork(String[]) and spawn(String[]) methods.

protected void
setupRedirector()

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

private void
setupWorkingDir(Execute
executable.
exe)

Set the working dir of the new process.

private void
spawn(String[]
String[] of command-line arguments.
command)

Executes the given classname with the given arguments in a separate VM.

Inherited from org.apache.tools.ant.Task:
bindToOwnergetOwningTargetgetRuntimeConfigurableWrappergetTaskNamegetTaskTypegetWrapperinitisInvalidloglogloglogmaybeConfigureperformreconfiguresetOwningTargetsetRuntimeConfigurableWrappersetTaskNamesetTaskType

Field Detail

cmdlback to summary
private CommandlineJava cmdl
dirback to summary
private File dir
envback to summary
private Environment env
errorback to summary
private File error
failOnErrorback to summary
private boolean failOnError
forkback to summary
private boolean fork
incompatibleWithSpawnback to summary
private boolean incompatibleWithSpawn
inputback to summary
private File input
inputStringback to summary
private String inputString
newEnvironmentback to summary
private boolean newEnvironment
outputback to summary
private File output
permback to summary
private Permissions perm
redirectorback to summary
protected Redirector redirector
redirectorElementback to summary
protected RedirectorElement redirectorElement
resultPropertyback to summary
private String resultProperty
spawnback to summary
private boolean spawn
timeoutback to summary
private Long timeout
TIMEOUT_MESSAGEback to summary
private static final String TIMEOUT_MESSAGE

Constructor Detail

Javaback to summary
public Java()

Normal constructor

Javaback to summary
public Java(Task owner)

create a bound task

Parameters
owner:Task

owner

Method Detail

addAssertionsback to summary
public void addAssertions(Assertions asserts)

Add assertions to enable in this program (if fork=true).

Parameters
asserts:Assertions

assertion set.

Since
Ant 1.6
addConfiguredRedirectorback to summary
public void addConfiguredRedirector(RedirectorElement redirectorElement)

Add a RedirectorElement to this task.

Parameters
redirectorElement:RedirectorElement

RedirectorElement.

addEnvback to summary
public void addEnv(Environment.Variable var)

Add an environment variable.

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

Parameters
var:Environment.Variable

new environment variable.

Since
Ant 1.5
addSyspropertyback to summary
public void addSysproperty(Environment.Variable sysp)

Add a system property.

Parameters
sysp:Environment.Variable

system property.

addSyspropertysetback to summary
public void addSyspropertyset(PropertySet sysp)

Add a set of properties as system properties.

Parameters
sysp:PropertySet

set of properties to add.

Since
Ant 1.6
checkConfigurationback to summary
protected void checkConfiguration() throws BuildException

Check configuration.

Exceptions
BuildException:
if required parameters are missing.
clearArgsback to summary
public void clearArgs()

Clear out the arguments to this java task.

createArgback to summary
public Commandline.Argument createArg()

Add a command-line argument.

Returns:Commandline.Argument

created argument.

createBootclasspathback to summary
public Path createBootclasspath()

Add a path to the bootclasspath.

Returns:Path

created bootclasspath.

Since
Ant 1.6
createClasspathback to summary
public Path createClasspath()

Add a path to the classpath.

Returns:Path

created classpath.

createJvmargback to summary
public Commandline.Argument createJvmarg()

Adds a JVM argument.

Returns:Commandline.Argument

JVM argument created.

createModulepathback to summary
public Path createModulepath()

Add a path to the modulepath.

Returns:Path

created modulepath.

Since
1.9.7
createPermissionsback to summary
public Permissions createPermissions()

Set the permissions for the application run inside the same JVM.

Returns:Permissions

Permissions.

Since
Ant 1.6
createUpgrademodulepathback to summary
public Path createUpgrademodulepath()

Add a path to the upgrademodulepath.

Returns:Path

created upgrademodulepath.

Since
1.9.7
createWatchdogback to summary
protected ExecuteWatchdog createWatchdog() throws BuildException

Create the Watchdog to kill a runaway process.

Returns:ExecuteWatchdog

new watchdog.

Exceptions
BuildException:
under unknown circumstances.
Since
Ant 1.5
executeback to summary
public void execute() throws BuildException

Overrides org.apache.tools.ant.Task.execute.

Do the execution.

Annotations
@Override
Exceptions
BuildException:
if failOnError is set to true and the application returns a nonzero result code.
executeJavaback to summary
public int executeJava() throws BuildException

Do the execution and return a return code.

Returns:int

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

Exceptions
BuildException:
if required parameters are missing.
executeJavaback to summary
protected int executeJava(CommandlineJava commandLine)

Execute the specified CommandlineJava.

Parameters
commandLine:CommandlineJava

CommandLineJava instance.

Returns:int

the exit value of the process if forked, 0 otherwise.

forkback to summary
private int fork(String[] command) throws BuildException

Executes the given source-file or classname with the given arguments in a separate VM.

Parameters
command:String[]

String[] of command-line arguments.

getCommandLineback to summary
public CommandlineJava getCommandLine()

Accessor to the command line.

Returns:CommandlineJava

the current command line.

Since
1.6.3
getSysPropertiesback to summary
public CommandlineJava.SysProperties getSysProperties()

Get the system properties of the command line.

Returns:CommandlineJava.SysProperties

the current properties of this java invocation.

Since
1.6.3
handleErrorFlushback to summary
protected void handleErrorFlush(String output)

Overrides org.apache.tools.ant.Task.handleErrorFlush.

Handle output sent to System.err and flush the stream.

Parameters
output:String

string of stderr.

Annotations
@Override
Since
Ant 1.5.2
handleErrorOutputback to summary
protected void handleErrorOutput(String output)

Overrides org.apache.tools.ant.Task.handleErrorOutput.

Handle output sent to System.err.

Parameters
output:String

string of stderr.

Annotations
@Override
Since
Ant 1.5
handleFlushback to summary
protected void handleFlush(String output)

Overrides org.apache.tools.ant.Task.handleFlush.

Pass output sent to System.out to specified output file.

Parameters
output:String

string of output on its way to its handlers.

Annotations
@Override
Since
Ant 1.5.2
handleInputback to summary
public int handleInput(byte[] buffer, int offset, int length) throws IOException

Overrides org.apache.tools.ant.Task.handleInput.

Handle an input request by this task.

Parameters
buffer:byte[]

the buffer into which data is to be read.

offset:int

the offset into the buffer at which data is stored.

length:int

the amount of data to read.

Returns:int

the number of bytes read.

Annotations
@Override
Exceptions
IOException:
if the data cannot be read.
Since
Ant 1.6
handleOutputback to summary
protected void handleOutput(String output)

Overrides org.apache.tools.ant.Task.handleOutput.

Pass output sent to System.out to specified output file.

Parameters
output:String

a string of output on its way to the handlers.

Annotations
@Override
Since
Ant 1.5
logback to summary
private void log(Throwable t)

Log the specified Throwable.

Parameters
t:Throwable

the Throwable to log.

Since
1.6.2
maybeSetResultPropertyValueback to summary
protected void maybeSetResultPropertyValue(int result)

Helper method to set result property to the passed in value if appropriate.

Parameters
result:int

the exit code

runback to summary
private void run(CommandlineJava command) throws BuildException

Executes the given classname with the given arguments as it were a command line application.

Parameters
command:CommandlineJava

CommandlineJava.

runback to summary
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:String

the name of the class to run.

args:Vector<String>

arguments for the class.

Exceptions
BuildException:
in case of IOException in the execution.
setAppendback to summary
public void setAppend(boolean append)

If true, append output to existing file.

Parameters
append:boolean

if true, append output to existing file.

Since
Ant 1.5
setArgsback to summary
public void setArgs(String s)

Deprecated: use nested arg instead. Set the command line arguments for the class.

Parameters
s:String

arguments.

setClassnameback to summary
public void setClassname(String s) throws BuildException

Set the Java class to execute.

Parameters
s:String

the name of the main class.

Exceptions
BuildException:
if there is also a jar or sourcefile attribute specified
setClasspathback to summary
public void setClasspath(Path s)

Set the classpath to be used when running the Java class.

Parameters
s:Path

an Ant Path object containing the classpath.

setClasspathRefback to summary
public void setClasspathRef(Reference r)

Set the classpath to use by reference.

Parameters
r:Reference

a reference to an existing classpath.

setCloneVmback to summary
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:boolean

if true copy system properties.

Since
Ant 1.7
setDirback to summary
public void setDir(File d)

Set the working directory of the process.

Parameters
d:File

working directory.

setDiscardErrorback to summary
public void setDiscardError(final boolean discard)

Whether error output should be discarded.

Defaults to false.

Parameters
discard:boolean

if true error streams are discarded.

Since
Ant 1.10.10
See Also
setDiscardOutput
setDiscardOutputback to summary
public void setDiscardOutput(final boolean discard)

Whether output should be discarded.

Defaults to false.

Parameters
discard:boolean

if true output streams are discarded.

Since
Ant 1.10.10
See Also
setDiscardError
setErrorback to summary
public void setError(File error)

Set the File to which the error stream of the process is redirected.

Parameters
error:File

file getting the error stream.

Since
Ant 1.6
setErrorPropertyback to summary
public void setErrorProperty(String errorProperty)

Set the property name whose value should be set to the error of the process.

Parameters
errorProperty:String

property name.

Since
Ant 1.6
setFailonerrorback to summary
public void setFailonerror(boolean fail)

If true, then fail if the command exits with a returncode other than zero.

Parameters
fail:boolean

if true fail the build when the command exits with a nonzero returncode.

setForkback to summary
public void setFork(boolean s)

If true, execute in a new VM.

Parameters
s:boolean

do you want to run Java in a new VM.

setInputback to summary
public void setInput(File input)

Set the input to use for the task.

Parameters
input:File

name of the input file.

setInputStringback to summary
public void setInputString(String inputString)

Set the string to use as input.

Parameters
inputString:String

the string which is used as the input source.

setJarback to summary
public void setJar(File jarfile) throws BuildException

Set the location of the JAR file to execute.

Parameters
jarfile:File

the jarfile to execute.

Exceptions
BuildException:
if there is also a classname, module or sourcefile attribute specified
setJvmback to summary
public void setJvm(String s)

Set the command used to start the VM (only if forking).

Parameters
s:String

command to start the VM.

setJvmargsback to summary
public void setJvmargs(String s)

Set the command line arguments for the JVM.

Parameters
s:String

jvmargs.

setJVMVersionback to summary
public void setJVMVersion(String value)

Set the JVM version.

Parameters
value:String

JVM version.

setLogErrorback to summary
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:boolean

get in the ant log the messages coming from stderr in the case that fork = true.

setMaxmemoryback to summary
public void setMaxmemory(String max)

Corresponds to -mx or -Xmx depending on VM version.

Parameters
max:String

max memory parameter.

setModuleback to summary
public void setModule(String module) throws BuildException

Set the Java module to execute.

Parameters
module:String

the name of the module.

Exceptions
BuildException:
if there is also a jar or sourcefile attribute specified
Since
1.9.7
setModulepathback to summary
public void setModulepath(Path mp)

Set the modulepath to be used when running the Java class.

Parameters
mp:Path

an Ant Path object containing the modulepath.

Since
1.9.7
setModulepathRefback to summary
public void setModulepathRef(Reference r)

Set the modulepath to use by reference.

Parameters
r:Reference

a reference to an existing modulepath.

Since
1.9.7
setNewenvironmentback to summary
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:boolean

if true, use a completely new environment.

Since
Ant 1.5
setOutputback to summary
public void setOutput(File out)

Set the File to which the output of the process is redirected.

Parameters
out:File

the output File.

setOutputpropertyback to summary
public void setOutputproperty(String outputProp)

Set the property name whose value should be set to the output of the process.

Parameters
outputProp:String

property name.

setResultPropertyback to summary
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:String

name of property.

Since
Ant 1.6
setSourceFileback to summary
public void setSourceFile(final 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:String

The path to the source file

Exceptions
BuildException:
if there is also a jar, classname or module attribute specified
Since
Ant 1.10.5
setSpawnback to summary
public void setSpawn(boolean spawn)

Set whether or not you want the process to be spawned; default is not spawned.

Parameters
spawn:boolean

if true you do not want Ant to wait for the end of the process.

Since
Ant 1.6
setTimeoutback to summary
public void setTimeout(Long value)

Set the timeout in milliseconds after which the process will be killed.

Parameters
value:Long

timeout in milliseconds.

Since
Ant 1.5
setupCommandLineback to summary
private void setupCommandLine(Execute exe, String[] command)

Set the command line for the exe. On VMS, hands off to setupCommandLineForVMS(Execute, String[]).

Parameters
exe:Execute

executable.

command:String[]

command to execute.

setupCommandLineForVMSback to summary
private void setupCommandLineForVMS(Execute exe, String[] command)

On VMS platform, we need to create a special java options file containing the arguments and classpath for the java command. The special file is supported by the "-V" switch on the VMS JVM.

Parameters
exe:Execute

executable.

command:String[]

command to execute.

setupEnvironmentback to summary
private void setupEnvironment(Execute exe)

Set up our environment variables.

Parameters
exe:Execute

executable.

setupExecutableback to summary
private void setupExecutable(Execute exe, String[] command)

Do all configuration for an executable that is common across the fork(String[]) and spawn(String[]) methods.

Parameters
exe:Execute

executable.

command:String[]

command to execute.

setupRedirectorback to summary
protected void setupRedirector()

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

setupWorkingDirback to summary
private void setupWorkingDir(Execute exe)

Set the working dir of the new process.

Parameters
exe:Execute

executable.

Exceptions
BuildException:
if the dir doesn't exist.
spawnback to summary
private void spawn(String[] command) throws BuildException

Executes the given classname with the given arguments in a separate VM.

Parameters
command:String[]

String[] of command-line arguments.