 |
Documentation
Users
Download
Get Involved
Hosted by:
|  |  |  |
Examples
Running the TestWrapper example application |
Running in a Console |
Once you install the binary version of the Wrapper distribution, or have run build
on a source distribution, you will be ready to immediately run the example
application.
The TestWrapper example application is also used to test many of the recovery
features of the Java Service Wrapper.
To run the example, cd into your bin directory and run the following script:
Windows:
Linux / Solaris:
The Solaris testwrapper script tries
to write a PID file to /var/run. If
you aren't logged in as root, this will fail. You can fix this by simply
changing the PIDDIR variable in the
script, or by logging in as root. If you log in as root, make sure that
you have permission to use the X server or else you won't be able to see
the testwrapper GUI.
|
The Windows console can be stopped cleanly by hitting CTRL-C, but the Linux and
Solaris version require you to run the script with the stop parameter:
Linux / Solaris:
The Linux and Solaris versions also provide the ability to restart the application:
Linux / Solaris:
When the application starts, you should see the following dialog:
You should also see the following in the console:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
|
Let's start with the console output. The first column of data displays the source
of the output. Lines starting with wrapper are
coming from the native Wrapper application. Lines starting with
jvm 1 are coming from the output of the JVM.
The number after jvm indicates the JVM number
since the wrapper was started. We will see how that works when we start playing
with the TestWrapper's dialog.
The console output is also all logged to
logs/wrapper.log. The logged output differs
from the console output in that each line of output also includes a timestamp.
wrapper | 2001/12/06 16:18:27 | --> Wrapper Started as Console
wrapper | 2001/12/06 16:18:28 | Launching a JVM...
jvm 1 | 2001/12/06 16:18:29 | Initializing...
jvm 1 | 2001/12/06 16:18:30 | Wrapper (Version 2.x.x)
jvm 1 | 2001/12/06 16:18:30 |
jvm 1 | 2001/12/06 16:18:30 | start()
|
The TestWrapper presents you with a number of buttons. These are each used to test
various functionality of thw Wrapper. Each button is described below with the
output you will see in the console if the button is activated.
-
Exit
-
Exits the JVM cleanly by calling WrapperManager.stop(0).
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
jvm 1 | stop(0)
wrapper | <-- Wrapper Stopped
|
As you can see, the application had its stop() method called and
was stopped cleanly.
-
Access Violation
-
This takes advantage of a bug in the Sun JVM to cause an immediate
access violation in the JVM. (It doesn't work in the IBM JVM. Or
I guess you could say it does work...).
Console Output (SUN JVM):
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
jvm 1 | WARNING: Attempting to cause an access violation...
jvm 1 | #
jvm 1 | # HotSpot Virtual Machine Error, EXCEPTION_ACCESS_VIOLATION
jvm 1 | # Please report this error at
jvm 1 | # http://java.sun.com/cgi-bin/bugreport.cgi
jvm 1 | #
jvm 1 | # Error ID: 4F533F57494E13120E43505002D4
jvm 1 | #
jvm 1 |
jvm 1 | abnormal program termination
wrapper | JVM exited unexpectedly.
wrapper | Launching a JVM...
jvm 2 | Initializing...
jvm 2 | Wrapper (Version 2.x.x)
jvm 2 |
jvm 2 | start()
|
As you can see, an access violation caused the JVM to display an
error dump and then terminate. The wrapper immediately detects
this and after a 5 second pause, restarts the application in a new
JVM, as can be seen with the
jvm 2. All available
information about the crash has been logged for future reference.
-
Native Access Violation
-
The Wrapper includes a lightweight native library which is used to
handle system events. The library also contains a native method
which is used for testing to cause an access violation in native
code due to a NULL reference. This may take a few moments for the
application to restart as the system may save a coredump. This can
result in the Wrapper thinking that the application has become hung,
as can be seen in this output.
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
jvm 1 | WARNING: Attempting to cause an access violation...
jvm 1 | #
jvm 1 | # An EXCEPTION_ACCESS_VIOLATION exception has been detected in native code outside the VM.
jvm 1 | # Program counter=0x8f7105f
jvm 1 | #
wrapper | JVM is hung: Timed out waiting for signal from JVM.
wrapper | Java Virtual Machine did not exit on request, terminated
wrapper | Launching a JVM...
jvm 2 | Initializing...
jvm 2 | Wrapper (Version 2.x.x)
jvm 2 |
jvm 2 | start()
|
As you can see, an access violation caused the JVM to display an
error dump. Dumping the core took a minute or so and the wrapper
is configured to assume that the JVM is hung after it has lost
contact for more than 30 seconds. Either way, the wrapper detected
the problem and restarted a fresh JVM.
-
Simulate JVM Hang
-
This test causes the Wrapper to think that the JVM has become hung.
After 30 seconds, the Wrapper times out and decides that the JVM
will not come back and restarts it.
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
jvm 1 | WARNING: Attempting to cause an access violation...
wrapper | JVM is hung: Timed out waiting for signal from JVM.
wrapper | Java Virtual Machine did not exit on request, terminated
wrapper | Launching a JVM...
jvm 2 | Initializing...
jvm 2 | Wrapper (Version 2.x.x)
jvm 2 |
jvm 2 | start()
|
-
System.exit(0)
-
This button tests the Wrapper's ability to trap an unexpected call
to System.exit() and stop the application gracefully.
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
jvm 1 | stop(0)
jvm 1 | here
wrapper | <-- Wrapper Stopped
|
As an exercise, edit your conf/wrapper.conf
file and uncomment the property,
wrapper.disable_shutdown_hook=TRUE.
(Make sure to comment it back out when you are done) Now rerun the
test.
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
wrapper | JVM exited unexpectedly.
wrapper | Launching a JVM...
jvm 2 | Initializing...
jvm 2 | Wrapper (Version 2.x.x)
jvm 2 |
jvm 2 | start()
|
You will notice that the Wrapper no longer catches the call to
System.exit() and so the it thinks that the JVM crashed and
restarts it.
-
Runtime.getRuntime().halt(0)
-
This button calls a very lowlevel method to stop the JVM very
forcibly. In this case, Shutdown Hooks are not executed and the
Wrapper has no way to catch it.
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
wrapper | JVM exited unexpectedly.
wrapper | Launching a JVM...
jvm 2 | Initializing...
jvm 2 | Wrapper (Version 2.x.x)
jvm 2 |
jvm 2 | start()
|
You will notice that the Wrapper thinks that the JVM crashed and
restarts it.
-
Request Restart
-
Restarts the JVM cleanly by calling WrapperManager.restart()
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
wrapper | JVM requested a restart.
jvm 1 | stop(0)
wrapper | Launching a JVM...
jvm 2 | Initializing...
jvm 2 | Wrapper (Version 2.x.x)
jvm 2 |
jvm 2 | start()
|
As you can see, the application had its stop() method called and
was restarted cleanly.
This covers all of the ways that your application can exit or die of its own will.
There are two other external factors that the Wrapper can also protect against.
-
CTRL-C
-
Most Java applications die rather abruptly if the user hits CTRL-C,
logs out of windows, etc. You can work around some of these issues
with a Shutdown Hook, but the Wrapper implements this by using a
native library to directly capture the system signals. This makes
it possible to have a Java application installed as an NT Service
without it being stopped when a user logs out.
As a test, try hitting CTRL-C in the console window.
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
wrapper | CTRL-C trapped. Shutting down.
jvm 1 | stop(0)
wrapper | <-- Wrapper Stopped
|
You can also see variations on this by logging out when the console
application is still running. The Wrapper will correctly terminate
the application.
Console Output:
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
wrapper | User logged out. Shutting down.
jvm 1 | stop(0)
wrapper | <-- Wrapper Stopped
|
On Linux or Solaris platforms, you can not hit CTRL-C because the
Wrapper is launched as a spawned process. Running the script with
the stop parameter will produce the following results:
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
wrapper | Shutting down.
jvm 1 | stop(0)
wrapper | <-- Wrapper Stopped
|
-
Process Termination
-
It is also possible, though unlikely, that the application process
could be killed by another application. This test also simulates
cases where the JVM dies very suddenly of its own accord. On Unix
systems, you can kill the java process with a
kill -9. On Windows systems,
open up the Task Manager. Select the Process tab. Locate the
java.exe process to kill and then kill it.
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
wrapper | JVM exited unexpectedly.
wrapper | Launching a JVM...
jvm 2 | Initializing...
jvm 2 | Wrapper (Version 2.x.x)
jvm 2 |
jvm 2 | start()
|
Restarts without any problems.
-
System Under High Load or System Suspend
-
There are cases where either the Wrapper, the JVM or both will be
denied CPU cycles for an extended period of time. This can happen
if a resource unfriendly process starts taking 100% of the CPU for
a period of time. It is also possible if the user Suspends the
system to RAM or disk. When the system is resumed, all running
applications will have experienced some missing time. The Wrapper
is capable of recognizing that this has happened making it possible
to avoid unneeded restarts of the JVM process. The following output
shows what happens when the System is suspended to RAM for 255
seconds before being resumed.
Console Output:
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1 | Initializing...
jvm 1 | Wrapper (Version 2.x.x)
jvm 1 |
jvm 1 | start()
jvm 1 | JVM Process has not received any CPU time for 255 seconds. Extending timeouts.
wrapper | Wrapper Process has not received any CPU time for 255 seconds. Extending timeouts.
|
|
Running as an NT Service |
When running as an NT service, the TestWrapper will be unable to show its Dialog.
So this application is not very interresting. We can however do a few tests to
verify that the Wrapper acts as an NT service correctly.
The first thing you will need to do is get the TestWrapper installed as a service
by running the following command:
InstallTestWrapper-NT.bat
|
You will see the output:
wrapper | Test Wrapper Application installed.
|
Once the TestWrapper application in installed as a service, we will want to start
it.
You will see the output:
The Test Wrapper Application service is starting.
The Test Wrapper Application service was started successfully.
|
The service can be uninstalled by executing the following command:
UninstallTestWrapper-NT.bat
|
If the service is running, you will see the output:
wrapper | Service is running. Stopping it...
wrapper | Waiting to stop...
wrapper | Test Wrapper Application stopped.
wrapper | Test Wrapper Application removed.
|
If you look at the contents of logs/wrapper.log,
you will see output very simmilar to that of the console. Except this time, the
start message informs you that the application is being started as a Service.
wrapper.log
wrapper | 2001/12/06 17:34:21 | --> Wrapper Started as Service
wrapper | 2001/12/06 17:34:21 | Launching a JVM...
jvm 1 | 2001/12/06 17:34:22 | Initializing...
jvm 1 | 2001/12/06 17:34:22 | Wrapper (Version 2.x.x)
jvm 1 | 2001/12/06 17:34:22 |
jvm 1 | 2001/12/06 17:34:22 | start()
|
Here are the results of several more actions that can take place on an NT service:
-
User Logging out and then back in
-
A log entry is made when the user logs out, but the service is
unaffected.
wrapper.log
wrapper | 2001/12/06 17:39:39 | --> Wrapper Started as Service
wrapper | 2001/12/06 17:39:40 | Launching a JVM...
jvm 1 | 2001/12/06 17:39:40 | Initializing...
jvm 1 | 2001/12/06 17:39:40 | Wrapper (Version 2.x.x)
jvm 1 | 2001/12/06 17:39:40 |
jvm 1 | 2001/12/06 17:39:41 | start()
wrapper | 2001/12/06 17:40:07 | User logged out. Ignored.
jvm 1 | 2001/12/06 17:40:07 | controlEvent(202)
|
-
Restarting your machine. This will result in a logout signal
followed by a shut down signal. The service will be shut down
gracefully and then come back after the machine restarts.
-
A log entry is made when the user logs out, but the service is
unaffected.
wrapper.log
wrapper | 2001/12/06 17:41:04 | --> Wrapper Started as Service
wrapper | 2001/12/06 17:41:05 | Launching a JVM...
jvm 1 | 2001/12/06 17:41:05 | Initializing...
jvm 1 | 2001/12/06 17:41:05 | Wrapper (Version 2.x.x)
jvm 1 | 2001/12/06 17:41:05 |
jvm 1 | 2001/12/06 17:41:05 | start()
wrapper | 2001/12/06 17:41:25 | User logged out. Ignored.
jvm 1 | 2001/12/06 17:41:26 | controlEvent(202)
wrapper | 2001/12/06 17:41:27 | Machine is shutting down.
jvm 1 | 2001/12/06 17:41:27 | controlEvent(203)
jvm 1 | 2001/12/06 17:41:28 | stop(0)
wrapper | 2001/12/06 17:41:29 | <-- Wrapper Stopped
wrapper | 2001/12/06 17:44:12 | --> Wrapper Started as Service
wrapper | 2001/12/06 17:44:12 | Launching a JVM...
jvm 1 | 2001/12/06 17:44:17 | Initializing...
jvm 1 | 2001/12/06 17:44:21 | Wrapper (Version 2.x.x)
jvm 1 | 2001/12/06 17:44:21 |
jvm 1 | 2001/12/06 17:44:23 | start()
|
|
Running as a Linux / Solaris Service |
There are not any differences between running as a service vs as a console
application in a Unix environment.
|
|
|  |