# JavaExec

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 settings, which are managed separately and included in `JavaForkOptions.getAllJvmArgs()`.
`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 settings, which are managed separately and included in `JavaForkOptions.getAllJvmArgs()`.

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`, ? extends `Object`>` 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)`.