Gradle - Run Java with JVM Arguments

This tutorial shows you how to add JVM arguments when running a Java application using Gradle.

Gradle is one of the build tools supporting Java. Java itself allows a program to be launched with JVM arguments. JVM arguments are usually used to set the run configurations for the application. For example, it can be used to set the initial and maximum memory allocation pools. It can also be used to set additional properties. If the Java application is run using Gradle, it's also possible to add JVM arguments. In this tutorial, I'm going to show you how to do it.

Using Application Plugin

Gradle has a plugin called 'application' which enables you to set the JVM arguments. First, you have to add the plugin in the build.gradle file.

  plugins {
    id 'application'
    // other plugins
  }

After adding the plugin, you can add an applicationDefaultJvmArgs property. The value is an array. For example, if you want to write a JVM argument -Dmyprop=woolha.com, you can write the following.

  applicationDefaultJvmArgs = ["-Dmyprop=woolha.com"]

If there are more than one argument, the values can be separated by a comma. Below is another example with where multiple arguments are passed

  applicationDefaultJvmArgs = [
      "-Dmyprop=woolha.com",
      "-Dversion=1.0.0",
      "-Xms2048m"
  ]

By using the application plugin, there will be a Gradle task named run which can be used to run the application. The main class to be executed has to be defined by adding a mainClass property in an application block. The value is the fully qualified name of the main class

  application {
      mainClass = 'com.woolha.example.Main'
  }

The JVM arguments defined using applicationDefaultJvmArgs are applied to the run task. In addition, they are also considered in the generated start scripts.

To check whether a property passed as a JVM argument is successfully set, you can use the System.getProperty method.

  String myprop = System.getProperty("myprop");

Using Command Line

Another alternative to add the JVM arguments is by using a command line argument. Gradle command line has -D option which can be used for it.

For example, if there is a task called execute which runs a Java main class, you can add the option like in the following example.

  ./gradlew :woolha-demo-gradle-2:execute -Dmyprop=woolha.com3 -Dversion=1.0.0 -Dorg.gradle.jvmargs="-Xms1024m -Xmx2048m"

However, after adding that option, you may find out that the property is not set when you check it in your Java code. That's because when Gradle forks a new Java process, it doesn't pass the arguments to the forked process. The solution is to set the system properties explicitly in the task which can be seen in the examples below.

Using JavaExec task

In the example below, we create a task called execute whose type is JavaExec to run a Java main class. To pass all properties to the Java program, add systemProperties System.getProperties() statement inside the task block. Another alternative is to set an individual property one-by-one using systemProperty "propname", System.getProperty("propname") statement.

  task execute (type:JavaExec) {
      mainClass = 'com.woolha.example.Main'
      classpath = sourceSets.main.runtimeClasspath
  
      // Pass all properties
      systemProperties System.getProperties()
  
      // Pass property by name
      systemProperty "myprop", System.getProperty("myprop")
  }

Using Application Plugin

If you use the Application plugin, it's also possible to add JVM arguments in the command line. You have to modify the run task to make it does the similar thing in order to make the arguments passed to the Java program.

  run {
      // Pass all properties
      systemProperties System.getProperties()
  
      // Pass property by name
      systemProperty "myprop", System.getProperty("myprop")
  }

You need to know that if the same argument is also set in applicationDefaultJvmArgs, the one set from the command line will not be used.

Using gradlew

If your project has a gradlew (Gradle wrapper) file, it's also possible to define the default JVM arguments there. You need to add or modify DEFAULT_JVM_OPTS property to define the arguments that you want to set as the default. It's allowed to pass multiple arguments like in the example below.

DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m" "-Dmyprop=woolha.com"'

The argument set using this method will be replaced by the same argument defined using command line or Application plugin's applicationDefaultJvmArgs.

Summary

There are several ways to set JVM arguments using Gradle. If you use the Application plugin, it can be done by setting the value of applicationDefaultJvmArgs property. The arguments can be added using the command line as well. Another alternative is by setting DEFAULT_JVM_OPTS in the gradlew file.