How to integrate your application with the Java Service Wrapper

There are currently four ways to integrate your Java application with the Java Service Wrapper. Three of them will work out of the box without any additional coding.

The first step is to decide which of these four methods is best for your application. After a brief overview of each of the four options, we will go into detail on how to integrate an application using each method.

Integration Method 1 (WrapperSimpleApp)

Method 1 uses 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.

Details

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 shuts down 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 shut down cleanly. If, on the other hand, a shutdown hook is not registered, then the application will suddenly exit as when pressing CTRL-C in the console (command window). Both cases, with and without a Shutdown Hook, provide the exact same behavior as if the application was running without the Wrapper.

You can find a detailed overview and instructions using a simple HelloWorld application examples for Windows or Linux/UNIX.

Integration Method 2 (WrapperStartStopApp)

Method 2 uses 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.

Details

Typically, this kind of application will open a server socket on startup whose job is to wait for a connection that triggers a shutdown. The stop class, when launched, triggers the shutdown by connecting to the application.

The Wrapper works with this kind of application by starting up the application as in Method 1, using the start class and then calling the main method of the stop class when it is time for the application to be shut down.

You can find a detailed overview and instructions using Tomcat as an example for Windows or Linux/UNIX.

Integration Method 3 (WrapperListener)

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

Details

While this method provides features that are not available with either of the first two methods (either WrapperSimpleApp or WrapperStartStopApp), it does add some complexity. This is the only method that allows user code to receive and respond directly to system control events as well as the startup and shutdown process.

If the additional features are not required, implementing a Shutdown Hook to enable the use of Method 1 (WrapperSimpleApp), 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.

However, in most cases this added control is not necessary, as both Method 1 (WrapperSimpleApp) and Method 2 (WrapperStartStopApp) helper classes take care of this for you by starting up and shutting down the application at the appropriate times.

You can find a detailed overview and instructions on the Platform Independent page.

Integration Method 4 (WrapperJarApp)

The fourth and final method uses the WrapperJarApp helper class to launch the application. This is another simple way to integrate with the Wrapper when the application is already configured to run as an executable jar.

Details

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 shuts down 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, as when pressing CTRL-C in the console (command window). Both cases, with and without a Shutdown Hook, provide the exact same behavior as if the application was running without the Wrapper.

You can find a detailed overview and instructions using JBoss EAP as an example for Windows or Linux/UNIX.

Reference: Launching your application with the Wrapper

[Windows]

[Linux / Unix]

[Common]