• wrapper.java.additional.<n> properties
• wrapper.java.additional.<n>.quotable Properties
• wrapper.java.additional.<n>.stripquotes Properties (No longer used as of 3.6.0)
• wrapper.java.additional.default.stripquotes Properties (No longer used as of 3.6.0)
• wrapper.java.additional.<n>.java_version.min Properties
• wrapper.java.additional.<n>.java_version.max properties
• wrapper.java.additional.<n>.app_only Properties (Deprecated as of 3.5.60)
• wrapper.java.additional.<n>.scope properties
• wrapper.java.additional_file property
• wrapper.java.additional_file.required property
• wrapper.java.additional_file.quotable property
• wrapper.java.additional_file.stripquotes property (No longer used as of 3.6.0)
• Usage Examples

Compatibility :	1.0.0
Editions :
Platforms :

Additional Java parameters to pass to Java when it is launched. These are not parameters for your application, but rather parameters for the JVM.

If you wish to dynamically change the list of additional Java parameters, there are a few ways to do so. The first is to make use of cascading include files to append a generated configuration file listing the wrapper.java.additional.<n> properties along with your JVM options. Alternatively, you may use the wrapper.java.additional_file property to reference a parameter file where you would simply list the JVM options without properties. Finally, you can pass the wrapper.java.additional.<n> as command line properties when launching the Wrapper.

<n> component:

Each element has a property name which starts with "wrapper.java.additional." and the "<n>" component of the property name is an integer number counting up from "1". By default, the numbering should be in sequence without gaps. The wrapper.ignore_sequence_gaps property can optionally be set to allow gaps in the sequence.

Individual parameter entry:

It is important that each property only define a single argument.

wrapper.java.additional.1=-server
wrapper.java.additional.2=-Dprop=TRUE

wrapper.java.additional.1=-server -Dprop=TRUE

wrapper.java.additional.1=--add-opens module/package=target-module

Quotes:

Version 3.6.0 and later

Starting with version 3.6.0, the handling of special characters has changed to ensure consistency across all platforms. In most cases, you can write the argument exactly as you intend it to be received by the JVM.

An exception to this is leading or trailing spaces, which are normally trimmed from property values. To preserve these spaces, it is necessary to enclose the value in quotation marks. These quotation marks will be stripped if the corresponding "quotable" property is set to TRUE. To retain actual quotes in the value, escape them with a '\' character. Backslashes must also be doubled ('\\'). No other characters are allowed to be escaped.

When stripping quotes, only the the following changes will apply:

• '\\' will become '\',
• '\"' will become '"'
• '"' will become ''

wrapper.java.additional.1=-Dprop="my arg  "
wrapper.java.additional.1.quotable=TRUE

Prior to version 3.6.0

In older versions of the Wrapper, the way quotes are handled varies between platforms. On Windows, the Java process is created using a command line where arguments containing spaces must be quoted. The quotes are automatically stripped from the command line when the process is launched. On Linux, however, an array is used, and arguments are passed directly.

To simulate the Windows behavior and use the same configuration across platforms, it is possible to mark certain arguments with a strip quotes flag (stripquotes property = TRUE). This flag is only used on Unix, and specifies that quotes must be stripped before passing the parameter(s) to the JVM.

When stripping quotes, all other characters except for the following will remain unchanged.

• '\\' will become '\',
• '\"' will become '"'
• '"' will become ''

Compatibility :	3.6.0
Editions :
Platforms :

If a JVM argument (usually a system property) needs to include trailing spaces, you can preserve them by enclosing the value in quotation marks. These quotation marks will be stripped if you set the corresponding wrapper.java.additional.<n>.quotable property to TRUE.

The default value for this property is "FALSE".

When a "quotable" property is set to TRUE, actual quotes to be retained in the corresponding value must then be escaped with a '\' character, and backslashes must be doubled ('\\'). No other character are allowed to be escaped.

The following replacements will be made when stripping quotes.

• '\\' will become '\',
• '\"' will become '"'
• '"' will become ''

wrapper.java.additional.1=-Dprop1="value with trailing spaces   "
wrapper.java.additional.1.quotable=TRUE

Compatibility :	(No longer used as of 3.6.0)
Editions :
Platforms :

If a wrapper.java.additional.<n> value contains quotes, then the contents of the quotes will be passed to the JVM as a single argument on Windows. However on UNIX, the quotes will also be included as part of the argument value. In most cases, this is not correct behavior on UNIX, but it is this way to maintain backwards compatibility.

The wrapper.java.additional.<n>.stripquotes property makes it possible to tell the Wrapper to automatically strip those extra quotes on UNIX. The property is ignored on Windows.

Defaults to the value of the wrapper.java.additional.default.stripquotes property, which itself defaults to "FALSE".

<n> component:

Each element has a property name which starts with "wrapper.java.additional." and the "<n>" component of the property name is an integer number counting up from "1". By default the numbering should be in sequence without gaps". The wrapper.ignore_sequence_gaps property can optionally be set to allow gaps in the sequence.

wrapper.java.additional.1.stripquotes=FALSE

The following replacements will be made when stripping quotes. All other characters will remain unchanged.

• '\\' will become '\',
• '\"' will become '"'
• '"' will become ''

wrapper.java.additional.1=-server
wrapper.java.additional.2=-Dprop=TRUE
wrapper.java.additional.3=-Dmyapp.data="../MyApp Home"
wrapper.java.additional.3.stripquotes=TRUE

Compatibility :	3.5.17 (No longer used as of 3.6.0)
Editions :
Platforms :

Makes it possible to change the default strip quotes behavior on UNIX when you wish to have the same behavior for all wrapper.java.additional.<n> property values. The default value is "FALSE". The property is ignored on Windows.

wrapper.java.additional.default.stripquotes=FALSE

Compatibility :	3.5.36
Editions :
Platforms :

This property can be used to append the option with index 'n' only if the Java version is greater than or equal to the specified value.

The default value is '1.4' which is the oldest JVM version supported by the Wrapper. Any lower value is invalid and will cause the Wrapper to stop.

The value can be in the format '1.major[.minor[_revision]]' or 'major[.minor[.revision]]', regardless the version of Java. This is done to support both numbering schemes returned by 'java -version': prior to Java 9 the first format was used, while Java 9 and above use the second format.

The brackets indicate that the minor and revision components are optional. Leaving one or both unspecified means that these placeholders will accept any number.

wrapper.java.additional.<n>.java_version.min=1.7

wrapper.java.additional.<n>.java_version.min=8.0.40

Compatibility :	3.5.36
Editions :
Platforms :

This property can be used to append the option with index 'n' only if the Java version is lower than or equal to the specified value.

The default value is 'UNLIMITED'.

The value can be in the format '1.major[.minor[_revision]]' or 'major[.minor[.revision]]', regardless the version of Java. This is done to support both numbering schemes returned by 'java -version': prior to Java 9 the first format was used, while Java 9 and above use the second format.

The brackets indicate that the minor and revision components are optional. Leaving one or both unspecified means that these placeholders will accept any number.

wrapper.java.additional.<n>.java_version.max=9.0.1

wrapper.java.additional.<n>.java_version.max=9

Compatibility :	3.5.57, Requires Java 9+ (Deprecated as of 3.5.60)
Editions :
Platforms :

Before launching a JVM to run the Java application, the Wrapper will execute the Java command line with a --dry-run option to check that the command line is valid.

The wrapper.java.additional.<n>.app_only property can be set to TRUE to skip an option for the "--dry-run" command line.

This property has no effect when using versions of Java that do not support the --dry-run option (prior to Java 9).

The default value is "FALSE", which means that the specified option will be present in both the real Java command line and the "--dry-run" command line. In the vast majority of cases, FALSE is preferred so that all JVM options are verified.

There are a few cases where setting wrapper.java.additional.<n>.app_only to TRUE can be useful, though. For example, using the -XX:NativeMemoryTracking=[off|summary|detail] option to track native memory in JVMs will cause a warning when used in the --dry-run command line:

OpenJDK 64-Bit Server VM warning: Native Memory Tracking did not setup properly, using wrong launcher?

Most of the time, this warning won't be visible because the output will be logged at the level specified with the wrapper.java.query.loglevel property, which is DEBUG by default. However, it is not possible to track the native memory usage of a "--dry-run" JVM anyway because it won't run user's native code. It is therefore best not to include this option in the "--dry-run" command line.

wrapper.java.additional.4=-XX:NativeMemoryTracking=summary
wrapper.java.additional.4.app_only=TRUE

Compatibility :	3.5.60
Editions :
Platforms :

Before launching the Java application, the Wrapper will run the java command a few times to determine the characteristics of the current Java installation and the appropriate settings for the application. In most cases, the command lines for these Java invocations are built by the Wrapper without the user having to worry about it. In a few rare scenarios, however, it may be necessary to add or remove certain options to these command lines. Let's first draw the list of these Java invocations and their roles:

• java --version: This invocation retrieves information about the current Java installation (version, vendor, etc.). It only uses the --version parameter, no additional options are needed.

• Call to the WrapperBootstrap class: This invocation retrieves information about the Java Application (main module, main class, package, etc). The Wrapper will build the command line with its own options and parameters. In particular, the classpath, module path and list of modules must exactly match those of the command used when launching the application. In a few rare cases, some additional arguments may be added by the user in order to load the main class.

• Call with the --dry-run option: The --dry-run option was introduced in Java 9, therefore this invocation is not performed on earlier Java versions. This call is used to validate the Java command line right before executing the application. The command line is essentially the one used when launching the application with the addition of the --dry-run option which specifies that the main method should not be executed.

  In some rare cases, one might want to remove certain options that are not relevant in the dry run context. For example, using the -XX:NativeMemoryTracking=[off|summary|detail] option to track native memory in JVMs will cause a warning when used in the --dry-run command line:

  OpenJDK 64-Bit Server VM warning: Native Memory Tracking did not setup properly, using wrong launcher?

  Most of the time, this warning won't be visible because the output will be logged at the level specified with the wrapper.java.query.loglevel property, which is DEBUG by default. However, it is not possible to track the native memory usage of a "--dry-run" JVM anyway because it won't run user's native code. It is therefore best not to include this option in the "--dry-run" command line.

The wrapper.java.additional.<n>.scope property controls in which command line(s) the parameter with index 'n' should be referenced.

Possible values are:

• DRYRUN_APP: to pass the parameter to both the --dry-run instance and the application. This value is suitable to the vast majority of cases.

• APP: to only pass the parameter to the application.

• BOOTSTRAP_DRYRUN_APP: to pass the parameter to the bootstrap instance, the --dry-run instance and the application.

The default value is DRYRUN_APP.

# The following option is used for the --dry-run and application calls:
wrapper.java.additional.1=-Xmx1g
wrapper.java.additional.1.scope=DRYRUN_APP

# The following option is used for the bootstrap, --dry-run and application calls:
wrapper.java.additional.2=-agentlib:mylib
wrapper.java.additional.2.scope=BOOTSTRAP_DRYRUN_APP

# The following option is only for the application:
wrapper.java.additional.3=-XX:NativeMemoryTracking=summary
wrapper.java.additional.3.scope=APP

Compatibility :	3.5.16
Editions :
Platforms :

This property provides a way to specify a file that can contain one or more JVM arguments to be passed to the JVM. This can be very useful when the parameter list needs to be generated dynamically or via an installer.

Any parameters defined in this file will appear after those defined using the standard wrapper.java.additional.<n> properties.

Starting with Wrapper version 3.5.23, any environment variable references in the file will be expanded.

File Format:

The file format is simple.

• It must start with an encoding directive line just like the Wrapper configuration file. This is needed to tell the Wrapper what encoding to use when reading the file. If this line is missing, then the Wrapper will attempt to proceed after logging a warning. The encoding used in the file may be different from the encoding used in other configuration files.
• The '#' character is interpreted as a comment character. To include a '#' character in a property value, the value must either be quoted ("#") or escaped by a second '#' character.
• By default, any non-empty line that is not a comment will be interpreted as an argument whose value spans the entire line. This behavior can be changed by setting the wrapper.java.additional_file.quotable property to TRUE. In this mode, arguments are delimited by any unquoted spaces. This allows multiple parameters to be listed on the same line. Values that contain spaces must be enclosed in quotes; these quotes will be removed during file parsing.

@encoding=UTF-8
# Example arguments: One argument per line
-DTEST1=Value1
-DTEST2=Value2 with space
-DTEST3=Value3 with space
-DTEST4=Value4

@encoding=UTF-8
# Example arguments: Multiple arguments in one line
-DTEST1=Value1 -DTEST2="Value2 with space" "-DTEST3=Value3 with space"

# More arguments
-DTEST4=Value4

Compatibility :	3.5.36
Editions :
Platforms :

Specifies if the Java additional file is required or not. If it is required and not found, the Wrapper will stop without starting the JVM. If it is not required, the file will be ignored when not found.

The default value is TRUE.

wrapper.java.additional_file.required=FALSE

Compatibility :	3.6.0
Editions :
Platforms :

When set to TRUE, the quotes contained in the "additional file" will be stripped. This allows you to use quotes as delimiters for values and thus list multiple arguments on a single line.

Also, quotes can be used as delimiters to retain leading or trailing spaces in arguments.

The default value for this property is "FALSE".

"-Dprop1=val 1" -Dprop1="val 2" -Dprop1=val3

When a "quotable" property is set to TRUE, actual quotes to be retained in the corresponding value must then be escaped with a '\' character, and backslashes must be doubled ('\\'). No other character are allowed to be escaped.

The following replacements will be made when stripping quotes.

• '\\' will become '\',
• '\"' will become '"'
• '"' will become ''

wrapper.java.additional_file.quotable=TRUE

@encoding=UTF-8
-DTEST1=Value1 -DTEST2="Test Value with spaces."

Compatibility :	3.5.16 (No longer used as of 3.6.0)
Editions :
Platforms :

Different platforms handle parameters with spaces differently. To make a given configuration work consistently, you should always quote those values. They will be used as is on Windows. However, on UNIX platforms, the quotes will be stripped as the command line is broken into a parameter list.

In almost all cases, you will want to strip these quotes. The default value is "FALSE".

wrapper.java.additional_file.stripquotes=FALSE

@encoding=UTF-8
-DTEST1=Value1 -DTEST2="Test Value with spaces."

• wrapper.app.parameter.<n> (1.0.0)

  Set the parameters of your Java application.

• wrapper.app.parameter.<n>.quotable (3.6.0)

  Allows to use quotes as delimiters in application parameters.

• wrapper.app.parameter.backend (3.6.0)

  Allows application parameters to be passed through the backend instead of the command line.

• wrapper.app.parameter_file (3.5.17)

  Specifies the path of the file containing the application parameters.

• wrapper.app.parameter_file.quotable (3.6.0)

  Allows to use quotes as delimiters for values listed in the "parameter file".

• wrapper.app.parameter_file.required (3.5.17)

  Specifies if the parameter file is required or not.

• wrapper.app.property.<n> (3.5.57)

  Configure application specific properties to be sent via pipe or socket.

• wrapper.app.property.<n>.java_version.min (3.5.57) ( Std/Pro )

  Append application property with index 'n' only if the Java version is greater than or equal to the specified value.

• wrapper.app.property.<n>.java_version.max (3.5.57) ( Std/Pro )

  Append application property with index 'n' only if the Java version is lower than or equal to the specified value.

• wrapper.app.property.<n>.quotable (3.6.0)

  Allows to use quotes as delimiters in application properties.

• wrapper.app.property_file (3.5.57)

  Specifies the path of the file containing the application properties.

• wrapper.app.property_file.quotable (3.6.0)

  Allows to use quotes as delimiters for values listed in the "property file".

• wrapper.app.property_file.required (3.5.57)

  Specifies if the property file is required or not.

• wrapper.java.additional.<n> (1.0.0)

  Configure additional parameters to pass to the JVM.

• wrapper.java.additional.<n>.java_version.max (3.5.36) ( Std/Pro )

  Append option with index 'n' only if the Java version is lower than or equal to the specified value.

• wrapper.java.additional.<n>.java_version.min (3.5.36) ( Std/Pro )

  Append option with index 'n' only if the Java version is greater than or equal to the specified value.

• wrapper.java.additional.<n>.quotable (3.6.0)

  Allows to use quotes as delimiters in JVM parameters.

• wrapper.java.additional_file (3.5.16)

  Sets the path to a file containing JVM parameters.

• wrapper.java.additional_file.quotable (3.6.0)

  Allows to use quotes as delimiters for values listed in the "additional file".

• wrapper.java.additional_file.required (3.5.36)

  Specifies if the Java additional file is required or not.

• wrapper.java.mainclass (1.0.0)

  Sets the class holding the main method called when the Wrapper starts the JVM.

• wrapper.java.tmpdir.<x> (3.5.0)
• wrapper.java.tmpdir.required (3.5.0)

  Specifies if the Wrapper should exit when the Java temporary directory cannot be written to.

• wrapper.java.tmpdir.warn_silently (3.5.0)

  Specifies whether a message should be logged at the DEBUG or WARN log level when the Java temporary directory could not be written to.