Package org.gradle.api.tasks

# Class JavaExec

java.lang.Object
org.gradle.api.internal.AbstractTask
org.gradle.api.DefaultTask
org.gradle.api.internal.ConventionTask
org.gradle.api.tasks.JavaExec

All Implemented Interfaces:
  `Comparable<Task>`, `org.gradle.api.internal.DynamicObjectAware`, `org.gradle.api.internal.IConventionAware`, `org.gradle.api.internal.TaskInternal`, `Named`, `ExtensionAware`, `Task`, `BaseExecSpec`, `JavaExecSpec`, `JavaForkOptions`, `ProcessForkOptions`, `Configurable<Task>`

@DisableCachingByDefault(because="Gradle would require more information to cache this task") public abstract class JavaExec extends org.gradle.api.internal.ConventionTask implements JavaExecSpec
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 `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 `debugOptions(Action)`:

     task runApp(type: JavaExec) {
        ...

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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `(package private) static class`
  `JavaExec.ArgsAdapter`
  Upgrade for `getArgs()`
  `(package private) static class`
  `JavaExec.ClasspathAdapter`
  Upgrade for `getClasspath()`
  `(package private) static class`
  `JavaExec.ErrorOutputAdapter`
  Upgrade for `getErrorOutput()`
  `(package private) static class`
  `JavaExec.IgnoreExitValueAdapter`
  Upgrade for `getIgnoreExitValue()`
  `(package private) static class`
  `JavaExec.StandardInputAdapter`
  Upgrade for `getStandardInput()`
  `(package private) static class`
  `JavaExec.StandardOutputAdapter`
  Upgrade for `getStandardOutput()`

  ## Nested classes/interfaces inherited from interface org.gradle.api.Named

  `Named.Namer`

- ## Field Summary

  ### Fields inherited from interface org.gradle.api.Task

  `TASK_ACTION, TASK_CONSTRUCTOR_ARGS, TASK_DEPENDS_ON, TASK_DESCRIPTION, TASK_GROUP, TASK_NAME, TASK_OVERWRITE, TASK_TYPE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JavaExec()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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(@Nullable Object... classpath)`
  Adds the given values to the end of the bootstrap classpath for the process.
  `JavaExec`
  `classpath(@Nullable 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.
  `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.
  `void`
  `exec()`
  `JavaExec`
  `executable(Object executable)`
  Sets the name of the executable to use.
  `Provider<List<String>>`
  `getAllJvmArgs()`
  Returns the full set of arguments to use to launch the JVM for the process.
  `ListProperty<String>`
  `getArgs()`
  Returns the arguments passed to the main class to be executed.
  `ListProperty<CommandLineArgumentProvider>`
  `getArgumentProviders()`
  Argument providers for the application.
  `ConfigurableFileCollection`
  `getBootstrapClasspath()`
  Returns the bootstrap classpath to use for the process.
  `ConfigurableFileCollection`
  `getClasspath()`
  Returns the classpath for executing the main class.
  `Provider<List<String>>`
  `getCommandLine()`
  Returns the full command line, including the executable plus its arguments.
  `Property<Boolean>`
  `getDebug()`
  Determines whether debugging is enabled for the test process.
  `JavaDebugOptions`
  `getDebugOptions()`
  Returns the Java Debug Wire Protocol properties for the process.
  `Property<String>`
  `getDefaultCharacterEncoding()`
  Returns the default character encoding to use.
  `Property<Boolean>`
  `getEnableAssertions()`
  A flag that marks if assertions are enabled for the process.
  `MapProperty<String,Object>`
  `getEnvironment()`
  The environment variables to use for the process.
  `Property<OutputStream>`
  `getErrorOutput()`
  Returns the output stream to consume standard error from the process executing the command.
  `protected abstract org.gradle.process.internal.ExecActionFactory`
  `getExecActionFactory()`
  `Property<String>`
  `getExecutable()`
  Returns the name of the executable to use.
  `Provider<ExecResult>`
  `getExecutionResult()`
  Returns the result for the command run by this task.
  `Property<Boolean>`
  `getIgnoreExitValue()`
  Tells whether a non-zero exit value is ignored, or an exception thrown.
  `Property<Boolean>`
  `getIsIgnoreExitValue()`
  Added for Kotlin DSL source compatibility.
  `abstract Property<JavaLauncher>`
  `getJavaLauncher()`
  Configures the java executable to be used to run the tests.
  `protected abstract JavaToolchainService`
  `getJavaToolchainService()`
  `Provider<JavaVersion>`
  `getJavaVersion()`
  Returns the version of the Java executable specified by `getJavaLauncher()`.
  `ListProperty<String>`
  `getJvmArgs()`
  The extra arguments to use to launch the JVM for the process.
  `ListProperty<CommandLineArgumentProvider>`
  `getJvmArgumentProviders()`
  Command line argument providers for the java process to fork.
  `ListProperty<String>`
  `getJvmArguments()`
  Extra JVM arguments to be to use to launch the JVM for the process.
  `abstract Property<String>`
  `getMainClass()`
  The fully qualified name of the Main class to be executed.
  `abstract Property<String>`
  `getMainModule()`
  The name of the main module to be executed if the application should run as a Java module.
  `Property<String>`
  `getMaxHeapSize()`
  Returns the maximum heap size for the process, if any.
  `Property<String>`
  `getMinHeapSize()`
  Returns the minimum heap size for the process, if any.
  `ModularitySpec`
  `getModularity()`
  Returns the module path handling for executing the main class.
  `protected abstract ObjectFactory`
  `getObjectFactory()`
  `protected abstract org.gradle.api.internal.provider.PropertyFactory`
  `getPropertyFactory()`
  `protected abstract ProviderFactory`
  `getProviderFactory()`
  `Property<InputStream>`
  `getStandardInput()`
  Returns the standard input stream for the process executing the command.
  `Property<OutputStream>`
  `getStandardOutput()`
  Returns the output stream to consume standard output from the process executing the command.
  `MapProperty<String,Object>`
  `getSystemProperties()`
  System properties which will be used for the process.
  `DirectoryProperty`
  `getWorkingDir()`
  Returns the working directory for the process.
  `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`
  `setArgsString(String args)`
  Parses an argument list from `args` and passes it to `getArgs()`.
  `JavaExec`
  `systemProperties(Map<String,? extends @Nullable Object> properties)`
  Adds some system properties to use for the process.
  `JavaExec`
  `systemProperty(String name, @Nullable Object value)`
  Adds a system property to use for the process.
  `JavaExec`
  `workingDir(Object dir)`
  Sets the working directory for the process.

  ### Methods inherited from class org.gradle.api.internal.ConventionTask

  `conventionMapping, conventionMapping, getConventionMapping`

  ### Methods inherited from class org.gradle.api.DefaultTask

  `compareTo, configure, dependsOn, doFirst, doFirst, doFirst, doLast, doLast, doLast, finalizedBy, getActions, getAnt, getDependsOn, getDescription, getDestroyables, getDidWork, getEnabled, getExtensions, getFinalizedBy, getGroup, getInputs, getLocalState, getLogger, getLogging, getMustRunAfter, getName, getOutputs, getPath, getProject, getShouldRunAfter, getState, getTaskDependencies, getTemporaryDir, getTimeout, hasProperty, mustRunAfter, onlyIf, onlyIf, onlyIf, property, setActions, setDependsOn, setDescription, setDidWork, setEnabled, setFinalizedBy, setGroup, setMustRunAfter, setOnlyIf, setOnlyIf, setOnlyIf, setProperty, setShouldRunAfter, shouldRunAfter, usesService`

  ### Methods inherited from class org.gradle.api.internal.AbstractTask

  `acceptServiceReferences, appendParallelSafeAction, doNotTrackState, doNotTrackStateIf, getAsDynamicObject, getIdentityPath, getImpliesSubProjects, getLifecycleDependencies, getOnlyIf, getReasonNotToTrackState, getReasonsNotToTrackState, getReasonTaskIsIncompatibleWithConfigurationCache, getRequiredServices, getServices, getSharedResources, getStandardOutputCapture, getTaskActions, getTaskIdentity, getTemporaryDirFactory, hasTaskActions, injectIntoNewInstance, isCompatibleWithConfigurationCache, isEnabled, isHasCustomActions, notCompatibleWithConfigurationCache, prependParallelSafeAction, restoreOnlyIf, restoreTaskActions, setImpliesSubProjects`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface org.gradle.api.Task

  `doNotTrackState, notCompatibleWithConfigurationCache`

- ## Constructor Details

  - ### JavaExec

    public JavaExec()

- ## Method Details

  - ### exec

    public void exec()

  - ### getAllJvmArgs

    public Provider<List<String>> getAllJvmArgs()
    Returns 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.
    Specified by:
      `getAllJvmArgs` in interface `JavaForkOptions`
    Returns:
      The immutable list of arguments. Returns an empty list if there are no arguments.

  - ### getJvmArgs

    public ListProperty<String> getJvmArgs()
    The extra arguments to use to launch the JVM for the process.
    Specified by:
      `getJvmArgs` in interface `JavaForkOptions`
    Returns:
      The list of arguments. Returns an empty list if there are no arguments.

  - ### jvmArgs

    public JavaExec jvmArgs(Iterable<?> arguments)
    Adds some arguments to use to launch the JVM for the process.
    Specified by:
      `jvmArgs` in interface `JavaForkOptions`
    Parameters:
      `arguments` - The arguments. Must not be null.
    Returns:
      this

  - ### jvmArgs

    public JavaExec jvmArgs(Object... arguments)
    Adds some arguments to use to launch the JVM for the process.
    Specified by:
      `jvmArgs` in interface `JavaForkOptions`
    Parameters:
      `arguments` - The arguments.
    Returns:
      this

  - ### getSystemProperties

    public MapProperty<String,Object> getSystemProperties()
    System properties which will be used for the process.
    Specified by:
      `getSystemProperties` in interface `JavaForkOptions`
    Returns:
      The system properties. Returns an empty map when there are no system properties.

  - ### systemProperties

    public JavaExec systemProperties(Map<String,? extends @Nullable Object> properties)
    Adds some system properties to use for the process.
    Specified by:
      `systemProperties` in interface `JavaForkOptions`
    Parameters:
      `properties` - The system properties. Must not be null.
    Returns:
      this

  - ### systemProperty

    public JavaExec systemProperty(String name, @Nullable Object value)
    Adds a system property to use for the process.
    Specified by:
      `systemProperty` in interface `JavaForkOptions`
    Parameters:
      `name` - The name of the property
      `value` - The value for the property. May be null.
    Returns:
      this

  - ### getBootstrapClasspath

    public ConfigurableFileCollection getBootstrapClasspath()
    Returns the bootstrap classpath to use for the process. The default bootstrap classpath for the JVM is used when this classpath is empty.
    Specified by:
      `getBootstrapClasspath` in interface `JavaForkOptions`
    Returns:
      The bootstrap classpath. Never returns null.

  - ### bootstrapClasspath

    public JavaExec bootstrapClasspath(@Nullable Object... classpath)
    Adds the given values to the end of the bootstrap classpath for the process.
    Specified by:
      `bootstrapClasspath` in interface `JavaForkOptions`
    Parameters:
      `classpath` - The classpath.
    Returns:
      this

  - ### getMinHeapSize

    public Property<String> getMinHeapSize()
    Returns the minimum heap size for the process, if any. Supports the units megabytes (e.g. "512m") and gigabytes (e.g. "1g").
    Specified by:
      `getMinHeapSize` in interface `JavaForkOptions`
    Returns:
      The minimum heap size. Returns null if the default minimum heap size should be used.

  - ### getDefaultCharacterEncoding

    public Property<String> getDefaultCharacterEncoding()
    Returns the default character encoding to use.
    Specified by:
      `getDefaultCharacterEncoding` in interface `JavaForkOptions`
    Returns:
      The default character encoding. Returns null if the `default character encoding of this JVM` should be used.

  - ### getMaxHeapSize

    public Property<String> getMaxHeapSize()
    Returns the maximum heap size for the process, if any. Supports the units megabytes (e.g. "512m") and gigabytes (e.g. "1g").
    Specified by:
      `getMaxHeapSize` in interface `JavaForkOptions`
    Returns:
      The maximum heap size. Returns null if the default maximum heap size should be used.

  - ### getEnableAssertions

    public Property<Boolean> getEnableAssertions()
    A flag that marks if assertions are enabled for the process.
    Specified by:
      `getEnableAssertions` in interface `JavaForkOptions`

  - ### getDebug

    public Property<Boolean> getDebug()
    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(Action)`.

    Specified by:
      `getDebug` in interface `JavaForkOptions`

  - ### getDebugOptions

    public JavaDebugOptions getDebugOptions()
    Returns 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.
    Specified by:
      `getDebugOptions` in interface `JavaForkOptions`

  - ### debugOptions

    public void debugOptions(Action<JavaDebugOptions> action)
    Configures Java Debug Wire Protocol properties for the process. If `JavaForkOptions.getDebug()` (boolean)} is enabled then the `-agentlib:jdwp=...` will be appended to the JVM arguments with the configuration from the parameter.
    Specified by:
      `debugOptions` in interface `JavaForkOptions`
    Parameters:
      `action` - the Java debug configuration

  - ### getMainModule

    public abstract Property<String> getMainModule()
    The name of the main module to be executed if the application should run as a Java module.
    Specified by:
      `getMainModule` in interface `JavaExecSpec`

  - ### getMainClass

    public abstract Property<String> getMainClass()
    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.

    Specified by:
      `getMainClass` in interface `JavaExecSpec`

  - ### getArgs

    public ListProperty<String> getArgs()
    Returns the arguments passed to the main class to be executed.
    Specified by:
      `getArgs` in interface `JavaExecSpec`

  - ### setArgsString

    public JavaExec setArgsString(String args)
    Parses an argument list from `args` and passes it to `getArgs()`.

    The parser supports both single quote (`'`) and double quote (`"`) as quote delimiters. For example, to pass the argument `foo bar`, use `"foo bar"`.

    Note: the parser does not support using backslash to escape quotes. If this is needed, use the other quote delimiter around it. For example, to pass the argument `'singly quoted'`, use `"'singly quoted'"`.

    Parameters:
      `args` - Args for the main class. Will be parsed into an argument list.
    Returns:
      this
    Since:
      4.9

  - ### args

    public JavaExec args(Object... args)
    Adds args for the main class to be executed.
    Specified by:
      `args` in interface `JavaExecSpec`
    Parameters:
      `args` - Args for the main class.
    Returns:
      this

  - ### args

    public JavaExecSpec args(Iterable<?> args)
    Adds args for the main class to be executed.
    Specified by:
      `args` in interface `JavaExecSpec`
    Parameters:
      `args` - Args for the main class.
    Returns:
      this

  - ### getArgumentProviders

    public ListProperty<CommandLineArgumentProvider> getArgumentProviders()
    Argument providers for the application.
    Specified by:
      `getArgumentProviders` in interface `JavaExecSpec`

  - ### classpath

    public JavaExec classpath(@Nullable Object... paths)
    Adds elements to the classpath for executing the main class.
    Specified by:
      `classpath` in interface `JavaExecSpec`
    Parameters:
      `paths` - classpath elements
    Returns:
      this

  - ### getClasspath

    public ConfigurableFileCollection getClasspath()
    Returns the classpath for executing the main class.
    Specified by:
      `getClasspath` in interface `JavaExecSpec`

  - ### getModularity

    public ModularitySpec getModularity()
    Returns the module path handling for executing the main class.
    Specified by:
      `getModularity` in interface `JavaExecSpec`

  - ### copyTo

    public JavaExec copyTo(JavaForkOptions options)
    Copies these options to the given options.
    Specified by:
      `copyTo` in interface `JavaForkOptions`
    Parameters:
      `options` - The target options.
    Returns:
      this

  - ### getJavaVersion

    @Internal("covered by getJavaLauncher().getMetadata().getLanguageVersion()") public Provider<JavaVersion> getJavaVersion()
    Returns the version of the Java executable specified by `getJavaLauncher()`.
    Since:
      5.2

  - ### getExecutable

    @Internal("covered by getJavaVersion") public Property<String> getExecutable()
    Returns the name of the executable to use.
    Specified by:
      `getExecutable` in interface `ProcessForkOptions`
    Returns:
      The executable.

  - ### executable

    public JavaExec executable(Object executable)
    Sets the name of the executable to use.
    Specified by:
      `executable` in interface `ProcessForkOptions`
    Parameters:
      `executable` - The executable. Must not be null.
    Returns:
      this

  - ### getWorkingDir

    @Internal public DirectoryProperty getWorkingDir()
    Returns the working directory for the process. Defaults to the project directory.
    Specified by:
      `getWorkingDir` in interface `ProcessForkOptions`
    Returns:
      The working directory. Never returns null.

  - ### workingDir

    public JavaExec workingDir(Object dir)
    Sets the working directory for the process. The supplied argument is evaluated as per `Project.file(Object)`.
    Specified by:
      `workingDir` in interface `ProcessForkOptions`
    Parameters:
      `dir` - The working directory. Must not be null.
    Returns:
      this

  - ### getEnvironment

    @Internal public MapProperty<String,Object> getEnvironment()
    The environment variables to use for the process. Defaults to the environment of this process.
    Specified by:
      `getEnvironment` in interface `ProcessForkOptions`
    Returns:
      The environment. Returns an empty map when there are no environment variables.

  - ### environment

    public JavaExec environment(String name, Object value)
    Adds an environment variable to the environment for this process.
    Specified by:
      `environment` in interface `ProcessForkOptions`
    Parameters:
      `name` - The name of the variable.
      `value` - The value for the variable. Must not be null.
    Returns:
      this

  - ### environment

    public JavaExec environment(Map<String,?> environmentVariables)
    Adds some environment variables to the environment for this process.
    Specified by:
      `environment` in interface `ProcessForkOptions`
    Parameters:
      `environmentVariables` - The environment variables. Must not be null.
    Returns:
      this

  - ### copyTo

    public JavaExec copyTo(ProcessForkOptions target)
    Copies these options to the given target options.
    Specified by:
      `copyTo` in interface `ProcessForkOptions`
    Parameters:
      `target` - The target options
    Returns:
      this

  - ### getStandardInput

    @Internal public Property<InputStream> getStandardInput()
    Returns the standard input stream for the process executing the command. The stream is closed after the process completes. Defaults to an empty stream.
    Specified by:
      `getStandardInput` in interface `BaseExecSpec`
    Returns:
      The standard input stream.

  - ### getStandardOutput

    @Internal public Property<OutputStream> getStandardOutput()
    Returns the output stream to consume standard output from the process executing the command. Defaults to `System.out`.
    Specified by:
      `getStandardOutput` in interface `BaseExecSpec`
    Returns:
      The output stream

  - ### getErrorOutput

    @Internal public Property<OutputStream> getErrorOutput()
    Returns the output stream to consume standard error from the process executing the command. Default to `System.err`.
    Specified by:
      `getErrorOutput` in interface `BaseExecSpec`
    Returns:
      The error output stream.

  - ### getIgnoreExitValue

    @Input public Property<Boolean> getIgnoreExitValue()
    Tells whether a non-zero exit value is ignored, or an exception thrown. Defaults to `false`.
    Specified by:
      `getIgnoreExitValue` in interface `BaseExecSpec`
    Returns:
      whether a non-zero exit value is ignored, or an exception thrown

  - ### getIsIgnoreExitValue

    @Internal public Property<Boolean> getIsIgnoreExitValue()
    Added for Kotlin DSL source compatibility.
    Specified by:
      `getIsIgnoreExitValue` in interface `BaseExecSpec`

  - ### getCommandLine

    @Internal public Provider<List<String>> getCommandLine()
    Returns the full command line, including the executable plus its arguments.
    Specified by:
      `getCommandLine` in interface `BaseExecSpec`
    Returns:
      The full command line, including the executable plus its arguments

  - ### getJvmArgumentProviders

    public ListProperty<CommandLineArgumentProvider> getJvmArgumentProviders()
    Command line argument providers for the java process to fork.
    Specified by:
      `getJvmArgumentProviders` in interface `JavaForkOptions`

  - ### getJvmArguments

    public ListProperty<String> getJvmArguments()
    Extra JVM arguments to be to use to launch the JVM for the process. Must be used to set a convention for JVM arguments.
    Specified by:
      `getJvmArguments` in interface `JavaExecSpec`

  - ### getExecutionResult

    @Internal public Provider<ExecResult> getExecutionResult()
    Returns the result for the command run by this task. The provider has no value if this task has not been executed yet.
    Returns:
      A provider of the result.
    Since:
      6.1

  - ### getJavaLauncher

    public abstract Property<JavaLauncher> getJavaLauncher()
    Configures the java executable to be used to run the tests.
    Since:
      6.7

  - ### getObjectFactory

    @Inject protected abstract ObjectFactory getObjectFactory()

  - ### getPropertyFactory

    @Inject protected abstract org.gradle.api.internal.provider.PropertyFactory getPropertyFactory()

  - ### getExecActionFactory

    @Inject protected abstract org.gradle.process.internal.ExecActionFactory getExecActionFactory()

  - ### getJavaToolchainService

    @Inject protected abstract JavaToolchainService getJavaToolchainService()

  - ### getProviderFactory

    @Inject protected abstract ProviderFactory getProviderFactory()