When the Wrapper is launched, it is very careful about making sure that the working directory is in a known and constant state. This helps to guarantee that there will be no path related problems caused by a user launching the Wrapper from an unexpected location.

Windows:

On Windows platforms, the wrapper.exe sets its own working directory immediately on startup to the directory where it is located. This is especially critical on Windows platforms. When running in a console, the working directory is normally set to the current directory when an application is launched. This means that it would be different if the Wrapper was launched as bin\wrapper.exe versus .\wrapper.exe versus ..\bin\wrapper.exe. In addition, when running as a Windows Service, the working directory is normally set to the Windows system32 directory. By always forcing the working directory to the location of the wrapper.exe, integrators can reliably make use of relative path references.

Linux/Unix:

Things work a little differently on Linux/Unix platforms. There, the Wrapper binary does not set its own working directory by default. This is left up to the script used to launch the Wrapper. While this has traditionally given more flexibility to Unix users, the same issues as exist on the Windows platform also exist on Unix. However, by using the scripts shipped with the Wrapper distribution, all path issue should be taken good care of.

Flexible Work:

There are times however where having the working directory set to the location of the Wrapper binary makes it impossible to run some applications cleanly. An example is an application which expects the working directory to be at the root of the file system. The only way to run such an application under the Wrapper would be to place the Wrapper binary and scripts in the root directory. Not something that most system administrators would want to do.

To allow such cases, the wrapper.working.dir property was added. It is very important to understand exactly how this property works to avoid problems.

The wrapper.working.dir property can be specified either in the wrapper.conf or as a parameter to the Wrapper binary. However, the property does not take effect until AFTER all of the Wrapper's properties have been completely parsed. This means that the location of the wrapper.conf file and any include files (cascading style) referenced therein must still be referenced using locations relative to the Wrapper binary. This is necessary to make sure that the configuration file can be loaded reliably.

Any and all paths defined in OTHER properties specified either from the command line or within the wrapper.conf file will then be relative to the location specified by the wrapper.working.dir property.

Confused yet? An example or two is in order.

Windows will be used as an example, but the issues are all the same for Linux/Unix platforms.

C:\myapp\
    bin\
        wrapper.exe
    conf\
        wrapper.conf
        include.conf
    lib\
        wrapper.dll
        wrapper.jar
        myapp.jar
    logs\
        wrapper.log

Without using the wrapper.working.dir property, the working directory will be located in the C:\myapp\bin directory. The Wrapper would be launched using the following command.

wrapper.exe -c ../conf/wrapper.conf

Paths in the wrapper.conf file would be configured as follows. (Note this is not a complete configuration file.):

#include ../conf/include.conf
wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=../lib/myapp.jar
wrapper.java.library.path.1=../lib
wrapper.pidfile=./wrapper.pid
wrapper.java.pidfile=./java.pid
wrapper.logfile=../logs/wrapper.log

Note that all paths are relative to the location of the wrapper.exe file.

The same directory structure used in the previous example will be reused.

This time the wrapper.working.dir property will be set the parent of the bin directory in which the wrapper.exe file is located. This is a location that is commonly referred to as the application HOME directory. C:\myapp in this case.

The wrapper.working.dir property can be specified either on the command line used to launch the Wrapper, or within the wrapper.conf file. In either case, the specified directory can be absolute or relative. In the case of a relative directory, the directory will be relative to the location of the Wrapper binary.

This example will specify the new working directory within the wrapper.conf file. So in this case, the command used to launch the Wrapper is unchanged, meaning that the batch files and scripts that is shipped with the Wrapper can be used without any modification.

wrapper.exe -c ../conf/wrapper.conf

When the Wrapper is launched, it immediately sets its own working directory to the location of the Wrapper binary. Then loads the wrapper.conf file and any include files (cascading style) using that working directory. Once the configuration is loaded, the working directory will be changed to the new location specified by the wrapper.working.dir property. All future paths including the launching of the JVM will be done using this new working directory.

For this example, the wrapper.conf fragment used above will be modified as follows:

wrapper.working.dir=../
#include ../conf/include.conf
wrapper.java.classpath.1=lib/wrapper.jar
wrapper.java.classpath.2=lib/myapp.jar
wrapper.java.library.path.1=lib
wrapper.pidfile=bin/wrapper.pid
wrapper.java.pidfile=bin/java.pid
wrapper.logfile=logs/wrapper.log

Notice that the location of the include file (cascading style) and wrapper.working.dir property are both relative to the Wrapper binary location, but all other paths are now relative to the new working directory.

The location of the wrapper.working.dir property in the wrapper.conf file is not important as it is not applied until after the entire configuration file has been parsed.

Problems?:

If you encounter any problems related to configuring the Wrapper, the first thing that should be done is to enable the wrapper.debug property and rerun the application. Make sure that the application can be run as a console application before attempting to run it as a service or daemon process.