Java Service Wrapper



Documentation


Users


Download


Get Involved


Hosted by:
SourceForge Logo

Configuration File Overview

Configuration File Overview


Configuring the Wrapper to Work With Your Application.

Example Wrapper Configuration File

Wrapper uses a configuration file to control how Java is launched.

The Wrapper config file contains the following information. This example assumes that the '@app.name@' and '@app.long.name@' tokens will be replaced with the name of your application on installation. Good values are 'testwrapper' for '@app.name@' and 'Test Wrapper Application' for '@app.long.name@'. A template wrapper.conf file can be found in the src/conf directory, named wrapper.conf.in.

#********************************************************************
# Wrapper parameters
#********************************************************************
# Java Application
wrapper.java.command=java

# Java Main class
wrapper.java.mainclass=com.silveregg.wrapper.test.Main

# Java Classpath (include wrapper.jar)  Add class path elements as
#  needed starting from 1
wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=../lib/wrappertest.jar

# Java Library Path (location of Wrapper.DLL or libwrapper.so)
wrapper.java.library.path.1=../lib

# Java Additional Parameters
#wrapper.java.additional.1=

# Initial Java Heap Size (in MB)
wrapper.java.initmemory=16

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=64

# Application parameters.  Add parameters as needed starting from 1
#wrapper.app.parameter.1=

# Port which the native wrapper code will attempt to connect to
wrapper.port=1777

#********************************************************************
# Wrapper Logging parameters
#********************************************************************
# Format of output for the console.  (See docs for formats)
wrapper.console.format=PM

# Log Level for console output.  (See docs for log levels)
wrapper.console.loglevel=INFO

# Log file to use for wrapper output logging.
wrapper.logfile=../logs/wrapper.log

# Format of output for the log file.  (See docs for formats)
wrapper.logfile.format=LPTM

# Log Level for log file output.  (See docs for log levels)
wrapper.logfile.loglevel=INFO

# Maximum size that the log file will be allowed to grow to before
#  the log is rolled. Size is specified in bytes.  The default value
#  of 0, disables log rolling.  May abbreviate with the 'k' (kb) or
#  'm' (mb) suffix.  For example: 10m = 10 megabytes.
wrapper.logfile.maxsize=0

# Maximum number of rolled log files which will be allowed before old
#  files are deleted.  The default value of 0 implies no limit.
wrapper.logfile.maxfiles=0

# Log Level for sys/event log output.  (See docs for log levels)
wrapper.syslog.loglevel=NONE

#********************************************************************
# Wrapper Unix daemon parameters
#********************************************************************
# File to write process ID to
wrapper.pidfile=/var/run/@app.name@.pid

#********************************************************************
# Wrapper NT Service parameters
#********************************************************************
# WARNING - Do not modify any of these parameters when an application
#  using this configuration file has been installed as a service.
#  Please uninstall the service before modifying this section.  The
#  service can then be reinstalled.

# Name of the service
wrapper.ntservice.name=@app.name@

# Display name of the service
wrapper.ntservice.displayname=@app.long.name@

# Description of the service
wrapper.ntservice.description=@app.description@

# Service dependencies.  Add dependencies as needed starting from 1
wrapper.ntservice.dependency.1=

# Mode in which the service is installed.  AUTO_START or DEMAND_START
wrapper.ntservice.starttype=AUTO_START

# Priority at which the service is run.  NORMAL, LOW, HIGH, or
#  REALTIME
wrapper.ntservice.process_priority=NORMAL

# Allow the service to interact with the desktop.
wrapper.ntservice.interactive=false

Additional properties, not found in the default configuration file above, are described below in the Advanced properties section.


Command Line Configuration

As of version 2.2.5, it is possible to specify Wrapper properties from the command line. This can be useful in situations where configuration values can only be set at runtime.

Configuration properties can be set on the command line by including them after the configuration file when launching Wrapper. Each property consists of a property name, followed by '=', followed by the property's value. The syntax is exactly the same as in the wrapper.conf file.

In this example, an application is being launched using a specific java application and debug logging enabled.

Windows NT/2000:

Wrapper.exe -c ..\conf\wrapper.conf wrapper.java.command=java wrapper.debug=true

Linux / Solaris:

./wrapper ../conf/wrapper.conf wrapper.java.command=java wrapper.debug=true

NOTE - Properties specified on the command line can not contain unquoted spaces. If you need to include spaces in the value of the property, simply include the entire name-value pair in quotes:

Example:

Wrapper.exe -c ..\conf\wrapper.conf "wrapper.java.command=C:\My App\jre\bin\java.exe"

This feature also works with the -i command on Windows systems when installing the application as a service.


Explanation of Wrapper Configuration File Properties

Note about paths

Java handles forward slashes, '/', and backslashes, '\', correctly on both Windows platforms. To make your wrapper.conf cross platform compatible, you should always use forward slashes in all paths in wrapper.conf.

Versions of the wrapper prior to 2.2.3 required that all paths in the wrapper.conf file be absolute. This is mainly to accommodate running the Wrapper as an NT service, but it also makes the application's startup much more reliable when launching the application from different locations.

In the Windows versions starting with 2.2.3, the Wrapper now sets its current working directory to the location of the wrapper executable. When the Wrapper launches Java, its working directory will remain the same making relative path references possible.

Linux and Solaris versions work correctly with relative paths if the current directory is always the same when the application is started. (i.e. You always start the application like ./myapp, as opposed to other locations like, bin/myapp)


Environment variable expansion

Starting with version 2.2.9, the Wrapper supports environment variable expansion at run time within the values of any of the properties listed on this page. To maintain the platform independent nature of the wrapper.conf file, the windows syntax is used for all platforms.

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.


Platform independent properties

wrapper.java.command

Location of the Java executable.

Example:

wrapper.java.command=java


wrapper.java.mainclass

Class to execute when the wrapper starts the application. If your application implements WrapperListener, then this will be that main class. Otherwise, this should be com.silveregg.wrapper.WrapperSimpleApp Then your main class will be listed as the first application parameter below.

Example (WrapperListener case):

wrapper.java.mainclass=com.widgetsrus.MyAppMain

Example (WrapperSimpleApp case):

wrapper.java.mainclass=com.silveregg.wrapper.WrapperSimpleApp


wrapper.java.classpath.<n>

Java Classpath to use. You should have a series of properties listing up the various class path elements to use when launching the application. Each element has a property name which starts with wrapper.java.classpath. and ends with an integer number counting up from 1. There can be no missing numbers.

This list must contain the wrapper.jar file. It can contain jar files as well as directories contains class files.

Example:

wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=../lib/myapp.jar
wrapper.java.classpath.3=../lib/mysql.jar
wrapper.java.classpath.4=../classes

As of version 2.2.5, classpath entries which contain wild cards can be used.

Example:

wrapper.java.classpath.1=../lib/*.jar
wrapper.java.classpath.2=../classes


wrapper.java.library.path.<n>

Java library path to use. You should have a series of properties listing up the various library path elements to use when launching the application. Each element has a property name which starts with wrapper.java.library.path. and ends with an integer number counting up from 1. There can be no missing numbers.

The library path is used to specify a list of directories in which to look for any native (JNI) libraries used by the application. You must place the Wrapper.DLL or libWrapper.so file in one of the directories specified.

Example:

wrapper.java.library.path.1=../lib


wrapper.java.additional.<n>

Additional Java parameters to pass to Java when it is launched. These are not parameters for your application, but rather parameters for the Java virtual machine. Each element has a property name which starts with wrapper.java.additional. and ends with an integer number counting up from 1. There can be no missing numbers.

For each entry, you can also have a corresponding strip quotes flag which will remove the quotes from the element when run on Linux or Solaris machines. This was necessary to allow for file references which contain spaces. For parameters like the one below it would not otherwise be possible to decide when to remove quotes and when to leave them alone.

Example:

wrapper.java.additional.1=-Xrs
wrapper.java.additional.2=-Dprop=TRUE
wrapper.java.additional.3=-Dmyapp.data="../data"
wrapper.java.additional.3.stripquotes=TRUE


wrapper.java.initmemory

The initial amount of memory in megabytes that the JVM should use. Some JVMs work more efficiently if this value is high rather than low.

Example:

wrapper.java.initmemory=16


wrapper.java.maxmemory

The maximum amount of memory in megabytes that the JVM will be allowed to use. Java is set to 64MB by default.

Example:

wrapper.java.maxmemory=64


wrapper.app.parameter.<n>

Application parameters to pass to your application when it is launched. These are the parameters passed to your application's main method. Each element has a property name which starts with wrapper.java.parameter. and ends with an integer number counting up from 1. There can be no missing numbers.

When the value of wrapper.java.mainclass is com.silveregg.wrapper.WrapperSimpleApp, the first parameter to the application must be the name of the class which contains your main method. All other parameters are then passed to your application's main method in order.

For each entry, you can also have a corresponding strip quotes flag which will remove the quotes from the element when run on Linux or Solaris machines. This was necessary to allow for file references which contain spaces. For parameters like the one below it would not otherwise be possible to decide when to remove quotes and when to leave them alone.

Example:

wrapper.java.mainclass=com.silveregg.wrapper.WrapperSimpleApp
wrapper.app.parameter.1=com.widgetsrus.MyAppMain
wrapper.app.parameter.2=-d
wrapper.app.parameter.3=-c"../conf/myapp.conf"
wrapper.app.parameter.3.stripquotes=TRUE
wrapper.app.parameter.4=-p4

Application parameters are designed to be individual parameters. If you specify a parameter like '-c conf/myconffile.conf', it will work correctly on windows because the '-c' and 'conf/myconffile.conf' parameters will be correctly parsed when Java is launched. But on Unix systems, the parameters will incorrectly be interpreted as a single parameter '-c conf/myconffile.conf'.

Incorrect:

wrapper.app.parameter.1=-c conf/myconffile.conf

Correct:

wrapper.app.parameter.1=-c
wrapper.app.parameter.2=conf/myconffile.conf


wrapper.port

A port used to communicate between the Wrapper executable and the Java application. Used to monitor the health of the Java application. This can be any value. If at runtime, the specified value is in use, then a warning will be printed to the console and the next available port will be used in its place.

When the Wrapper launches a JVM instance, it will open a server socket listening on this port bound to the localhost address. The launched JVM will be supplied with a key which it must use to be able to connect back to the Wrapper process. Once the JVM has connected, the Wrapper will no longer accept additional connections.

Example:

wrapper.port=1777



Logging properties

wrapper.console.format

Format to use for output to the console. Logging was intentionally kept simple. The format consists of the tokens 'L' for log level, 'P' for prefix, 'T' for time, and 'M' for message. If the format contains these values then it will be included in the format. The order of the tokens does not affect the way the log appears, but the M token should usually be placed last as it is the only column without a uniform width. If the property is missing or commented out, then the default value 'PM' will be used. Setting the property to a blank value will cause console output to be disabled.

Examples with sample output:

wrapper.console.format=PTM
wrapper  | 2001/12/11 13:45:33 | --> Wrapper Started as Console
wrapper  | 2001/12/11 13:45:33 | Launching a JVM...
jvm 1    | 2001/12/11 13:45:35 | Initializing...

wrapper.console.format=PM
wrapper  | --> Wrapper Started as Console
wrapper  | Launching a JVM...
jvm 1    | Initializing...

wrapper.console.format=M
--> Wrapper Started as Console
Launching a JVM...
Initializing...

wrapper.console.format=
< No output >


wrapper.console.loglevel

Log level to use for console output. Valid log levels include: NONE for no output, FATAL to only show fatal error messages, ERROR to show all error messages, STATUS to show all state changes, INFO shows all JVM output and informative messages, and DEBUG shows detailed debug information. The default value is INFO.

Example:

wrapper.console.loglevel=INFO


wrapper.logfile

Log file to which all output to the console will be logged. If the logfile is not specified, then file logging will be written to a file called "wrapper.log" in the same directory as the Wrapper executable. Providing a blank value will cause file logging to be disabled.

Example:

wrapper.logfile=../logs/wrapper.log


wrapper.logfile.format

Format to use for logging to the log file. Logging was intentionally kept simple. The format consists of the tokens 'L' for log level, 'P' for prefix, 'T' for time, and 'M' for message. If the format contains these values then it will be included in the format. The order of the tokens does not affect the way the log appears, but the M token should usually be placed last as it is the only column without a uniform width. If the property is missing or commented out, then the default value 'LPTM' will be used. Setting the property to a blank value will cause file logging to be disabled.

Examples with sample log entries:

wrapper.logfile.format=LPTM
STATUS | wrapper  | 2001/12/11 13:45:33 | --> Wrapper Started as Console
STATUS | wrapper  | 2001/12/11 13:45:33 | Launching a JVM...
INFO   | jvm 1    | 2001/12/11 13:45:35 | Initializing...

wrapper.logfile.format=PM
wrapper  | --> Wrapper Started as Console
wrapper  | Launching a JVM...
jvm 1    | Initializing...

wrapper.logfile.format=M
--> Wrapper Started as Console
Launching a JVM...
Initializing...

wrapper.logfile.format=
< No logging >


wrapper.logfile.loglevel

Log level to use for logging to the log file. Valid log levels include: NONE for no log output, FATAL to only log fatal error messages, ERROR to log all error messages, STATUS to log all state changes, INFO logs all JVM output and informative messages, and DEBUG logs detailed debug information. The default value is INFO.

Example:

wrapper.console.loglevel=INFO


wrapper.logfile.maxsize

The wrapper.log file can be set to roll when the file reaches a specified size. The default value of 0 will disable log file rolling. To roll the file, specify a maximum file size in bytes. The size can be abbreviated with the suffixes 'k' for kilobytes, or 'm' for megabytes. For example, '10m' sets the log file to be rolled when it reaches a size of 10 megabytes.

Example:

wrapper.logfile.maxsize=10m


wrapper.logfile.maxfiles

When log file rolling is enabled, old log files will be renamed with an integer suffix. Where larger indices are older log files. The maximum number of log files can be set using this property. The default value, 0, implies no limit on the number of files. If this number is reduced from say 10 to 5, the extra 5 files will not be deleted, new log files will only be rolled within the first 5 indices.

Example:

wrapper.logfile.maxfiles=10


wrapper.syslog.loglevel

Log level to use for logging to the Event Log on Windows systems, or the syslog on unix systems. Valid log levels include: NONE for no log output, FATAL to only log fatal error messages, ERROR to log all error messages, STATUS to log all state changes, INFO logs all JVM output and informative messages, and DEBUG logs detailed debug information. The default value is NONE. Be careful setting log which are too low. DEBUG for example will very quickly fill up your syslog.

Example:

wrapper.syslog.loglevel=NONE



Unix specific properties

wrapper.pidfile

File to write process ID to

Example:

wrapper.pidfile=/var/run/myapp.pid



Windows NT/2000 specific properties

NT Service Properties

WARNING - Do not modify any of these parameters when an application using this configuration file has been installed as a service. Please uninstall the service before modifying this section. The service can then be reinstalled.

wrapper.ntservice.name

Name of the NT service when installed

Example:

wrapper.ntservice.name=MyApp


wrapper.ntservice.displayname

Display name of the NT service when installed

Example:

wrapper.ntservice.displayname=My Application


wrapper.ntservice.description

Description of the NT service when installed. (Only used in Windows 2000 and XP, not in NT.)

Example:

wrapper.ntservice.description=Description of My Application


wrapper.ntservice.dependency.<n>

Names of any other Services which must be running before this service can be started. Stopping any of the listed services will also stop this service. Add dependencies as needed starting from 1.

Example:

wrapper.ntservice.dependency.1=MySQL


wrapper.ntservice.starttype

Mode in which the service is installed. AUTO_START starts the service automatically when the system is rebooted. Or DEMAND_START which requires that the service me started manually.

Example:

wrapper.ntservice.starttype=AUTO_START


wrapper.ntservice.process_priority

Specifies the priority at which the Wrapper and its JVM will be run at when run as an NT service or as a console application. Possible values are NORMAL, LOW, HIGH, and REALTIME. Defaults to NORMAL.

Example:

wrapper.ntservice.process_priority=NORMAL

From the Windows API, each priority level is described as follows:

NORMAL

Specify this class for a process with no special scheduling needs.


LOW

Specify this class for a process whose threads run only when the system is idle. The threads of the process are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle-priority class is inherited by child processes.


HIGH

Specify this class for a process that performs time-critical tasks that must be executed immediately. The threads of the process preempt the threads of normal or idle priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class application can use nearly all available CPU time.


REALTIME

Specify this class for a process that has the highest possible priority. The threads of the process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.



wrapper.ntservice.account

The account to use when running the service. Use an account name in the form: {DomainName}\{UserName}. If the account belongs to the built-in domain, then you may specify the name if the form: .\{UserName}. The default, blank value, will use the LocalSystem account.

Example:

wrapper.ntservice.account=.\leif

When attempting to install the service, you will encounter the following message if the account name is invalid, does not exist, or the password for the account is incorrect. A common mistake is setting the account name to leif rather than .\leif.

CreateService failed - The account name is invalid or does not exist,
or the password is invalid for the account name specified. (0x421)

Only accounts which have their "Logon as Service" right set can be used to run a service. Failure to set this right will result in the following error message when you attempt to actually start the service:

System error 1069 has occurred.

The service did not start due to a logon failure.

To set the "Logon as Service" right; Go to the Administrative Tools folder in your control panel. Open the Local Security Policy applet. Expand Local Policy and then click on User Rights Assignment. On the right side there is a logon as service policy. Open that and then add the user that you wish to allow to run the service.

Note that the Local Security Policy applet only appears to be available on Professional versions of Windows NT, 2000 and XP. Home versions do not seem to allow you to setup users with the "Logon as Service" right.


wrapper.ntservice.password

The password of the account specified in wrapper.ntservice.account. If the account does not have a password, or if the LocalSystem account is being used, then this value can be blank. The default is no password.

Example:

wrapper.ntservice.password=secret


wrapper.ntservice.interactive

Setting the interactive property to true will make it possible for the service to display a GUI and have access to the desktop when run as a service. The default is false, or a non-interactive service.

Example:

wrapper.ntservice.interactive=false



Advanced properties

This section covers the advanced properties which can be used to further configure the Wrapper. These properties are not found in the default wrapper.conf file distributed with the Wrapper. However they can be added as needed. The default values of these properties have been designed to work with the majority of applications. In most cases, they should not be changed.

There are cases where they may need to be changed to suit the needs of a particular application. When doing so however, please take the time to read the documentation of the property carefully and make sure that changing it is really what you want to do.

WARNING - Do not modify any of these parameters unless you have read the description of the property below. Incorrect settings can cause the Wrapper to fail to operate as expected.

wrapper.restart.delay

Controls the number of seconds to pause between a JVM exiting for any reason, and a new JVM being launched. Defaults to 5 seconds.

Setting this restart delay to a very low value or even 0 could cause problems as the new JVM could may be launched before all resources from the previous invocation have been reclaimed from the operating system.

Example:

wrapper.restart.delay=5


wrapper.startup.timeout

Number of seconds to allow between the time that the Wrapper launches the JVM process and the time that the JVM side of the Wrapper responds that the application has started. 0 means never time out. Defaults to 30 seconds.

If you are experiencing timeout problems as your application is starting up. The most common cause is a misconfiguration. Please verify that the WrapperManager is indeed being started. You should see the following output in the console when you launch the Wrapper.

wrapper  | --> Wrapper Started as Console
wrapper  | Launching a JVM...
jvm 1    | Wrapper (Version 2.x.x)

If you do not see the Wrapper version displayed, then the WrapperManager is not being launched. Please make sure that you have read over the API Overview section. If the configuration looks correct, then try enabling DEBUG level log output to try and narrow in on the problem.

If the Wrapper version is being displayed, but the Wrapper is still timing out on startup, then it is most likely being caused by one of two things. The first is that the start method call is not returning. This should not be an issue if you are using the SimpleWrapperApp class to launch your application. If you are implementing the WrapperListener however. Please verify that the start method is indeed returning upon completion. You should be able to see this with DEBUG output enabled.

The other possibility is that the startup method is simply taking a while to complete. In this case, it may be necessary to extend the default startup timeout. Try setting to to 300 (5 minutes) and see if that makes the problem go away.

It is best to choose a value which is long enough to let the application start reliably, but short enough that the Wrapper will react as quickly as possible in the event of an actual JVM hang.

If the start procedure sometimes takes a long time. One alternative to setting a long timeout is to periodically call the WrapperManager.signalStarting(n) method. This method gives the application the ability to request more time to startup, while at the same time assuring the Wrapper that the JVM is alive and well.

Example:

wrapper.startup.timeout=30

WARNING - While the ability is there. Be aware that setting this property to 0 or some large value will mean that the Wrapper's ability to detect a JVM hang during the startup phase will be disabled.


wrapper.ping.timeout

Number of seconds to allow between the wrapper pinging the JVM and the response. 0 means never time out. Defaults to 30 seconds.

In normal operation, the Wrapper pings the JVM once every 5 seconds to make sure that its process has not frozen up. The ping timeout is the amount of time to allow for a response from the JVM before the Wrapper assumes that it is hung and restarts it.

With the addition of the wrapper.cpu.timeout property, there is now almost no reason why you should ever need to change this property. The only reasons why you should be getting ping timeouts are if the system is under heavy load or if the JVM is really hung. The CPU timeout should now detect any problems in with CPU.

Example:

wrapper.ping.timeout=30

WARNING - While the ability is there. Be aware that setting this property to 0 or some large value will mean that the Wrapper's ability to detect a JVM hang as it is running will be disabled.


wrapper.shutdown.timeout

Number of seconds to allow between the time that the Wrapper asks the JVM to shutdown and the time that the JVM side of the Wrapper responds that it is stopping. 0 means never time out. Defaults to 30 seconds.

If you are experiencing timeout problems as your application is shutting down, you may want to consider extending this timeout. This can happen in cases where the shutdown code within the application takes a long time to complete. As a test, try setting this property to something like 300 (5 minutes) and see if this makes the problem go away.

If the application still times out quicker than the 5 minute test timeout, then the problem may be in a later phase of shutdown. Take a look at the wrapper.jvm_exit.timeout property below.

If the application still times out after waiting the full 5 minutes then you will have to do some debugging of your application to see what is taking so long. If it is possible to speed up the application's shutdown phase, that would be best. Otherwise set the timeout to a value that allows the application to shutdown cleanly.

It is best to choose a value which is long enough to let the application run reliably, but short enough that the Wrapper will react as quickly as possible in the event of an actual JVM hang.

If the shutdown procedure sometimes takes a long time. One alternative to setting a long timeout is to periodically call the WrapperManager.signalStopping(n) method. This method gives the application the ability to request more time to shutdown, while at the same time assuring the Wrapper that the JVM is alive and well.

Example:

wrapper.shutdown.timeout=30

WARNING - While the ability is there. Be aware that setting this property to 0 or some large value will mean that the Wrapper's ability to detect a JVM hang during the shutdown phase will be disabled.


wrapper.jvm_exit.timeout

Number of seconds to allow between the time that the JVM reports that it is stopped and the time that the JVM process actually terminates. 0 means never time out. Defaults to 5 seconds.

In normal operation, the Java side of the Wrapper will execute System.exit when it has completed its JVM shutdown cycle and is ready to exit. When this timeout is triggered, a message like the following will be logged.

wrapper  | Shutdown failed: Timed out waiting for the JVM to terminate.
wrapper  | Java Virtual Machine did not exit on request, terminated

If the application has registered its own shutdown hook which takes some time to complete, you could experience timeouts waiting for the JVM process to terminate. To avoind this problem, it may be necessary to extend the timeout to give the application's shutdown hook time to execute to completion. Be aware that as a rule, shutdown hooks should always complete almost instantly.

Example:

wrapper.jvm_exit.timeout=5

WARNING - While the ability is there. Be aware that setting this property to 0 or some large value will mean that the Wrapper's ability to detect a JVM hang as the JVM process terminates will be disabled.


wrapper.cpu.timeout

Number of seconds without CPU before the JVM will issue a warning and extend timeouts. In order for this property to have any effect, it must have a value less than the other timeouts (wrapper.startup.timeout, wrapper.ping.timeout, and wrapper.shutdown.timeout). 0 means never extend time outs. Defaults to 10 seconds.

If the Wrapper detects that it was denied CPU for an extended period of time, you may see messages like the following from the Wrapper, the JVM, or both.

INFO   | wrapper  | Wrapper Process has not received any CPU time for 27 seconds.
                    Extending timeouts.
INFO   | jvm 1    | JVM Process has not received any CPU time for 27 seconds.
                    Extending timeouts.

These messages are warnings that, in this case, both the Wrapper and its JVM process were denied access to the CPU for a period of 27 seconds. Depending on the current state of the wrapper, either the startup, ping, or shutdown timeout is extended to avoid a false timeout caused by the lack of processing power.

There are two cases where either the Wrapper or its controlled JVM could be denied access to the CPU for an extended period of time. Either could lead to the Wrapper thinking that the JVM was hung, causing it to be restarted or shutdown because one or more of the timeouts expired.

The first way that this can happen is when the Wrapper is competing for system resources with another process which has the habit of consuming 100% of the CPU for extended periods of time without yielding to other processes. Most modern operating systems are fairly good about managing multitasking. But there are still cases where it can fail. One example of this on NT, is when the machine is very low on memory leading to lots of disk swapping. If the total memory is large enough the entire system can freeze up for as long as a minute before any applications are again given any CPU cycles.

In most cases, when you are having problems with CPU timeouts, you should really look at finding a way to resolve the problem of the Wrapper not getting any CPU rather than extending any timeouts. If the application being run by the Wrapper is not getting any CPU then it will not be able to reliably service requests from clients.

A second way is if the system is suspended and then resumed. This is a common thing to do on notebooks. When the system comes back up, the system will appear to have suddenly been set ahead by potentially several hours.

By default, warning messages will be displayed after 10 seconds, which is actually quite a while. The CPU timeout being triggered will not have any adverse effects on an application other than the message being displayed in the logs. To avoid this message being logged the timeout can be set to a larger value, or disabled completely.

Example:

wrapper.cpu.timeout=10

WARNING - While the ability is there. Be aware that setting this property to 0 or a value larger than another timeout could cause that timeout to be falsely triggered in cases of heavy load. This can lead to the JVM being restarted when a restart is not really necessary.


wrapper.max_failed_invocations

Maximum number of times that the Wrapper will attempt to restart the JVM if each attempted invocation exits abnormally shortly after having being launched. Must be at least 1. Defaults to 5 invocations.

If there are mistakes in the configuration of an application then the JVM could exit with a ClassNotFoundException or something. This will be interpreted as the JVM having exited abnormally, leading to a JVM restart. Obviously, this would lead to an infinite loop of JVM restarts. To resolve this problem, this property sets the maximum number of times that the JVM will be restarted.

If the JVM was running for longer than wrapper.successful_invocation_time seconds, then the restart count will be reset to 0. So this count only applies to JVM invocations which fail on startup.

In general, this property should be set to a time longer than the wrapper.startup.timeout as it is designed to count failures on startup.

In most cases, a value of 1 would be acceptable. But there are cases where some resources may not immediately be available. For example. On Solaris systems. A server socket may remain bound for up to 2 minutes after the process which previously had it bound was terminated. This can lead to cases where a server will start normally. Then at some later date, when the JVM is restarted for some other reason, getting a BindException when the new JVM invocation tries to startup. Setting the value to 5 makes it less likely that the JVM will not be able to restart successfully after a few failures.

Note that the restart count is reset if a Java application requests a restart using the WrapperManager.restart() method.

Example:

wrapper.max_failed_invocations=5


wrapper.successful_invocation_time

Specifies the amount of time that an application must remain running before it will be considered to have been a successful invocation. This property's use is described above in the description of wrapper.max_failed_invocations. Defaults to 300 seconds.

Example:

wrapper.successful_invocation_time=300

WARNING - If the specified time is too short then all invocations may be viewed as having been successful. This can lead to a case where the JVM is restarted infinitely as described above.


wrapper.disable_shutdown_hook

Disable detection of calls to System.exit(). If disabled, calls to System.exit() will be treated as if the JVM had crashed and the Service will be restarted.

The Wrapper registers a shutdown hook by default. If an application ever calls System.exit() rather than calling WrapperManager.stop() to stop the service, then the Wrapper will correctly shutdown the server.

You may wish to disable the shutdown hook for a number of reasons, including security.

Example:

wrapper.disable_shutdown_hook=TRUE

WARNING - When the Wrapper detects that System.exit() has been called, it will call the stop() method on your application if it implements the WrapperListener method. You must be careful that your application does not call System.exit() again or call the dispose() method on an AWT frame or window. Either one of these actions will result in a deadlock when called from within a ShutdownHook thread due to the way Java has implemented these methods. If either of these cases can not be avoided, then the shutdown hook should be disabled.

If you have control over whether the System.exit() or dispose() methods are called, you may be able to make use of the WrapperManager.hasShutdownHookBeenTriggered() method to avoid the deadlock issue.

For more information on the AWT deadlock bug, see the full description of bug #4712342 on Sun's site.


wrapper.request_thread_dump_on_failed_jvm_exit

Enabling this property will tell the Wrapper to attempt to request a Thread Dump in the event that the JVM does not exit when requested. This information can be useful in tracking down the reason why the JVM is not exiting. This will have no effect if the JVM is hung for some reason as it process will not respond to the thread dump request. Defaults to FALSE.

Example:

wrapper.request_thread_dump_on_failed_jvm_exit=TRUE





Copyright ©2000-2001 by Silver Egg Technology Co., Ltd. All Rights Reserved. last modified: