World Map
Java Service Wrapper is the easiest way to make your product more reliable.
  • Free Trial
  • Buy Now
Configuration File Directives

Overview: Configuration File Directives

As the Java Service Wrapper parses its configuration file, in most cases, it will ignore all text that comes after a '#' character and treat it as a comment. There are a small set of exceptions to this rule however.

The Wrapper historically followed the C language pattern of defining special directives which are processed as the configuration file is loaded.

Configuration File Encoding

Starting with Wrapper version 3.5.0, it became possible to specify the encoding of individual configuration files. The most portable encoding is UTF-8, but other encodings are supported on some platforms.

The encoding directive must be specified on the first line of a configuration file. The Wrapper will log a warning if any file is missing the directive. It is possible to specify different encodings in include files (cascading style)

UTF-8 Example:
#encoding=UTF-8

wrapper.debug=FALSE
...

Include Cascading Configuration File

It is possible to split a configuration in one or more optional configuration files and then include them from the main file. See the Cascading Configuration File ("include file") page for more information.

Example:
#include ../conf/wrapper-settings.conf

By design, the Wrapper will silently skip over any include files that it is unable to locate or read for any reason. This can be very powerful as it makes it possible to create platform specific configurations or optionally override existing property values.

In some cases however, an include file is required for propper operation of an application. Starting with Wrapper version 3.5.5, it is possible to specify a required include, which will cause an error and prevent the Wrapper from starting if it is missing.

Example:
#include.required ../conf/wrapper-settings.conf

Debug Include Files

Starting with Wrapper version 3.3.0, it is possible to debug the way the #include directive works by seeing exactly what is and isn't being included. See the Debug Messages in the "include file" (cascading style) page for more information.

Example:
#include.debug

Debug Properties

Starting with Wrapper version 3.5.4, it is possible configure the Wrapper so that it outputs a message on startup whenever any property is overwritten by another declaration, or when a property can not be set because its value is fixed.

Wrapper version 3.5.27 improves this feature. It is now possible to control the log level of these messages and to specify if the Wrapper should exit after logging them. You could also apply different settings per sections of your configuration files and thus allow to be more or less strict in some parts. This can be achieved using two new directives:

Depending on the nature of the properties the Wrapper will output different messages. These messages are described bellow.

NOTE

These messages are only logged on debug mode by default because it is common practice to overwrite property values using optional Cascading Configuration File ("include file"), or other methods.

WARNING

Because the properties wrapper.name and wrapper.displayname are defined in the UNIX shell script, if you use this script to launch the Wrapper and if you debug the properties using the above directives, you may get warning messages as those variables are also defined by default in the configuration file.

You can avoid these messages by either removing the redundant properties in the configuration file or by uncommenting the line '#APP_NAME_PASS_TO_WRAPPER=false' in the script file.

The second option will cause the script to no longer pass these parameters to the Wrapper. Be careful not to deactivate the properties 'APP_NAME' and 'APP_LONG_NAME' which are required to the proper functioning of the script.

Messages

To help understand why a property has a specific value, it can be useful to visualize when its value has been changed, or on the contrary, when it has been ignored despite an attempt to overwrite it.

Here are the messages you can get:

Overlapped Properties:

The Wrapper is setup so that the last defined instance of a specific property will be used. This can be very powerful as default values can be setup and then reference an optional include file which could contain values specific to a system.

Property Redefinition Example:
STATUS | wrapper  | The "foo.bar" property was redefined on line #8 of configuration file: /home/wrapper/conf/wrapper.conf
STATUS | wrapper  |   Old Value foo.bar=123
STATUS | wrapper  |   New Value foo.bar=XYZ

Command line Properties:

Property values specified on the Wrapper command line are 'final', meaning that they can not be changed or overwritten by values in the configuration file. This is very useful because a user can run the Wrapper with a test value without having to actually edit the configuration file.

Final Property Redefinition Example:
STATUS | wrapper  | The "foo.bar" property was defined on the Wrapper command line and can not be overwritten.
STATUS | wrapper  |   Ignoring redefinition on line #8 of configuration file: /home/wrapper/conf/wrapper.conf
STATUS | wrapper  |   Fixed Value foo.bar=123
STATUS | wrapper  |   Ignored Value foo.bar=XYZ

Internal Environment Variables:

The Wrapper also sets several internal environment variables. These are done using final properties. If the user configuration file attempts to set any of these, then the Wrapper will ignore them and maintain the values set by the Wrapper.

Final Property Redefinition Example:
STATUS | wrapper  | The "set.WRAPPER_ARCH" property is defined by the Wrapper internally and can not be overwritten.
STATUS | wrapper  |   Ignoring redefinition on line #10 of configuration file: /home/wrapper/conf/wrapper.conf
STATUS | wrapper  |   Fixed Value set.WRAPPER_ARCH=x86
STATUS | wrapper  |   Ignored Value set.WRAPPER_ARCH=special

#properties.on_overwrite.loglevel

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

This directive is used to set the log level at which the messages should be logged.

Valid values include:

  • NOTICE: to log at the NOTICE log level.

  • ADVICE: to log at the ADVICE log level.

  • FATAL: to log at the FATAL log level.

  • ERROR: to log at the ERROR log level.

  • WARN: to log at the WARN log level.

  • STATUS: to log at the STATUS log level.

  • INFO: to log at the INFO log level.

  • DEBUG: to log at the DEBUG log level.

The default value is DEBUG.

Example (log the overwritten properties at a warning level):
#properties.on_overwrite.loglevel=WARN

NOTE

Use of the directive #properties.debug has been deprecated as of Wrapper version 3.5.27 in favor of those new directives that offer finer control on debugging properties. For backwards compatibility #properties.debug will have the same effect as #properties.on_overwrite.loglevel=STATUS.

#properties.on_overwrite.exit

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

This directive is used to specify if the Wrapper should exit if any property is overwritten.

Valid values include:

  • TRUE: specifies that the Wrapper should exit if any property following this directive is overwritten.

  • FALSE: specifies that the Wrapper should not exit if any property following this directive is overwritten.

The default value is FALSE.

Example (exit if any overwritten property is encountered):
#properties.on_overwrite.exit=TRUE

Usage

A directive is valid from the line where it is inserted in the configuration file until the end of the file or until a next directive with the same name is encountered. If found, the value of the new directive will then become valid for the section following in the configuration file.

If a property is overwritten within a section where #properties.on_overwrite.exit has been set to TRUE, a message will be logged with at least a FATAL level (it would remain at level ADVICE or NOTICE if previously set with '#properties.on_overwrite.loglevel').

Example:
wrapper.name=@app.name@
wrapper.lang.folder=../lang
...

#properties.on_overwrite.loglevel=STATUS
wrapper.lang.folder=../../lang
...

#properties.on_overwrite.loglevel=INFO
wrapper.name=newAppName
...

#properties.on_overwrite.exit=TRUE
wrapper.app.parameter.3=start
...

wrapper.app.parameter.3=start_app
...

#properties.on_overwrite.exit=FALSE
...

In the above configuration, wrapper.lang.folder will be logged with a 'STATUS' level, wrapper.name will be logged with an 'INFO' level, and wrapper.app.parameter.3 will be logged at a 'FATAL' level causing the Wrapper to exit. Any property following '#properties.on_overwrite.exit=FALSE' will not cause the Wrapper to exit and will be logged with an 'INFO' level, as previously set.

NOTE

Starting with version 3.5.27, the Wrapper will also log messages if the command line contains duplicated properties or attempts to set an internal environment variable.

You can still use #properties.on_overwrite.loglevel and #properties.on_overwrite.exit to control the log level at which these messages should appear and to specify if the Wrapper should exit after logging them. If several directives are set in the configuration file, the last directive of each type will apply.

Reference: Loglevel