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.
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)
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 proper 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.
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:
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.
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:
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
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):
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.
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):
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').
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.
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.