JavaExec

Table of Contents

Properties
Methods
Script blocks
Property details
Method details

API Documentation:	`JavaExec`

Executes a Java application in a child process.

Similar to Exec, but starts a JVM with the given classpath and application class.

plugins {
    id 'java'
}

task runApp(type: JavaExec) {
  classpath = sourceSets.main.runtimeClasspath

  mainClass = 'package.Main'

  // arguments to pass to the application
  args 'appArg1'
}

// Using and creating an Executable Jar
jar {
  manifest {
    attributes('Main-Class': 'package.Main')
  }
}

task runExecutableJar(type: JavaExec) {
  // Executable jars can have only _one_ jar on the classpath.
  classpath = files(tasks.jar)

  // 'main' does not need to be specified

  // arguments to pass to the application
  args 'appArg1'
}

The process can be started in debug mode (see JavaExec.getDebug()) in an ad-hoc manner by supplying the `--debug-jvm` switch when invoking the build.

gradle someJavaExecTask --debug-jvm

Also, debug configuration can be explicitly set in JavaExec.debugOptions(org.gradle.api.Action):

task runApp(type: JavaExec) {
   ...

   debugOptions {
       enabled = true
       port = 5566
       server = true
       suspend = false
   }
}

Properties

Property	Description
`allJvmArgs`	The full set of arguments to use to launch the JVM for the process. This includes arguments to define system properties, the minimum/maximum heap size, and the bootstrap classpath.
`args`	The arguments passed to the main class to be executed.
`argumentProviders`	Argument providers for the application.
`bootstrapClasspath`	The bootstrap classpath to use for the process. The default bootstrap classpath for the JVM is used when this classpath is empty.
`classpath`	The classpath for executing the main class.
`commandLine`	The full command line, including the executable plus its arguments.
`debug`	Determines whether debugging is enabled for the test process. When enabled — `debug = true` — the process is started in a suspended state, listening on port 5005. You should disable parallel test execution when debugging and you will need to reattach the debugger occasionally if you use a non-zero value for `Test.getForkEvery()`.
`debugOptions`	The Java Debug Wire Protocol properties for the process. If enabled then the `-agentlib:jdwp=...` will be appended to the JVM arguments with the configuration from the parameter.
`enableAssertions`	Returns true if assertions are enabled for the process.
`environment`	The environment variables to use for the process. Defaults to the environment of this process.
`errorOutput`	The output stream to consume standard error from the process executing the command. Default to `System.err`.
`executable`	The name of the executable to use.
`executionResult`	The result for the command run by this task. The provider has no value if this task has not been executed yet.
`ignoreExitValue`	Tells whether a non-zero exit value is ignored, or an exception thrown. Defaults to `false`.
`javaLauncher`	Configures the java executable to be used to run the tests.
`jvmArgs`	The extra arguments to use to launch the JVM for the process. Does not include system properties and the minimum/maximum heap size.
`jvmArgumentProviders`	Command line argument providers for the java process to fork.
`jvmArguments`	Extra JVM arguments to be to use to launch the JVM for the process. Must be used to set a convention for JVM arguments.
`mainClass`	The fully qualified name of the Main class to be executed.
`mainModule`	The name of the main module to be executed if the application should run as a Java module.
`maxHeapSize`	The maximum heap size for the process, if any.
`modularity`	The module path handling for executing the main class.
`standardInput`	The standard input stream for the process executing the command. The stream is closed after the process completes. Defaults to an empty stream.
`standardOutput`	The output stream to consume standard output from the process executing the command. Defaults to `System.out`.
`systemProperties`	The system properties which will be used for the process.
`workingDir`	The working directory for the process. Defaults to the project directory.

Methods

Method	Description
`args(args)`	Adds args for the main class to be executed.
`args(args)`	Adds args for the main class to be executed.
`bootstrapClasspath(classpath)`	Adds the given values to the end of the bootstrap classpath for the process.
`classpath(paths)`	Adds elements to the classpath for executing the main class.
`copyTo(options)`	Copies these options to the given options.
`copyTo(target)`	Copies these options to the given target options.
`debugOptions(action)`	Configures Java Debug Wire Protocol properties for the process. If `JavaForkOptions.setDebug(boolean)` is enabled then the `-agentlib:jdwp=...` will be appended to the JVM arguments with the configuration from the parameter.
`environment(name, value)`	Adds an environment variable to the environment for this process.
`environment(environmentVariables)`	Adds some environment variables to the environment for this process.
`executable(executable)`	Sets the name of the executable to use.
`jvmArgs(arguments)`	Adds some arguments to use to launch the JVM for the process.
`jvmArgs(arguments)`	Adds some arguments to use to launch the JVM for the process.
`systemProperties(properties)`	Adds some system properties to use for the process.
`workingDir(dir)`	Sets the working directory for the process. The supplied argument is evaluated as per `Project.file(java.lang.Object)`.

Script blocks

No script blocks

Property details

`List<String>` `allJvmArgs`

The full set of arguments to use to launch the JVM for the process. This includes arguments to define system properties, the minimum/maximum heap size, and the bootstrap classpath.

`List<String>` `args`

The arguments passed to the main class to be executed.

Default:: []

`List<CommandLineArgumentProvider>` `argumentProviders` (read-only)

Argument providers for the application.

Default:: []

`FileCollection` `bootstrapClasspath`

The bootstrap classpath to use for the process. The default bootstrap classpath for the JVM is used when this classpath is empty.

Default:: []

`FileCollection` `classpath`

The classpath for executing the main class.

Default:: null

`List<String>` `commandLine` (read-only)

The full command line, including the executable plus its arguments.

`boolean` `debug`

Determines whether debugging is enabled for the test process. When enabled — debug = true — the process is started in a suspended state, listening on port 5005. You should disable parallel test execution when debugging and you will need to reattach the debugger occasionally if you use a non-zero value for Test.getForkEvery().

Since Gradle 5.6, you can configure the port and other Java debug properties via JavaForkOptions.debugOptions(org.gradle.api.Action).

Default:: false

`JavaDebugOptions` `debugOptions` (read-only)

The Java Debug Wire Protocol properties for the process. If enabled then the -agentlib:jdwp=... will be appended to the JVM arguments with the configuration from the parameter.

`boolean` `enableAssertions`

Returns true if assertions are enabled for the process.

Default:: false

`Map<String, Object>` `environment`

The environment variables to use for the process. Defaults to the environment of this process.

Default:: Current process' environment

`OutputStream` `errorOutput`

The output stream to consume standard error from the process executing the command. Default to System.err.

Default:: System.err

`String` `executable`

The name of the executable to use.

Default:: java executable for current JVM

`Provider<ExecResult>` `executionResult`

The result for the command run by this task. The provider has no value if this task has not been executed yet.

`boolean` `ignoreExitValue`

Tells whether a non-zero exit value is ignored, or an exception thrown. Defaults to false.

Default:: false

`Property<JavaLauncher>` `javaLauncher`

Configures the java executable to be used to run the tests.

Default:: java.toolchain

`List<String>` `jvmArgs`

The extra arguments to use to launch the JVM for the process. Does not include system properties and the minimum/maximum heap size.

Default:: []

`List<CommandLineArgumentProvider>` `jvmArgumentProviders` (read-only)

Command line argument providers for the java process to fork.

Default:: []

`ListProperty<String>` `jvmArguments`

Extra JVM arguments to be to use to launch the JVM for the process. Must be used to set a convention for JVM arguments.

Default:: null

`Property<String>` `mainClass`

The fully qualified name of the Main class to be executed.

This does not need to be set if using an Executable Jar with a Main-Class attribute.

Default:: null

`Property<String>` `mainModule`

The name of the main module to be executed if the application should run as a Java module.

Default:: null

`String` `maxHeapSize`

The maximum heap size for the process, if any.

Default:: null

`ModularitySpec` `modularity` (read-only)

The module path handling for executing the main class.

`InputStream` `standardInput`

The standard input stream for the process executing the command. The stream is closed after the process completes. Defaults to an empty stream.

Default:: An empty InputStream

`OutputStream` `standardOutput`

The output stream to consume standard output from the process executing the command. Defaults to System.out.

Default:: System.out

`Map<String, Object>` `systemProperties`

The system properties which will be used for the process.

Default:: [:]

`File` `workingDir`

The working directory for the process. Defaults to the project directory.

Default:: project.projectDir

Method details

`JavaExecSpec` `args`(`Iterable<?>` args)

Adds args for the main class to be executed.

`JavaExec` `args`(`Object...` args)

Adds args for the main class to be executed.

`JavaExec` `bootstrapClasspath`(`Object...` classpath)

Adds the given values to the end of the bootstrap classpath for the process.

`JavaExec` `classpath`(`Object...` paths)

Adds elements to the classpath for executing the main class.

`JavaExec` `copyTo`(`JavaForkOptions` options)

Copies these options to the given options.

`JavaExec` `copyTo`(`ProcessForkOptions` target)

Copies these options to the given target options.

`void` `debugOptions`(`Action<JavaDebugOptions>` action)

Configures Java Debug Wire Protocol properties for the process. If JavaForkOptions.setDebug(boolean) is enabled then the -agentlib:jdwp=... will be appended to the JVM arguments with the configuration from the parameter.

`JavaExec` `environment`(`String` name, `Object` value)

Adds an environment variable to the environment for this process.

`JavaExec` `environment`(`Map<String, ?>` environmentVariables)

Adds some environment variables to the environment for this process.

`JavaExec` `executable`(`Object` executable)

Sets the name of the executable to use.

`JavaExec` `jvmArgs`(`Iterable<?>` arguments)

Adds some arguments to use to launch the JVM for the process.

`JavaExec` `jvmArgs`(`Object...` arguments)

Adds some arguments to use to launch the JVM for the process.

`JavaExec` `systemProperties`(`Map<String, ?>` properties)

Adds some system properties to use for the process.

`JavaExec` `workingDir`(`Object` dir)

Sets the working directory for the process. The supplied argument is evaluated as per Project.file(java.lang.Object).

JavaExec

Properties

Methods

Script blocks

Property details

List<String> allJvmArgs

List<String> args

List<CommandLineArgumentProvider> argumentProviders (read-only)

FileCollection bootstrapClasspath

FileCollection classpath

List<String> commandLine (read-only)

boolean debug

JavaDebugOptions debugOptions (read-only)

boolean enableAssertions

Map<String, Object> environment

OutputStream errorOutput

String executable

Provider<ExecResult> executionResult

boolean ignoreExitValue

Property<JavaLauncher> javaLauncher

List<String> jvmArgs

List<CommandLineArgumentProvider> jvmArgumentProviders (read-only)

ListProperty<String> jvmArguments

Property<String> mainClass

Property<String> mainModule

String maxHeapSize

ModularitySpec modularity (read-only)

InputStream standardInput

OutputStream standardOutput

Map<String, Object> systemProperties

File workingDir