Hosted by:
SourceForge
Get Firefox!

Integration Methods
Integration Methods
Methods of Integrating with the Java Service Wrapper

There are currently three ways which an application can integrate with the Java Service Wrapper. Two of which will work out of the box without any additional coding. The first step is to decide which of these three methods is best for your application. After a brief overview of each of the three options, we will go into detail how to integrate an application using each.

Method 1

The first method is to use the WrapperSimpleApp helper class to launch the application. This is by far the simplest way to integrate with the Wrapper, and where possible, it is highly recommended. There are some things to be aware of when using this method however. When the Wrapper shuts down the JVM, there is no direct call to an application requesting that it shutdown cleanly. Rather, the Wrapper will exit the JVM by calling System.exit() from within the JVM. If the application has registered its own shutdown hook, it will be invoked, giving the application a chance to shutdown cleanly. If on the other hand, a shutdown hook is not registered, then the application will suddenly exit. Both cases, with and without a shutdown hook, provide the exact same behavior as if the application was running without the Wrapper and a user pressed CTRL-C in the console.

Detailed overview and instructions, using JBoss as an example. (Win32 or Linux / UNIX).

Method 2

The second method is to use the WrapperStartStopApp helper class. This method provides a way to integrate with applications like Tomcat, which are started using one class and then stopped using another class. Typically, this kind of application will open a server socket on startup whose job is to wait for a connection which triggers a shutdown. The shutdown, or "stop", class when launched then triggers the shutdown by connecting to application. The Wrapper works with this kind of application by starting up the application, as in the first method, using the "start" class and then calling the main method of the "stop" class when it is time for the application to be shutdown.

Detailed overview and instructions, using Tomcat as an example. (Win32 or Linux / UNIX).

Method 3

The third and final method, while providing the most flexibility and access to all of the Wrapper's features, is also the only one which requires some coding to complete the integration. This method involves creating a class which implements the WrapperListener interface. An instance of the user class is then instantiated and registered with the WrapperManager.

While this method provides features that are not available with either of the first two methods, it does add some complexity. If the additional features are not required, implementing a shutdown hook to enable the use of Method 1, or implementing a shutdown class should be considered as options. The main method of a shutdown class can be as simple as just calling a shutdown method in the application.

This is the only method which allows user code to receive and respond directly to system control events as well as the startup and shutdown process. In most cases this added control is not necessary however, as both the WrapperSimpleApp and WrapperStartStopApp helper classes take care of this for you by starting up and shutting down the application at the appropriate times.

Detailed overview and instructions (Platform Independent).

NOTE

The Wrapper can be used with 1.2.x versions however some functions are disabled due to this version of Java's lack of support for shutdown hooks. Shutdown hooks were implemented with the 1.3.0 release of Java.

Integration method #1 can be used, but the application will not be shutdown cleanly. This method normally relies on an application's own shutdown hook to handle any work that needs to be done before the JVM shuts down. To guarantee a clean shutdown of the application, Methods #2 or #3, which both directly allow code to be executed on shutdown must be used.

by Leif Mortenson

last modified: