# 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()`.
`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.
`main` | Deprecated Replaced The fully qualified name of the Main class to be executed.
`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.
`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`

#### `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:
  `[]`

#### `String` `main`

Note: This property is deprecated and will be removed in the next major version of Gradle.

Note: This property has been replaced by 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`>` `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.

Use this property instead of `JavaExecSpec.getMain()` and `JavaExecSpec.setMain(java.lang.String)`.

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.

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