Hosted by:

Launching Your Application (Win32)

Launching Your Application (Win32)

Launching Your Application

- All Platforms

Launching Your Application (Win32)

- Setup The Scripts
- Running in a Console
- Installing and Running as an NT Service
- Using wrapper.exe Directly
- Query Service Status
- UNIX-Style Command Based Script

| Setup The Scripts

Setting up the scripts used to launch the Java Service Wrapper is extremely simple. Simply copy the following 3 batch files from the Wrapper distribution into the bin directory of your application.

    {WRAPPER_HOME}\src\bin\App.bat.in
    {WRAPPER_HOME}\src\bin\InstallApp-NT.bat.in
    {WRAPPER_HOME}\src\bin\UninstallApp-NT.bat.in

Rename the three batch files as follows, replacing "MyApp" throughout this document with the name of your application. Be sure to remove the `.in` extensions so that the files all end in `.bat`. Depending on how your file explorer is configured, you may not be able to see the extensions.

    C:\MyApp\bin\MyApp.bat
    C:\MyApp\bin\InstallMyApp-NT.bat
    C:\MyApp\bin\UninstallMyApp-NT.bat

The three batch files are used to run an application in a console, and to install and remove it as an NT Service. These scripts should not require any modification. However, they do assume that they are placed into the same directory as the `wrapper.exe` executable. They also assume that the `wrapper.conf` file will be located within a `conf` directory one level up, `../conf/wrapper.conf`. If you wish to locate either of these files elsewhere, then the three batch files will require appropriate modifications.

| Running in a Console

Running the application in a Command Window (console) can be done by double clicking on the `MyApp.bat` batch file from within the file explorer. Or by opening a Command Window and then running the script from the command prompt. The scripts do not require that you be in the `bin` directory.

    C:\MyApp\bin>MyApp.bat
    wrapper  | --> Wrapper Started as Console
    wrapper  | Launching a JVM...
    jvm 1    | Wrapper (Version 3.x.x)
    jvm 1    |

The application can be terminated by hitting CTRL-C in the command window. This will cause the Wrapper to shut down the application cleanly.

| Installing and Running as an NT Service

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

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.

    C:\MyApp\bin>InstallMyApp-NT.bat
    wrapper  | My Application installed.

Once the service has been installed, it can be started by opening up the Service Control Panel, selecting the service, and then pressing the start button.

The service can also be started and stopped from within a Command Window by using the `net start MyApp` and `net stop MyApp` commands, or by passing commands to the wrapper.exe executable.

    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.

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

The service can be uninstalled by running the `UninstallMyApp-NT.bat` batch file.

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

| Using wrapper.exe Directly

As an alternative to using the scripts provided with the Java Service Wrapper. You may choose to launch the Wrapper directly. If the `wrapper.exe` executable is launched without any parameters, the following usage output will be displayed.

    C:\MyApp\bin>wrapper.exe
    Wrapper (Version 3.n.n) http://wrapper.tanukisoftware.org

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

    where <command> can be one of:
      -c  --console run as a Console application
      -t  --start   starT an NT service
      -p  --stop    stoP a running NT service
      -i  --install Install as an NT service
      -r  --remove  Remove as an NT service
      -q  --query   Query the current status of the service
      -qs --querysilent Silently Query the current status of the service
      -?  --help    print this help message

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

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

To run the Java Service 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.

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

To install the application as an NT service, execute:

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

Once installed, the service can be started just like any other NT 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 manually from the services control panel, or by executing either of the following two commands:

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

NOTE MEG

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 any 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.

The service can be stopped using the services control panel, or by executing either of the following commands:

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

To uninstall the application as an NT service, execute:

    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 Service Status

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.

    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" 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

An exit code of 15, 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 means that the service is not currently installed.

| UNIX-Style Command Based Script

The Wrapper distribution also includes an alternative batch file which functions very much like the shell script that is provided with UNIX versions of the Wrapper. This script requires a single command argument, which tells the script what to do. It has the benefit of being able to do everything from a single batch file. But the drawback of not being able to simply double-click on the batch file from the File Manager.

To make use of this script, simply copy the following file to your application's bin directory.

    {WRAPPER_HOME}\src\bin\AppCommand.bat.in

Rename the script as follows, replacing "MyApp" throughout this document with the name of your application. Be sure to remove the `.in` extensions so that the file ends in `.bat`. Depending on how your file explorer is configured, you may not be able to see the extension.

    C:\MyApp\bin\MyApp.bat

To familiarize yourself with the script, run it without any arguments. You will see the following:

    C:\MyApp\bin>MyApp.bat
    Usage: MyApp.bat { console : start : stop : restart : install : remove }
    Press any key to continue . . .

The `console` command runs the Wrapper in the current command window. The `start` and `stop` commands are used to start and stop the Wrapper when it is installed as an NT service. The `restart` command will stop and then immediately start the Wrapper. And the `install` and `remove` commands are used to install and remove the Wrapper as an NT service.

There are a few differences between this script and the UNIX script. The UNIX script can be used to stop a copy of the Wrapper running in a console. This is not possible with the Windows script. In addition, the `dump` command is missing from the Windows version of the script.

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  | Launching a JVM...
    jvm 1    | Wrapper (Version 3.x.x)
    jvm 1    |

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

by Leif Mortenson

Copyright ©1999-2004 by Tanuki Software. All Rights Reserved. | last modified: