Cascading Configuration Files

Starting with Wrapper version 3.0.0, it is possible to specify "include files" within a configuration file like cascading style. This is useful where there is a need to override default values without modifying the main default configuration file "wrapper.conf".

Syntax:

Include files are specified by placing a line in the configuration file with the following syntax: 

@include ../conf/wrapper2.conf

Layer Depth:

Include files can be nested up to 10 levels deep with cascading style.

Property Priority:

The order of where within a file you should put the definition of the include file is important. If there are the same name of properties in the configuration files, you should pay attention to the order.

The definition of "@include" line should be placed at the very bottom of the configuration file. For example, the "wrapper.conf" file includes "File2.conf" and the "File2.conf" file includes "File3.conf". In addition, the property "PropertyX=valueX" is defined in EACH of the three files. In this case, the property value "PropertyX=value3" of "File3.conf" will be set after processing all files.

On the other example, properties set after the included file will override properties settings within the included files.

This rule applies to the all contents of include files as well.

Path:

If relative paths to the include files are specified, be aware that all paths must be relative to the location of the Wrapper working directory. By default, the working directory is the location of the wrapper.exe file on Windows, or of the script used to launch the Wrapper on UNIX. The working directory can be changed using the wrapper.working.dir property, but this does not take effect until after the full configuration file has been loaded. This means that relative include file references will always be relative to the original working directory of the Wrapper.


Use with Environment Variables:

When using include files, it is possible to also reference environment variables. You can either reference the environment variables that are already defined by the Wrapper, or set your own environment variables in the configuration file as needed.

The pre-defined environment variables can be found in the Environment Variables page.

When the path to the include file containing the variable matches an existing file on your machine, this will allow you to specify in that file a set of configuration properties that you only want to apply for a specific environment.

For example, if you want to include platform-specific configurations, you may reference the following @include directive in your main configuration file:

wrapper.conf 
@include ../conf/wrapper-%WRAPPER_OS%.conf

And then create a file for each platform that needs a specific configuration.

wrapper-windows.conf 
wrapper.java.command=
wrapper.registry.java_home=HKEY_LOCAL_MACHINE\SOFTWARE\MyCompany\MyApplication\JavaHome
wrapper-linux.conf 
wrapper.java.command=%JAVA_HOME%/bin/java

Require an include file:

If the specified file can not be found for any reason, then it is just ignored. This makes it easy to specify a series of optional cascading configuration files which users may or may not create yet.

In some cases, an include file is required for proper operation of an application. This is particularly the case for secure files containing passwords or sensitive data. 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

Starting with Wrapper version 3.6.0, it is possible to specify whether include files are optional or required by default. This inclusion mode can be set with the @include.default_mode directive and can be changed anywhere in the current configuration file or its included files.

Example: 
@include.default_mode=required

# These are required includes
@include ../conf/wrapper-settings1.conf
@include ../conf/wrapper-settings2.conf
@include ../conf/wrapper-settings3.conf

@include.default_mode=optional

# These are optional includes
@include ../conf/wrapper-additional-settings1.conf
@include ../conf/wrapper-additional-settings2.conf
@include ../conf/wrapper-additional-settings3.conf

@include.optional makes it possible to specify an optional include file when the default inclusion mode is 'required'.

Example: 
@include.default_mode=required

# This is a required include
@include ../conf/wrapper-settings.conf

# This is a optional include
@include.optional ../conf/wrapper-additional-settings.conf

For Debugging

Enable Debug Messages:

As default, include files are designed to be optional, so the Wrapper will silently skip the include file if it cannot be found. This can make debugging problems involving include files frustrating. To help with this, it is possible to enable debug messages about include files using the following declaration "@include.debug" before any @include file references. Be aware that this debug declaration will have to be done before your configured logging properties have been processed in the configuration file "wrapper.conf". 

@include.debug

Output:

The output will show up on the console as well as in the default wrapper.log file, which will be located in the same directory as the Wrapper binary. If the Wrapper is being run as a Windows Service, then the default wrapper.log will show up in the Windows System32 directory.

Cascading a License File:

A newly created License file including License Key Properties can be placed in the same directory of Configuration file "wrapper.conf". See the details at License file in Cascading Configuration File.