 |
Documentation
Users
Download
Get Involved
Hosted by:
|  |  |  |
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:
|
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.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:
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:
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
|
|
|
|
|  |