On Windows systems, Java applications are run in a command prompt. This requires a user account to be logged on to the system at all times, and a command prompt to be open and running on the desktop.

There are several drawbacks to this ranging from security, to system performance, to simply having the risk of a user pressing the wrong key on the command prompt and killing the Java application.

Java App Server

What is a Service?

Windows has the ability to run applications in the background as a Service to solve these problems. Services are launched on system startup and do not require that a user be logged in. This greatly increases security and overall stability of the system because it is not possible for a user to stop, start, or otherwise tamper with them unless they are an administrator.

The problem is that Java on its own can not be run as a service. Many simple tools like the Windows sc command can be used to run Java as a service, but the user doing something as simple as logging off of the machine will cause Java to shutdown.

The Java Service Wrapper not only makes it possible, but makes it easy to run any Java application as a Windows Service. It also adds advanced failover, error recovery, and analysis features to make sure that your application has the maximum possible uptime.

Simple HelloWorldServer Java Class

For this example, we will be making use of a simple HelloWorldServer application that will let us run in the background and connect from a client using telnet. Please take a look at the full overview of the application to learn how to create and build the HelloWorldServer application for this example.

Unless you want to actually run the example, it will suffice to say that it can be run using the following Java command line.

Run the example:
java -classpath lib\classes HelloWorldServer

Wrapping the HelloWorldServer class

The first step in turning our HelloWorldServer class into a service is configuring the Java Service Wrapper to run our application. For the majority of applications this can be done without writing any Java code.

Directory structure

The Wrapper is very flexible and can be set up to work with any directory structure. For this example, we suggest a directory structure which is clean and can be reused even for fairly complicated applications. Please recreate the following directory structure under an arbitrary directory of your choice. We will call this root directory %EXAMPLE_HOME%. This is an extension of the directory structure described in the HelloWorldServer overview.

Directory structure:
%EXAMPLE_HOME%\
%EXAMPLE_HOME%\bin\
%EXAMPLE_HOME%\conf\
%EXAMPLE_HOME%\lang\
%EXAMPLE_HOME%\lib\
%EXAMPLE_HOME%\lib\classes\
%EXAMPLE_HOME%\logs\

Get the Java Service Wrapper

Please download the latest version of the Java Service Wrapper for your OS from the Download page, and extract it into a directory of your choice. We will call the extracted directory %WRAPPER_HOME%.

Copy Wrapper files

The Java Service Wrapper consists of three primary components. The Wrapper binary, a jar file, and a native library which is used by the jar file. Please copy these three files as follows:

Copy files:
%WRAPPER_HOME%\bin\wrapper.exe -> %EXAMPLE_HOME%\bin\wrapper.exe
%WRAPPER_HOME%\lib\wrapper.jar -> %EXAMPLE_HOME%\lib\wrapper.jar
%WRAPPER_HOME%\lib\wrapper.dll -> %EXAMPLE_HOME%\lib\wrapper.dll

The Wrapper can be controlled directly or using batch files. These files are described in detail on the Launch on Windows page. In this example we will execute the Wrapper directly.

Internationalization / Localization:

If you wish to use the Wrapper in a language other than English, please copy over the localization resources by copying over the entire lang directory.

Copy a language file:
%WRAPPER_HOME%\lang -> %EXAMPLE_HOME%\lang

License key:

The Standard and Professional Editions of the Java Service Wrapper require a license key to be able to run. The Wrapper is shipped with a simple license key that will let you run the Wrapper for 15 minutes. Please copy that over for now. You can obtain a long term trial license by clicking on the Free Trial button at the top of the page.

Copy the license file:
%WRAPPER_HOME%\src\conf\wrapper-license-time.conf -> %EXAMPLE_HOME%\conf\wrapper-license.conf

Wrapper configuration file:

Finally, copy over the default Wrapper configuration file. We will edit it in the next section.

Copy the configuration file:
%WRAPPER_HOME%\src\conf\wrapper.conf.in -> %EXAMPLE_HOME%\conf\wrapper.conf

Wrapper Configuration file

Open the %EXAMPLE_HOME%\conf\wrapper.conf file in the text editor of your choice. Notepad will work fine.

Please locate and modify the following properties.

Configuration file
wrapper.java.command=java
wrapper.java.command.loglevel=INFO

wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp
wrapper.app.parameter.1=HelloWorldServer

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

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

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

wrapper.console.title=Hello World Server
wrapper.name=helloworldserver
wrapper.displayname=Hello World Server
wrapper.description=Hello World Server
  • The wrapper.java.command property is used to specify the location of the Java command that will be used. The value that we have specified will be searched in the system path. It is also possible to specify an absolute path.

  • The wrapper.java.command.loglevel property is optional, but it is useful to help debug the Java command line which the Wrapper generates. We recommend that you include this as you get started, but it can be commented out once you have your application working.

  • The wrapper.java.mainclass property is used to specify the main class that is passed to Java when it is launched. This is a point of confusion for new users, but in most cases, this will be one of the Wrapper's helper classes rather than the main class of your application. The Wrapper supports several integration methods, but for this example, we are using the most simple method called Integration Method #1 (WrapperSimpleApp). This method makes use of the org.tanukisoftware.wrapper.WrapperSimpleApp helper class to manage the JVM lifecycle and backend communication with the Wrapper. For now, don't worry about this point.

  • The actual main class of our application HelloWorldServer is passed in as the first parameter using the wrapper.app.parameter.1 property. It is possible to pass in additional parameters to HelloWorldServer by adding additional properties with increasing indexes wrapper.app.parameter.2=P1, for example.

    We don't show them here, but it is also possible to add additional Java parameters using the wrapper.java.additional.<n> properties.

  • The next step is to specify the classpath. This is done using the wrapper.java.classpath.<n> properties. We need to have two classpath entries for our application. The first is to include the required wrapper.jar file which includes the Wrapper's helper classes. The second includes the lib/classes directory where our HelloWorldServer class is located.

  • The Wrapper makes use of a native library, wrapper.dll, to implement some of its functionality. Native libraries are not used by many Java applications so you may not have encountered them before. The wrapper.java.library.path.<n> properties are used to specify where these libraries are located. For now, don't worry about this point.

We have now told the Wrapper how to run our Java application.

There are just a couple more properties that need to be setup.

One important thing to note about all of the property values is that they are always specified with path values that are relative to the location of the wrapper.exe binary.

In addition to the properties that we are setting, there are a few other key elements of the configuration file which you should be aware of.

  • The top of the file contains an encoding for the file.

  • The #include ../conf/wrapper-license.conf line is used the include file feature to include the license key properties. Note that the leading # is required.

  • The wrapper.lang.folder property is used to specify the location of the Wrapper's localization files.

Running HelloWorldServer in a Console

The Wrapper has now been set up. Let's start testing our configuration by running the Wrapper in a Windows Command Prompt.

Please open a new Command Prompt and go into our %EXAMPLE_HOME% directory with cd command. The Wrapper and our wrapped application can now be started as follows:

bin\wrapper.exe -c ..\conf\wrapper.conf

Note that the location of the configuration file is relative to the location of the Wrapper binary. This is a little counter-intuitive, but it greatly increases the reliability of the Wrapper when launched using different methods.

When the Wrapper starts, you should see something like this:

wrapper  | --> Wrapper Started as Console
wrapper  | Java Service Wrapper Professional Edition 64-bit {version}
wrapper  |   Copyright (C) 1999-2010 Tanuki Software, Ltd. All Rights Reserved.
wrapper  |     https://wrapper.tanukisoftware.com
wrapper  |
wrapper  | --------------------------------------------------------------------
wrapper  | Thank you for your interest in the Java Service Wrapper.
wrapper  |
wrapper  | You are running with a full featured trial License Key which will
wrapper  | allow you to run or restart the Java Service Wrapper as many times
wrapper  | as you like.  Each invocation of the Wrapper will shutdown
wrapper  | automatically after 15 minutes.
wrapper  |
wrapper  | This limited trial License Key is useful for quick configuration
wrapper  | tests on various machines without the need to request a trial
wrapper  | license.  If more time is required, you can also immediately obtain
wrapper  | a one-month Free trial license:
wrapper  |   https://wrapper.tanukisoftware.com/trial
wrapper  |
wrapper  | The Java Service Wrapper requires a License Key to activate the
wrapper  | software.  License Keys can be purchased on the Java Service Wrapper
wrapper  | web site:
wrapper  |   https://wrapper.tanukisoftware.com/purchase
wrapper  |
wrapper  | This trial License Key in intended for testing and development and
wrapper  | should not be used as part of a production environment.
wrapper  | --------------------------------------------------------------------
wrapper  |
wrapper  |
wrapper  | Launching a JVM...
wrapper  | Command: "C:\Sun\jdk1.6.0_10_x64\bin\java.exe" -Djava.library.path="../lib" \
                     -classpath "../lib/wrapper.jar;../lib/classes" -Dwrapper.key="BBXKL6wk_SGpOV-i1z3E6yTeW1NQr62T" \
                     -Dwrapper.port=32000 -Dwrapper.jvm.port.min=31000 -Dwrapper.jvm.port.max=31999 -Dwrapper.pid=464 \
                     -Dwrapper.version="x.y.z" -Dwrapper.native_library="wrapper" -Dwrapper.cpu.timeout="10" \
                     -Dwrapper.jvmid=1 org.tanukisoftware.wrapper.WrapperSimpleApp HelloWorldServer
jvm 1    | WrapperManager: Initializing...
jvm 1    | Accepting connections on port: 9000

The banner at the top of the log is because we are using a temporary trial license. It points you to where you can get a long term trial license or purchase a license later.

The line that starts by "Command: " is a debug message, it shows the exact Java command line the Wrapper is executing to start the JVM. It is very useful to resolve problems. Once it is working, please comment out the wrapper.java.command.loglevel property. The rest of this example will assume you have done so.

If you have purchased a license, this is what you would see:

wrapper  | --> Wrapper Started as Console
wrapper  | Java Service Wrapper Professional Edition 64-bit {version}
wrapper  |   Copyright (C) 1999-2010 Tanuki Software, Ltd. All Rights Reserved.
wrapper  |     https://wrapper.tanukisoftware.com
wrapper  |   Licensed to {licensee}
wrapper  |
wrapper  | Launching a JVM...
jvm 1    | WrapperManager: Initializing...
jvm 1    | Accepting connections on port: 9000

You can stop your application at any time by pressing CTRL-C. The Wrapper always keeps a record of why an application was stopped so you will see something like the following in your log.

wrapper  | CTRL-C trapped.  Shutting down.
wrapper  | <-- Wrapper Stopped

Simulate a Crash

Now, to see a very simple example of how the Wrapper is able to recover from a number of failures. Please start up the Wrapper again. Next bring up the Windows Task Manager. This can be done by pressing CTRL-ALT-DEL.

View the Processes tab and locate the java.exe process. Select it and press End Process. This will tell Windows to immediately kill the Java process without giving it a chance to shutdown nicely.

When the Java process dies, you will see something like the following in the Wrapper log. Notice how the Wrapper detects that the JVM died and launches a replacement within a few seconds.

wrapper  | JVM exited unexpectedly.
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Initializing...
jvm 2    | Accepting connections on port: 9000

The log file keeps track of how many times the JVM has been restarted. This is very useful to system administrators so they can easily see whether there have been problems simply by looking at the end of the file.

Running the HelloWorldServer as a Service

Once the Wrapper configuration has been verified as correct, we are ready to install the Wrapper as a service.

Installing the Service

This can be done using the -i command to the Wrapper as follows.

NOTE

Please note that you will need to be a system administrator to do so. Starting with Windows 7 and Windows 2008, you will also need to be running from a console with elevated privileges.

bin\wrapper.exe -i ..\conf\wrapper.conf

You should see something like the following, confirming that the service has been installed.

wrapper  | Hello World Server service installed.

Starting the Service

You can now start your service up just like any other Windows Service. This can be done from the Windows Services Control Panel [Control Panel] - [Administrator Tool] - [Service].

The Windows net start command can also be used:

net start helloworld

It is also possible to start the Wrapper up using the Wrapper binary as follows:

bin\wrapper.exe -t ..\conf\wrapper.conf

In this case, you will see:

wrapper  | Starting the Hello World Server service...
wrapper  | Hello World Server started.

You can now confirm that the service is running by looking at the Services Control Panel [Control Panel] - [Administrator Tool] - [Service], task manager, and the WRAPPER_HOME\logs\wrapper.log file.

Stopping the Service

When you are ready to stop the service, you can do so as above, or by using the Wrapper itself:

bin\wrapper.exe -p ..\conf\wrapper.conf

Uninstalling the Service

The Wrapper is currently configured to start up again when your system is rebooted. As this is a test, you most likely want to remove the service as follows:

bin\wrapper.exe -r ..\conf\wrapper.conf

Reference: Launching your application with the Wrapper