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

Index

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 configuration file "wrapper.conf", 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 is 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.

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

NOTE

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 configuration file "wrapper.conf" 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.

Special Property Name starting with "set." and "set.default." :

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." property name is used, the environment variable will only be set if it does not exist yet. This can be useful for defining a series of default environment variable values. 

set.default.EXTERN_APP=C:/ExternAppHome

Example:

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.

From Command Line:

Environment variables defined from the command line work a little differently. These values from command line 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 configuration file "wrapper.conf" and then also to change that value from the command line.

Command Line on Windows: (NOTE: A space is included in a property value) 
wrapper.exe -c ..\conf\wrapper.conf "set.EXTERN_APP=C:\Program Files\ExternAppHome"
Command Line on UNIX: 
wrapper ../conf/wrapper.conf set.EXTERN_APP=/usr/lib/externapphome

NOTE

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

Default Environment Variable Definitions

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

  • The WRAPPER_ARCH variable is set to the name of the architecture for which the currently running Wrapper was built. (Since ver. 3.3.0)

  • The WRAPPER_BIN_DIR variable is set to location of the Wrapper binary on startup. It can be used to define paths relative to this location even if the current working directory is modified. (Since ver. 3.3.0)

  • The WRAPPER_BITS variable is set to the 32-bit or 64-bit depth for which the currently running Wrapper was built. (Since ver. 3.3.0)

  • The WRAPPER_FILE_SEPARATOR variable is set to '\' on Windows and '/' on Linux/UNIX platforms, as a file separator. The variable can be used to set platform independent values for additional environment variables or properties. (Since ver. 3.1.0)

    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_HOSTNAME and WRAPPER_HOST_NAME variables are set to the resolved name of the machine where the Wrapper is currently running. (WRAPPER_HOST_NAME Since ver.3.3.2, WRAPPER_HOSTNAME Since ver.3.3.6)

  • The WRAPPER_INIT_DIR variable is set to the working directory of the process that launched the Wrapper process. The Wrapper always first forces the working directory to the location of the Wrapper binary while the configuration is loaded (see WRAPPER_BIN_DIR variable). Then if the user has configured another working directory, it will be changed to the location specified with the wrapper.working.dir property. This is all needed to make sure that the Wrapper runs 100% reliabily with a given configuration regardless of where the Wrapper was launched from. Some applications need to know where the user was when they launched the Wrapper however. In those cases this variable can be used. (Since ver. 3.5.6)

    Example of Configuration file: 
    wrapper.java.additional.1=-myinit.working.dir="%WRAPPER_INIT_DIR%"
wrapper.java.additional.1.stripquotes=TRUE

  • The WRAPPER_JAVA_HOME variable is set on Windows platforms when the Java command is located using the system registry. In other cases, it is recommended that a JAVA_HOME variable be set. (Since ver. 3.3.0)

  • The WRAPPER_LANG variable is set to the Language being used by the Wrapper. One use for this is to include configuration file fragments which have localized values. (Since ver. 3.5.5)

    The following example shows how to localize the Windows Service display name and descriptions. Note that the English is always loaded explicitly first (or its properties could be defined first). This is to make sure that the english values exist as a default. The Wrapper will then overwrite them with values in the localized "include file" (cascading style).

    Example (wrapper.conf): 
    #encoding=UTF-8
#include ../conf/wrapper-en.conf
#include ../conf/wrapper-%WRAPPER_LANG%.conf
...
wrapper.ntservice.name=myapp
...
    Example (wrapper-en.conf): 
    #encoding=UTF-8
wrapper.ntservice.displayname=My App Server
wrapper.ntservice.description=Application Server that does cool stuff.
    Example (wrapper-de.conf): 
    #encoding=UTF-8
wrapper.ntservice.displayname=My App Server
wrapper.ntservice.description=Application Server that does cool stuff.

  • The WRAPPER_OS variable is set to the name of the OS for which the currently running Wrapper was built. (Since ver. 3.3.0)

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

    The example above 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_PATH_SEPARATOR variable is set to ';' on Windows and ':' on Linux/UNIX platforms. The variable can be used to build up platform independent paths. (Since ver. 3.1.0)

    Example of Configuration file: 
    set.PATH=..%WRAPPER_FILE_SEPARATOR%lib%WRAPPER_PATH_SEPARATOR%%PATH%

    The example above resolves to the following:

    Windows: 
    set.PATH=..\lib;%PATH%
    UNIX: 
    set.PATH=../lib:%PATH%

  • The WRAPPER_PID variable is set to the PID of the Wrapper process when it is launched. It can be used in file names like the PID file or log file to make sure that you get a unique file name when launching multiple copies of the Wrapper with the same configuration file. (Since ver. 3.3.7)

    Example of Configuration file: 
    wrapper.logfile=../logs/wrapper-%WRAPPER_PID%.log

  • The WRAPPER_RAND_NNNNNN variable is set to a random number at each location it is used within the Wrapper configuration file. (Since ver. 3.3.4)

    Example of Configuration file: 
    wrapper.app.parameter.1=mytempfile-%WRAPPER_RAND_NNNNNN%.txt

    The value is set once when the configuration file is loaded and parsed. If the value should be set each time a JVM is launched, it is necessary to specify the wrapper.restart.reload_configuration=TRUE configuration property to cause the configuration to be reparsed prior to each JVM invocation.

    A different random number will be generated each place that the variable is specified. If it is necessary to reference the same random number in multiple locations, please first store the value into a local variable and then reference that as needed. For example:

    Example of Configuration file: 
    set.RNUM=%WRAPPER_RAND_NNNNNN%
wrapper.java.additional.1=-Dtempid=%RNUM%
wrapper.app.parameter.1=mytempfile-%RNUM%.txt

    Additional formats exist for 1 though 6 digit random numbers: WRAPPER_RAND_N, WRAPPER_RAND_NN, WRAPPER_RAND_NNN, WRAPPER_RAND_NNNN, and WRAPPER_RAND_NNNNN.

  • The WRAPPER_TIME_YYYYMMDDHHIISS variable is set to a timestamp at each location it is used within the Wrapper configuration file. The time returned is the time that the configuration file is loaded. The variable will return the same value when referenced multiple times in the same configuration file. (Since ver. 3.3.4)

    The following example demonstrates how to generate a timestamped file name and pass it to the JVM:

    Example of Configuration file: 
    wrapper.app.parameter.1=mytempfile-%WRAPPER_TIME_YYYYMMDDHHIISS%.txt

    The above example results in a value like:

    The result: 
    wrapper.app.parameter.1=mytempfile-20090409124532.txt

    The value is set once when the configuration file is loaded and parsed. If the value should be set each time a JVM is launched, it is necessary to specify the wrapper.restart.reload_configuration=TRUE configuration property to cause the configuration to be reparsed prior to each JVM invocation.

    The following additional formats can also be referenced: WRAPPER_TIME_YYYYMMDD_HHIISS, WRAPPER_TIME_YYYYMMDDHHII, WRAPPER_TIME_YYYYMMDDHH, and WRAPPER_TIME_YYYYMMDD.

  • The WRAPPER_WORKING_DIR variable is set to the location of the Wrapper binary on startup, but will be changed to reflect the current working directory of the Wrapper when referenced by child processes. (Since ver. 3.3.0)

    The working directory of the Wrapper can be changed using the wrapper.working.dir property. Be sure to read the documentation as its usage is a bit tricky.

    Please note however, that because of the way this property is set, it will always equal the WRAPPER_BIN_DIR variable when referenced in the Wrapper configuration file. The variable is set accurately within the environment however, and any child processes will see the directory which was set with the wrapper.working.dir property.

Event Handler Variable Definitions

In additional to the above environment variables, the following variables can also be referred in event properties when those events are fired. The variable values can be referenced by event properties as documented within those properties. The variables are not actually set as TRUE environment variables.

Copyright (c) 2004-2013, Tanuki Software, Ltd. All Rights Reserved.