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.

Below are the different methods to start the Wrapper:

  • Dedicated Batch Files:

    Allow the user to double-click on them to take individual actions like installing as a service, starting, etc.

  • Command-Based Batch File:

    Launched from a console and takes a command as a parameter. This is very similar to the script provided on UNIX platforms and is useful for users who prefer to use the command line.

  • Standalone Binary:

    It is also possible to run the Wrapper binary directly from a command line using parameters.

Dedicated Batch Files

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

Set up 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 are each used for a specific task. (There are other files in the directory which are described elsewhere in this page.)

When setting up the Wrapper, you can choose which of the above batch files are needed 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 with variables that can be customized. 

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 directory where the Wrapper binary (.exe) file is located. It can be
rem  either an absolute or a relative path. If the path contains any special
rem  characters, please make sure to quote the variable.
set _WRAPPER_DIR=

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.
rem If a relative path is specified, please note that the location is based on the
rem location of the Wrapper executable.
set _WRAPPER_CONF_DEFAULT="../conf/%_WRAPPER_BASE%.conf"

rem Makes it possible to override the Wrapper configuration file by specifying it
rem  as the first parameter.
rem set _WRAPPER_CONF_OVERRIDE=true

rem _PASS_THROUGH controls how the script arguments should be passed to the
rem  Wrapper. Possible values are:
rem  - commented or 'false': the arguments will be ignored (not passed).
rem  - 'app_args' or 'true': the arguments will be passed through the Wrapper as
rem                          arguments for the Java Application.
rem  - 'both': both Wrapper properties and Application arguments can be passed to
rem            the Wrapper. The Wrapper properties come in first position. The
rem            user can optionally add a '--' separator followed by application
rem            arguments.
rem NOTE - If _WRAPPER_CONF_OVERRIDE is set to true the above applies to arguments
rem        starting with the second, otherwise it applies to all arguments.
rem set _PASS_THROUGH=app_args

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

  • _WRAPPER_BASE :

    Controls where the Wrapper binary is relative to the location of the batch file. In most cases, it is recommended to place it in the same location. If you choose to move it to another location, please be aware that by default all relative paths in the Wrapper configuration file will be relative to the location of the Wrapper binary, and not of the batch file.

    It is also possible to rename the Wrapper binary to something else like myapp.exe so that it shows up in the task manager rather than wrapper.exe.

  • _WRAPPER_CONF_DEFAULT :

    Controls the location and name of the default Wrapper configuration file. This relative path is always relative to the location of the Wrapper binary, not the location of the batch file.

  • _WRAPPER_CONF_OVERRIDE :

    Lets the user override the Wrapper configuration file by specifying it as the first parameter. The default value is TRUE.

    Up through Wrapper ver. 3.5.14, the first parameter was always an alternate configuration file.

  • _PASS_THROUGH (Since ver. 3.5.5) :

    Controls whether or not parameters passed to the batch file will be passed as is on to the Java application. For more information, please visit the "How can I pass command line parameters to my Java Application?" page. This variable only exists in App.bat.in and InstallApp-NT.bat.in.

    The first parameter to the batch file will always be the name of an alternate configuration file. If _PASS_THROUGH is set, then any additional parameters will be passed through to the JVM.

Run 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. You can also do it 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: 
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  |     https://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. For more options, please visit the page on how to stop a console application.

Run 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. It can also be done by opening a Command Window and then running the installed 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 the problem will be displayed. The script will then wait for the user to press a key before terminating.

Command and Output Example: 
InstallMyApp-NT.bat
wrapper  | My Application service installed.

Start and Stop the Windows Service

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

Command and Output Example: 
StartMyApp-NT.bat
wrapper  | Starting the My Application service...
wrapper  | My Application started.

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] - [System and Security] - [Administrative Tools] - [Service]) on Windows by selecting the service, and then clicking the "Start Service" button.

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

Command and Output Example: 
net start MyApp
The My Application service is starting....
The My Application service was started successfully.

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. This is 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: 
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.

Set up 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 -----------------------------------------------------------------------------

  • _WRAPPER_BASE :

    Controls where the Wrapper binary is relative to the location of the batch file. In most cases it is recommended to place it in the same location. If you choose to move it to another location, please be aware that by default all relative paths in the Wrapper configuration file will be relative to the location of the Wrapper binary, and not of the batch file.

    It is also possible to rename the Wrapper binary to something else like myapp.exe so that shows up in the task manager rather than wrapper.exe.

  • _WRAPPER_CONF :

    Controls the location and name of the Wrapper configuration file. This relative path is always relative to the location of the Wrapper binary, not the location of the batch file.

  • _FIXED_COMMAND (Since ver. 3.5.5) :

    Tells the script to use a hard coded command rather than expecting the first parameter of the command line to be a command. By default, the script expects the first parameter to be a command. This is often used when creating multiple files that work similar to the dedicated batch files described above.

  • _PASS_THROUGH (Since ver. 3.5.5) :

    Controls whether or not parameters passed to the batch file will be passed as is on to the Java application. For more information, please visit the "How can I pass command line parameters to my Java Application?" page. This variable only exists in App.bat.in and InstallApp-NT.bat.in.

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 its usage.

Usage with _PASS_THROUGH enabled: 
Usage: TestWrapperCommand [ console {JavaAppArgs} : start : stop : restart : pause : resume : status : permissions : privileges : install {JavaAppArgs} : installstart {JavaAppArgs} : update {JavaAppArgs} : remove : setup : teardown ]

Commands:
  console      Launch in the current console.
  start        Start the Service.
  stop         Stop the Service.
  restart      Stop the Service if running and then start.
  pause        Pause the Service if running.
  resume       Resume the Service if paused.
  status       Query the current status of the Service.
  permissions  Query the current permissions of the Service.
  privileges   Query the current privileges of the Service.
  install      Install the Service.
  installstart Install the Service and then start running it.
  update       Update an installed Service.
  remove       Uninstall the Service.
  setup        Setup the Wrapper (for registration to the Windows Event Log).
  teardown     Teardown the Wrapper (unregister from the Windows Event Log).

JavaAppArgs:
  Optional arguments which will be passed to the Java application.
Usage with _PASS_THROUGH disabled: 
Usage: TestWrapperCommand [ console : start : stop : restart : pause : resume : status : permissions : privileges : install : installstart : update : remove : setup : teardown ]

...

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:

  • console:

    Used to run the application as a regular console-based application in the current user desktop. This can also be useful to test a configuration before running as a service.

    If _PASS_THROUGH has been enabled, then any additional parameters will be passed directly through to the JVM when it is launched.

  • start:

    Used to start an installed Windows Service.

  • stop:

    Used to stop a running Windows Service.

    This will only stop a service. If the application is running in a console, then you will get an error that the service was not running. Please visit the page How to Stop a Console Application for more information.

  • restart:

    Used to restart an installed Windows Service. This works by first stopping, and then starting the service.

  • pause:

    Used to pause a running Windows Service. For more information, please visit the wrapper.pausable property page.

  • resume:

    Used to resume a previously paused Windows Service. For more information, please visit the wrapper.pausable property page.

  • status:

    Queries the status of the service.

    Output when service is not installed: 
    wrapper  | The {myapp} Service is not installed.]
    Output when service is installed but stopped: 
    wrapper  | The {myapp} Service is installed.
wrapper  |   Start Type: Automatic
wrapper  |   Interactive: No
wrapper  |   Running: No]
    Output when service is running: 
    wrapper  | The {myapp} Service is installed.
wrapper  |   Start Type: Automatic
wrapper  |   Interactive: No
wrapper  |   Running: Yes]

  • permissions (Professional Edition):

    This command has been added in Wrapper version 3.5.52 to query the permissions of the currently installed service. For more information, please visit the Permissions page.

  • privileges (Professional Edition):

    This command has been added in Wrapper version 3.5.58 to query the privileges of the currently installed service. For more information, please visit the Privileges page.

  • install:

    Used to install the application as a Windows Service.

    If _PASS_THROUGH has been enabled, then any additional parameters will be passed directly through to the JVM when it is eventually started or restarted.

  • installstart:

    Used to install and then start the application as a Windows Service.

    If _PASS_THROUGH has been enabled, then any additional parameters will be passed directly through to the JVM when it is eventually started or restarted.

  • update (Standard Edition):

    Used to update (reinstall) the application as a Windows Service. This is useful when some service-related configuration values have been changed. It differs from removing and then installing the service in that things like account passwords will not need to be re-entered.

    If _PASS_THROUGH has been enabled, then any additional parameters will be passed directly through to the JVM when it is eventually started or restarted.

  • remove:

    Used to uninstall (remove) the application as a Windows Service. If the service is currently started, it will be stopped.

  • setup:

    This command has been added in Wrapper version 3.5.28 to install components which require administrator privileges on recent versions of Windows.

    Actions performed:
    - from v. 3.5.28: register the application to the Windows Event Log system.
    - from v. 3.5.42: enable or disable the Event Log monitoring occurring whenever the Wrapper process or Java process exit.

  • teardown:

    This command has been added in Wrapper version 3.5.28 to perform cleanup tasks and reverse changes done with the '--setup' command.

    Actions performed:
    - from v. 3.5.28: unregister the application from the Windows Event Log system.
    - from v. 3.5.42: disable the Event Log monitoring occurring whenever the Wrapper process or Java process exit.

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

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  |     https://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

If the wrapper executable is launched without any parameters or with a "-?", the following usage output will be displayed.

Wrapper Usage: 
Java Service Wrapper Professional Edition 64-bit {version}
  Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
    https://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
  -su --setup   SetUp the wrapper
  -td --teardown TearDown the wrapper
  -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

In order 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: 
wrapper.exe -c ..\conf\wrapper.conf

Install the Application as a Service

To install the application as a Windows Service, execute:

Command Example: 
wrapper.exe -i ..\conf\wrapper.conf

Start 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] - [System and Security] - [Administrative Tools] - [Service]) on Windows by selecting the service, and then clicking the "Start Service" button or with one of the following commands:

Command Example: 
wrapper.exe -t ..\conf\wrapper.conf

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] - [System and Security] - [Administrative Tools] - [Service]) on Windows by selecting the service, and then clicking the "Start Service" button or with one of the following commands:

Command Example: 
wrapper.exe -p ..\conf\wrapper.conf

net stop MyApp

Uninstall the Application as a Service

If you want to uninstall the application as a Windows Service, execute the following command:

Command Example: 
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 either from the Command Line or from within a batch file. This can be useful for Install Scripts that need to know the current state of the service configuration.

Command and Output Example: 
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:

  • 1: Service is installed.

  • 2: Service is running.

  • 4: Service is interactive.

  • 8: Start type is automatic.

  • 16: Start type is manual.

  • 32: Start type is disabled.

  • 32768 (2^15): Encountered error when querying the status.

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.

Reference: Launching your application with the Wrapper

[Windows]

[Linux / Unix]

[Common]