Index

wrapper.app.parameter.<n>

Compatibility :1.0.0
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

These properties are used to specify the parameters that will be passed to your application's main method.

When the value of the wrapper.java.mainclass property is org.tanukisoftware.wrapper.WrapperSimpleApp, the first parameter to the application must be the name of the class that contains your main method. All other parameters are then passed to your application's main method in order. Please see the Integration section for more details.

<n> component:

Each element has a property name that starts with wrapper.app.parameter. and the "<n>" component of the property name is an integer number counting up from "1". By default, there can be no missing numbers. 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 parameter.

This will be interpreted as a single parameter:
wrapper.app.parameter.1=-c conf/myconffile.conf

This will be interpreted as two parameters:
wrapper.app.parameter.1=-c
wrapper.app.parameter.2=conf/myconffile.conf


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 parameter value exactly as you intend it to be received by the Java application.

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 ''
Example:
wrapper.app.parameter.1="  my arg"
wrapper.app.parameter.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 parameters 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 ''

wrapper.app.parameter.<n>.quotable

Compatibility :3.6.0
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

If a parameter value needs to include leading or 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.app.parameter.<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 ''
Example:
wrapper.app.parameter.1="  param1"
wrapper.app.parameter.1.quotable=TRUE
wrapper.app.parameter.2="  param2 with\"quotes\""
wrapper.app.parameter.2.quotable=TRUE

wrapper.app.parameter.<n>.stripquotes

Compatibility :3.5.17 (No longer used as of 3.6.0)
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :Windows (Not Supported)Mac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

WARNING

As of version 3.6.0 this property is no longer needed and therefore becomes invalid. Any value marked with "stripquotes" should be revised to no longer escape backslashes ('\') and quotes ('"').

If a wrapper.app.parameter.<n> value contains quotes, then the contents of the quotes will be passed to the Java Application 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.app.parameter.<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.app.parameter.default.stripquotes property, which itself defaults to "FALSE".

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

  • '\\' will become '\',
  • '\"' will become '"'
  • '"' will become ''
Example:
wrapper.app.parameter.1="parm1"
wrapper.app.parameter.1.stripquotes=TRUE
wrapper.app.parameter.2=parm=\"value\"
wrapper.app.parameter.2.stripquotes=TRUE

wrapper.app.parameter.default.stripquotes

Compatibility :3.5.17 (No longer used as of 3.6.0)
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :Windows (Not Supported)Mac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

WARNING

As of version 3.6.0 this property is no longer needed and therefore becomes invalid. Any value marked with "stripquotes" should be revised to no longer escape backslashes ('\') and quotes ('"').

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

Example:
wrapper.app.parameter.default.stripquotes=FALSE

wrapper.app.parameter_file

Compatibility :3.5.17
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

This property provides a way to specify a file that can contain one or more parameters 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.app.parameter.<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 a parameter whose value spans the entire line. This behavior can be changed by setting the wrapper.app.parameter_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 containing spaces must be quoted.

Example of Parameter File (with .quotable=FALSE):
@encoding=UTF-8
# Example parameters: One parameter per line
param1
param2 with space
param3
param4

Example of Parameter File (with .quotable=TRUE):
@encoding=UTF-8
# Example parameters: Multiple parameters in one line
param1 "param2 with space" param3

# More parameters
param4

NOTE

Versions before 3.6.0 don't have the "quotable" mode, and multiple parameters per line are always allowed.

If any of the values need to include a space, then it is necessary to add quotes following the rules described below to make sure the file works consistently across all platforms.

wrapper.app.parameter_file.required

Compatibility :3.5.36
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

Specifies if the parameter 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.

Example:
wrapper.app.parameter_file.required=FALSE

wrapper.app.parameter_file.quotable

Compatibility :3.6.0
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

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

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

The default value for this property is "FALSE".

WARNING

Versions before 3.6.0 don't have the "quotable" mode, and multiple arguments per line are always allowed.

If any of the values need to include a space, then it is necessary to add quotes following the rules described below to make sure the file works consistently across all platforms.

In the example below, the line was interpreted as three different parameters before version 3.6.0. Since version 3.6.0, they are interpreted as a single parameter containing quotes, unless wrapper.java.additional_file.quotable is set to TRUE.

"parameter 1" "parameter 2" parameter3

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 ''
Example:
wrapper.app.parameter_file.quotable=TRUE
Example of Parameter File UTF-8:
@encoding=UTF-8
-DTEST1=Value1 -DTEST2="Test Value with spaces."

wrapper.app.parameter_file.stripquotes

Compatibility :3.5.17 (No longer used as of 3.6.0)
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :Windows (Not Supported)Mac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

WARNING

As of version 3.6.0 this property is no longer needed and therefore becomes invalid. Any value marked with "stripquotes" should be revised to no longer escape backslashes ('\') and quotes ('"').

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".

Example:
wrapper.app.parameter_file.stripquotes=FALSE
Example of Parameter File UTF-8:
@encoding=UTF-8
-DTEST1=Value1 -DTEST2="Test Value with spaces."

wrapper.app.parameter.backend

Compatibility :3.6.0
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

This property can be set to TRUE to pass application parameters via the backend instead of the command line.

If any application parameters contain sensitive data, the Wrapper will require this property to be set to TRUE to prevent the data from appearing on the command line.

The default value is "FALSE".

Example:
wrapper.app.parameter.backend=TRUE

Reference: Parameters