World Map
Java Service Wrapper is the easiest way to make your product more reliable.
  • Free Trial
  • Buy Now
Launching Your Application (Windows)

Launching and Controlling Your Application (Windows)

On Windows, it is possible to run a Java application either as a desktop application, or as a Windows Service in the background. In the case of a Service, the Wrapper needs to be able to be installed, removed, started, stopped, have its status queried, etc. Depending on whether the application has a GUI or is meant to be run in a command window also determines how it will be run.

Dedicated Batch Files

On Windows systems, the most way of launching the Wrapper is to make use of dedicated batch files to perform each action of controlling the Wrapper. This makes it possible for the end user to double click on the batch file icons or set up links in menus.

Setup the Batch files

When you look in the Wrapper distribution's %WRAPPER_HOME%\src\bin folder, you will see a number of template batch files which each are used for a specific task. (There are other files in the directory which are described elsewhere in this page.)

When setting up the Wrapper to run with a particular application, you can pick and choose which of the above batch files make sense for the application. For example, if an application does not support being paused then the PauseApp-NT.bat.in and ResumeApp-NT.bat.in files are not required.

Customize the Batch files

NOTE

(Depending on how your file explorer is configured on your computer, you may not be able to see file extensions.)

For each required file, simply copy it over to the bin folder of your application. When you do so, rename the file by replacing App with the name of your application, and remove the .in from the end.

Example of Replacing file names:
App.bat.in             -> MyApp.bat
InstallApp-NT.bat.in   -> InstallMyApp-NT.bat
StartApp-NT.bat.in     -> StartMyApp-NT.bat
StopApp-NT.bat.in      -> StopMyApp-NT.bat
UninstallApp-NT.bat.in -> UninstallMyApp-NT.bat

The beginning of all of the files contain a section which can be customized to fit the file naming and directory structure of your application.

HelloWorldServer.java (Change)
rem -----------------------------------------------------------------------------
rem These settings can be modified to fit the needs of your application
rem Optimized for use with version @wrapper.version@ of the Wrapper.

rem The base name for the Wrapper binary.
set _WRAPPER_BASE=wrapper

rem The name and location of the Wrapper configuration file.   This will be used
rem  if the user does not specify a configuration file as the first parameter to
rem  this script.  It will not be possible to specify a configuration file on the
rem  command line if _PASS_THROUGH is set.
set _WRAPPER_CONF_DEFAULT=../conf/wrapper.conf

rem _PASS_THROUGH tells the script to pass all parameters through to the JVM as
rem  is.
rem set _PASS_THROUGH=true

rem Do not modify anything beyond this point
rem -----------------------------------------------------------------------------

Running in a Console

Start the application

Running the application in a console (Command Window) can be done by double clicking on the MyApp.bat batch file from within the file explorer. Or it can be also done by opening a Command Window and running the batch file from the prompt. Because of the way the Wrapper script sets its current directory, it is not necessary to run this batch file from within the bin directory.

Output Example:
C:\MyApp\bin>MyApp.bat
wrapper  | --> Wrapper Started as Console
wrapper  | Java Service Wrapper Professional Edition 64-bit {version}
wrapper  |   Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
wrapper  |     http://wrapper.tanukisoftware.com
wrapper  |   Licensed to {licensee}
wrapper  |
wrapper  | Launching a JVM...
jvm 1    | WrapperManager: Initializing...

Stop the application

The application can be terminated by pressing CTRL-C in the console (command window). This will cause the Wrapper to shut down the application cleanly. Please see the page on how to stop a console application for more options.

Running as a Windows Service

NOTE

Before proceeding, please make sure you have configured all of the Windows Service related properties in the wrapper.conf file. You should also have verified that the application runs correctly in console mode.

Install as a Windows Service

The application can be installed as a service by double clicking on the InstallMyApp-NT.bat batch file from within the file explorer. Or by opening a Command Window and then running the install script from the command prompt. If the service is installed successfully, the script will terminate immediately.

If there are any problems then an error message describing what went wrong will be displayed. The script will then wait for the user to press a key before terminating.

Command and Output Example:
C:\MyApp\bin>InstallMyApp-NT.bat
wrapper  | My Application service installed.

Starting and Stopping the Windows Service

The Service can now be started and stopped using the respective batch files.

Command and Output Example:
C:\MyApp\bin>StartMyApp-NT.bat
wrapper  | Starting the My Application service...
wrapper  | My Application started.
C:\MyApp\bin>StopMyApp-NT.bat
wrapper  | Stopping the My Application service...
wrapper  | My Application stopped.

As the service is a normal Windows Service, you can also start and stop it from the Services Control Panel ([Control Panel] - [Administrator Tool] - [Service]) on Windows, selecting the service, and then clicking the "start" button.

Additionally, the service can be controlled using the net start MyApp and net stop MyApp commands.

Command and Output Example:
C:\MyApp\bin>net start MyApp
The My Application service is starting....
The My Application service was started successfully.
C:\MyApp\bin>net stop MyApp
The My Application service is stopping..
The My Application service was stopped successfully.

NOTE

The net start x and net stop x commands have problems with services that take a long time to start or stop. In most cases they will work, but if a service takes more than a few seconds to stop, the net stop x command will return that the service was stopped even though it is still in the process of stopping. This can lead to problems when a script must wait until a service has actually stopped before proceeding. By using the Wrapper to start and stop the service, you will be guaranteed not to have such problems.

The Wrapper method of starting and stopping the service is also useful in scripts as it does not require the actual name that the service is installed as to exist anywhere except in the wrapper.conf file. This removes the need for manual editing of multiple files if the service name is changed.

If the wrapper.ntservice.starttype property is set to AUTO_START then the service will be started whenever the machine is rebooted.

Uninstall (remove) from the Windows Service

The service can be uninstalled by running the UninstallMyApp-NT.bat batch file. If it is currently running then it will be stopped first.

Command and Output Example:
C:\MyApp\bin>UninstallMyApp-NT.bat
wrapper  | Service is running.  Stopping it...
wrapper  | Waiting to stop...
wrapper  | My Application stopped.
wrapper  | My Application service removed.

Command Based Batch File

Some applications which have been ported over from UNIX based operating systems may work better with a UNIX style command script to control the service. The Command Based batch file combines all of the functionality of the individual dedicated batch files into a single file, which takes a command as a parameter.

Setup the Batch files

When you look in the Wrapper distribution's %WRAPPER_HOME%\src\bin folder, you will see a template command batch file, AppCommand.bat.in.

Simply copy this file over to the bin folder of your application. When you do so, rename the file by replacing App with the name of your application, and remove the .in from the end.

Example of Replacing file names:
MyServerCommand.bat.in             -> MyServerCommand.bat
MyServer.bat.in   -> MyServer.bat

The beginning of all of the files contain a section which can be customized to fit the file naming and directory structure of your application.

Script configuration block:
rem -----------------------------------------------------------------------------
rem These settings can be modified to fit the needs of your application
rem Optimized for use with version @wrapper.version@ of the Wrapper.

rem The base name for the Wrapper binary.
set _WRAPPER_BASE=wrapper

rem The name and location of the Wrapper configuration file.
rem  (Do not remove quotes.)
set _WRAPPER_CONF="../conf/wrapper.conf"

rem _FIXED_COMMAND tells the script to use a hard coded command rather than
rem  expecting the first parameter of the command line to be the command.
rem  By default the command will will be expected to be the first parameter.
rem set _FIXED_COMMAND=console

rem _PASS_THROUGH tells the script to pass all parameters through to the JVM
rem  as is.  If _FIXED_COMMAND is specified then all parameters will be passed.
rem  If not set then all parameters starting with the second will be passed.
set _PASS_THROUGH=true

rem Do not modify anything beyond this point
rem -----------------------------------------------------------------------------

Running the Script

The command based batch file is self documenting in that if the user tries running it without any parameters, the script will display usage.

Usage:
Usage:  [ console : start : pause : resume : stop : restart : install : update : remove : status ]
Press any key to continue . . .
Usage with _PASS_THROUGH enabled:
Usage:  [ console {JavaAppArgs} : start : pause : resume : stop : restart : install {JavaAppArgs} : update {JavaAppArgs} : remove : status ]
Press any key to continue . . .

There are a few differences between this batch file for Windows and the UNIX script. The UNIX script can be used to stop the Wrapper running in a console; however, it is not possible to do so with the batch file for Windows. In addition, the dump command is missing from the batch file for Windows.

As you can see, the command based batch file provides a wide range of capability:

As an example, the Wrapper can be started in a console using the following command:

C:\MyApp\bin>MyApp.bat console
wrapper  | --> Wrapper Started as Console
wrapper  | Java Service Wrapper Professional Edition 64-bit {version}
wrapper  |   Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
wrapper  |     http://wrapper.tanukisoftware.com
wrapper  |   Licensed to {licensee}
wrapper  |
wrapper  | Launching a JVM...
jvm 1    | WrapperManager: Initializing...

To execute other commands, simply replace "console" command with the command you wish to have executed.

Standalone Binary

The Java Service Wrapper can also be run directly without making use of a batch file.

Wrapper Usage

From a command line, if you run without any parameters or with a "-?" you will see the Wrapper's usage.

Wrapper Usage:
Java Service Wrapper Professional Edition 64-bit {version}
  Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
    http://wrapper.tanukisoftware.com

Usage:
  bin\wrapper <command> <configuration file> [configuration properties] [...]
  bin\wrapper <configuration file> [configuration properties] [...]
     (<command> implicitly '-c')
  bin\wrapper <command>
     (<configuration file> implicitly 'wrapper.conf')
  bin\wrapper
     (<command> implicitly '-c' and <configuration file> 'wrapper.conf')
  bin\wrapper --customize [customize arguments]

where <command> can be one of:
  -c  --console run as a Console application
  -t  --start   starT an NT service
  -a  --pause   pAuse a started NT service
  -e  --resume  rEsume a paused NT service
  -p  --stop    stoP a running NT service
  -i  --install Install as an NT service
  -it --installstart Install and sTart as an NT service
  -u  --update Update an installed NT service
  -r  --remove  Uninstall/Remove as an NT service
  -l=<code> --controlcode=<code> send a user controL Code to a running NT service
  -d  --dump    request a thread Dump
  -q  --query   Query the current status of the service
  -qs --querysilent Silently Query the current status of the service
  -h  --hostid  prints a list of HostIds which can be used to license this host.
  -v  --version print the wrapper's version information.
  -?  --help    print this help message
  -- <args>     mark the end of Wrapper arguments.  All arguments after the
                '--' will be passed through unmodified to the java application.

<configuration file> is the wrapper.conf to use.  Name must be absolute or relative
  to the location of bin\wrapper

[configuration properties] are configuration name-value pairs which override values
  in wrapper.conf.  For example:
  wrapper.debug=true

  --customize  This command will allow you to customize your Wrapper executable.
    The following [customize arguments] are available:
      --target <target file> Specifies the name and location of the customized
          Wrapper executable.  This property is mandatory as it is not possible
          or safe to guess a default file name.
      --icon <icon file> Specifies the custom icon for your Wrapper executable.
      --passthrough If set, the new Wrapper executable will precede the
                    whole command line to the wrapped application.
      --conf <conf file> Specifies the default location of the conf file
      --manufacturer <Manufacturer> Sets the Manufacturer for the binary

  Please note that any file references must be absolute or relative to the location
  of the Wrapper executable.]

Start the Application

To run the Wrapper as a console application, you would specify the -c command, followed by the wrapper.conf file. The location of the wrapper.conf file can be an absolute or relative location. If a relative path is used, the path is always relative to the location of the wrapper.exe file, not the current directory.

Command Example:
C:\MyApp\bin>wrapper.exe -c ..\conf\wrapper.conf

Installing the Application as a Service

To install the application as a Windows Service, execute:

Command Example:
C:\MyApp\bin>wrapper.exe -i ..\conf\wrapper.conf

Starting the Application as a Service

Once installed, the service can be started just like any other Windows Service. If the wrapper.ntservice.starttype was set to AUTO_START when installed, then the service will be started the next time the machine is rebooted. It is also possible to start the service from the Services Control Panel ([Control Panel] - [Administrator Tool] - [Service]) or with one of the following commands:

Command Example:
C:\MyApp\bin>wrapper.exe -t ..\conf\wrapper.conf
C:\MyApp\bin>net start MyApp

NOTE

The net start x and net stop x commands have problems with services that take a long time to start or stop. In most cases they will work, but if a service takes more than a few seconds to stop, the net stop x command will return that the service was stopped even though it is still in the process of stopping. This can lead to problems when a script must wait until a service has actually stopped before proceeding. By using the Wrapper to start and stop the service, you will be guaranteed not to have such problems.

The Wrapper method of starting and stopping the service is also useful in scripts as it does not require the actual name that the service is installed as to exist anywhere except in the wrapper.conf file. This removes the need for manual editing of multiple files if the service name is changed.

Stopping the Application as a Service

The service can be stopped using the Services Control Panel ([Control Panel] - [Administrator Tool] - [Service]), or by executing either of the following commands:

Command Example:
C:\MyApp\bin>wrapper.exe -p ..\conf\wrapper.conf
C:\MyApp\bin>net stop MyApp

Uninstall the Application as a Service

To uninstall the application as a Windows Service, execute the following command:

Command Example:
C:\MyApp\bin>wrapper.exe -r ..\conf\wrapper.conf

If the service is running at the time that it is uninstalled, the service will be cleanly stopped and then removed.

Query the Status of the Application as a Service

The Wrapper can be used to query the state of the service manually or from within a batch file. This can be useful for install scripts which need to know the current state of the service configuration.

Command and Output Example:
C:\MyApp\bin>wrapper.exe -q ..\conf\wrapper.conf
wrapper  | The My Application Service is installed.
wrapper  |   Start Type: Automatic
wrapper  |   Interactive: Yes
wrapper  |   Running: No

If run with the "-q" command, the Wrapper will display the current status to the console, "-qs" command will run silently. The Wrapper will then exit an exit code that is a combination of the following bits:

An exit code of "15" (=1+2+4+8), for example, indicates that the service is installed, running, interactive and configured to start automatically when the system is booted. An exit code of "0" (zero) means that the service is not currently installed.