Hosted by:
SourceForge
Get Firefox!

Environment Variables
Environment Variables
Configuration Property Overview
Working with Environment Variables
Environment Variable Expansion

The Wrapper supports environment variable expansion at run time within the values of any property. To maintain the platform independent nature of the wrapper.conf file, the windows syntax is used for all platforms.

When the Wrapper is run as a service, environment variables will be loaded from the system registry rather than from the environment. This was necessary because Windows loads the environment variables which are available to services when the machine is booted. Any changes to the system environment variables in the registry (set directly or through the system control panel) are not made available to the services until the machine is once again rebooted. By loading the environment variables from the registry, the reboot can be avoided while providing the same functionality.

Example referencing the JAVA_HOME environment variable:
wrapper.java.command=%JAVA_HOME%/bin/java

This will expand at runtime to a fully qualified path on any system which defines the JAVA_HOME environment variable.

Windows:
wrapper.java.command=C:\Sun\jdk1.3/bin/java
UNIX:
wrapper.java.command=/opt/IBMJava2-131/bin/java

If a referenced environment variable is not defined, then it will be left unchanged in the property value.

Environment Variable Definition

The Wrapper supports the ability to define environment variables from within the wrapper.conf file or from the command line. Once defined, the environment variable can be referenced like any other environment variable. This includes use in variable expansion as described above.

Environment variables are defined by using special property names which begin with "set." or "set.default." followed by the name of the environment variable. The value of the property will be the value of the new environment variable.

set.EXTERN_APP=C:/ExternAppHome

If the "set.default." syntax is used, the environment variable will only be set if it does not yet exist. This can be useful for defining a series of default environment variable values.

set.default.EXTERN_APP=C:/ExternAppHome

The ability to define environment variables make it possible to easily modify values that may be used throughout a configuration file. The example below shows how an environment variable can be used to specify the location of an external application.

set.EXTERN_APP=C:/ExternAppHome

wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=%EXTERN_APP%/lib/jar1.jar
wrapper.java.classpath.3=%EXTERN_APP%/lib/jar2.jar
wrapper.java.classpath.4=%EXTERN_APP%/lib/ext/jar3.jar
wrapper.java.classpath.5=%EXTERN_APP%/lib/ext/jar4.jar

The use of environment variables definitions can be very powerful if you understand how and when their values are set. Environment variables which were set before the Wrapper is launched can of course be used as usual. If the same variable name is specified in the configuration file then the value in the configuration file will override the existing value.

Environment variables defined from the command line work a little differently. These values will override any values from either the system or those set in the configuration file. This makes it possible to define default environment variables within the wrapper.conf file and then override that value from the command line.

Windows:
Wrapper.exe -c ..\conf\wrapper.conf "set.EXTERN_APP=C:\Program Files\ExternAppHome"
Unix:
wrapper ../conf/wrapper.conf set.EXTERN_APP=/usr/lib/externapphome

NOTE

Notice that like all properties set from the command line, properties which include spaces can be defined by including the entire property name, value pair in quotes.

Default Environment Variable Definitions

On startup, the Wrapper sets the following environment variables into its own environment. These variables can be used within the wrapper.conf file or by accessing the environment of the JVM or any of its child processes.

  • The WRAPPER_FILE_SEPARATOR variable is set to '\' on Windows and '/' on UNIX platforms. The variable can be used to set platform independent values for additional environment variables or properties.

    In general it is safe to always use '/' as a file separator for paths used within Java. Java is designed to work correctly on all platforms when '/' is used.

  • The WRAPPER_PATH_SEPARATOR variable is set to ';' on Windows and ':' on UNIX platforms. The variable can be used to build up platform independent paths.

    Example:
    set.PATH=..%WRAPPER_FILE_SEPARATOR%lib%WRAPPER_PATH_SEPARATOR%%PATH%

    Which resolves to the following:

    Windows:
    set.PATH=..\lib;%PATH%
    UNIX:
    set.PATH=../lib:%PATH%
  • The WRAPPER_OS variable is set to the name of the OS for which the currently running copy of Wrapper was built.

    Example:
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/%WRAPPER_OS%-%WRAPPER_ARCH%-%WRAPPER_BITS%

    Which resolves to the following:

    Windows:
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/windows-x86-32
    Linux:
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/linux-x86-32
    Solaris:
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/solaris-sparc-32
  • The WRAPPER_ARCH variable is set to the name of the architecture for which the currently running copy of Wrapper was built.

  • The WRAPPER_BITS variable is set to the 32 or 64 bit depth for which the currently running copy of Wrapper was built.

by Leif Mortenson

last modified: