Java Service Wrapper



Documentation


Users


Download


Get Involved


Hosted by:
SourceForge Logo

Launch Overview

Launch Overview


Launching Your Application Under Wrapper

Windows NT/2000

To run your application as a console app, execute the following command.

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

To install the application as an NT service, execute.

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

Then to start it, either reboot, go to the services control panel, or execute:

C:\MyApp\bin> net start MyApp

To uninstall the application as an NT service, execute:

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

These commands should normally be placed in batch files in the application's bin directory to make them easier to use.

A typical application would have the following three batch files in the bin directory with the Wrapper.exe file. The scripts will look for a wrapper.conf file passed in as an argument and then use a default if one is not specified. These examples assume that the '@app.home@' token will be replaced with your application's home directory on installation. Something like 'C:\MyApp'. The quotes around the paths in the scripts make it possible for the path to contain spaces.

MyApp.bat

@echo off

set _WRAPPER_CONF="%~f1"
if not %_WRAPPER_CONF%=="" goto startup
set _WRAPPER_CONF="@app.home@\conf\wrapper.conf"

:startup
"@app.home@\bin\Wrapper.exe" -c %_WRAPPER_CONF%
if not errorlevel 1 goto end
pause

:end
set _WRAPPER_CONF=

InstallMyApp-NT.bat

@echo off

set _WRAPPER_CONF="%~f1"
if not %_WRAPPER_CONF%=="" goto startup
set _WRAPPER_CONF="@app.home@\conf\wrapper.conf"

:startup
"@app.home@\bin\Wrapper.exe" -i %_WRAPPER_CONF%
if not errorlevel 1 goto end
pause

:end
set _WRAPPER_CONF=

UninstallMyApp-NT.bat

@echo off

set _WRAPPER_CONF="%~f1"
if not %_WRAPPER_CONF%=="" goto startup
set _WRAPPER_CONF="@app.home@\conf\wrapper.conf"

:startup
"@app.home@\bin\Wrapper.exe" -r %_WRAPPER_CONF%
if not errorlevel 1 goto end
pause

:end
set _WRAPPER_CONF=

It is also possible to make batch scripts which use only relative paths. This has the benefit of allowing you to unzip an application and run it in any location, but it has the drawback that the script will not work correctly on older version of windows. Template batch files can be found in the src/bin directory, named App.bat.in, InstallApp-NT.bat.in and UninstallApp-NT.bat.in. They should be renamed to match the name of your application.

MyApp.bat

@echo off
rem
rem Find the application home.
rem
if "%OS%"=="Windows_NT" goto nt

echo This is not NT, so please edit this script and set _APP_HOME manually
set _APP_HOME=..

goto conf

:nt
rem %~dp0 is name of current script under NT
set _APP_HOME=%~dp0
rem : operator works similar to make : operator
set _APP_HOME=%_APP_HOME:\bin\=%


rem
rem Find the wrapper.conf
rem
:conf
set _WRAPPER_CONF="%~f1"
if not %_WRAPPER_CONF%=="" goto startup
set _WRAPPER_CONF="%_APP_HOME%\conf\wrapper.conf"


rem
rem Run the application.
rem At runtime, the current directory will be that of Wrapper.exe
rem
:startup
"%_APP_HOME%\bin\Wrapper.exe" -c %_WRAPPER_CONF%
if not errorlevel 1 goto end
pause

:end
set _APP_HOME=
set _WRAPPER_CONF=

Starting in version 2.2.3, it is possible to specify paths in your wrapper.conf file which are relative to the Wrapper.exe file. Older versions did not work correctly with relative paths when the application was run as an NT service.


Linux / Solaris

To run your application from the command line:

$ wrapper [your application's wrapper config file]

In the src/bin subdirectory you will find some shell (bash and sh)script templates for starting and stopping wrapped applications cleanly in. These examples assume that the '@app.name@' and '@app.long.name@' tokens will be replaced with the name of your application on installation. Good values are 'testwrapper' for '@app.name@' and 'Test Wrapper Application' for '@app.long.name@'. These scripts also make some assumtions about your project's directory structure. Template scripts can be found in the src/bin directory, named bash.script.in and sh.script.in respectively.

You may need to tweak some of the other values (like PIDDIR in the sh script) to get them to fit your environment.

These scripts are used by passing them a command. Valid commands are start, stop, restart, and dump. start is used to launch the application and stop is used to stop it. restart will start and then stop the application in a single command. The dump command is used to invoke a thread dump in the JVM. See the Debugging section for more information on dump.

bash script

#! /bin/bash

#
# Skeleton bash script suitable for starting and stopping 
# wrapped Java apps on the Linux platform.
#
# This script expects to find the 'realpath' executable
# in the same directory. 
#

#-----------------------------------------------------------------------------
# These settings can be modified to fit the needs of your application

# Application
APP_NAME="@app.name@"
APP_LONG_NAME="@app.long.name@"

# Wrapper
WRAPPER_CMD="./wrapper"
WRAPPER_CONF="../conf/wrapper.conf"

# Priority (see the start() method if you want to use this)
PRIORITY=

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

# Get to the actual location of this script
SCRIPT_DIR=`dirname $0`
SCRIPT=`$SCRIPT_DIR/realpath $0`
cd `dirname $SCRIPT`

# Find pidof.
PIDOF="/bin/pidof"
if [ ! -x $PIDOF ]
then
    PIDOF="/sbin/pidof"
    if [ ! -x $PIDOF ]
    then
        echo "Cannot find 'pidof' in /bin or /sbin."
        echo "This script requires 'pidof' to run."
        exit 1
    fi
fi

start() {
    echo "Starting $APP_LONG_NAME..."
    pid=`$PIDOF $APP_NAME`
    if [ -z $pid ]
    then
        # If you wanted to specify the priority with which
        # your app runs, you could use nice here:
        # exec -a $APP_NAME nice -$PRIORITY $WRAPPER_CMD $WRAPPER_CONF &
        # See "man nice" for more details.
        exec -a $APP_NAME $WRAPPER_CMD $WRAPPER_CONF &
    else
        echo "$APP_LONG_NAME is already running."
        exit 1
    fi
}

stop() {
    echo "Stopping $APP_LONG_NAME..."
    pid=`$PIDOF $APP_NAME`
    if [ -z $pid ]
    then
        echo "$APP_LONG_NAME was not running."
    else
        kill $pid
        sleep 6

        pid=`$PIDOF $APP_NAME`
        if [ ! -z $pid ]
        then
            kill -9 $pid
        fi

        pid=`$PIDOF $APP_NAME`
        if [ ! -z $pid ]
        then
            echo "Failed to stop $APP_LONG_NAME."
        else
            echo "Stopped $APP_LONG_NAME."
        fi
    fi
}

dump() {
    echo "Dumping $APP_LONG_NAME..."
    pid=`$PIDOF $APP_NAME`
    if [ -z $pid ]
    then
        echo "$APP_LONG_NAME was not running."
    else
        kill -3 $pid

        if [ $? -ne 0 ]
        then
            echo "Failed to dump $APP_LONG_NAME."
        else
            echo "Dumped $APP_LONG_NAME."
        fi
    fi
}

case "$1" in

    'start')
        start
        ;;

    'stop')
        stop
        ;;

    'restart')
        stop
        start
        ;;

    'dump')
        dump
        ;;

    *)
        echo "Usage: $0 { start | stop | restart | dump }"
        exit 1
        ;;
esac

exit 0

sh script

#! /bin/sh

#
# Skeleton sh script suitable for starting and stopping 
# wrapped Java apps on the Solaris platform. 
#
# This script expects to find the 'realpath' executable
# in the same directory. 
#
# Make sure that PIDFILE points to the correct location,
# if you have changed the default location set in the 
# wrapper configuration file.
#

#-----------------------------------------------------------------------------
# These settings can be modified to fit the needs of your application

# Application
APP_NAME="@app.name@"
APP_LONG_NAME="@app.long.name@"

# Wrapper
WRAPPER_CMD="./wrapper"
WRAPPER_CONF="../conf/wrapper.conf"

# Priority (see the start() method if you want to use this) 
PRIORITY=

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

# Get to the actual location of this script
SCRIPT_DIR=`dirname $0`
SCRIPT=`$SCRIPT_DIR/realpath $0`
cd `dirname $SCRIPT`

# Process ID
PIDDIR="/var/run"
PIDFILE="$PIDDIR/$APP_NAME.pid"
pid=""

getpid() {
    if [ -f $PIDFILE ]
    then
    if [ -r $PIDFILE ]
    then
        pid=`cat $PIDFILE`
        if [ "X$pid" != "X" ]
        then
        # Verify that a process with this pid is still running.
        pid=`/usr/bin/ps -p $pid | grep $pid | grep -v grep | awk '{print $1}' | tail -1`
        if [ "X$pid" = "X" ]
        then
            # This is a stale pid file.
            rm -f $PIDFILE
            echo "Removed stale pid file: $PIDFILE"
        fi
        fi
    else
        echo "Cannot read $PIDFILE."
        rm -f $PIDFILE
        exit 1
    fi
    fi
}
 
start() {
    echo "Starting $APP_LONG_NAME..."
    getpid
    if [ "X$pid" = "X" ]
    then
        # If you wanted to specify the priority with which
        # your app runs, you could use nice here:
        # exec nice -$PRIORITY $WRAPPER_CMD $WRAPPER_CONF &
        # See "man nice" for more details.
        exec $WRAPPER_CMD $WRAPPER_CONF &
    else
        echo "$APP_LONG_NAME is already running."
        exit 1
    fi
}
 
stop() {
    echo "Stopping $APP_LONG_NAME..."
    getpid
    if [ "X$pid" = "X" ]
    then
        echo "$APP_LONG_NAME was not running."

    else
        kill $pid
        sleep 6

        pid=`/usr/bin/ps -p $pid | grep $pid | grep -v grep | awk '{print $1}' | tail -1`

        if [ "X$pid" != "X" ]
        then
        # SIGTERM didn't work, send SIGKILL.
            kill -9 $pid
        rm -f $PIDFILE

            pid=`/usr/bin/ps -p $pid | grep $pid | grep -v grep | awk '{print $1}' | tail -1`
        fi

        if [ "X$pid" != "X" ]
        then
            echo "Failed to stop $APP_LONG_NAME."
            exit 1
        else
            echo "Stopped $APP_LONG_NAME."
        fi
    fi
}

dump() {
    echo "Dumping $APP_LONG_NAME..."
    getpid
    if [ "X$pid" = "X" ]
    then
        echo "$APP_LONG_NAME was not running."

    else
        kill -3 $pid

        if [ $? -ne 0 ]
        then
            echo "Failed to dump $APP_LONG_NAME."
            exit 1
        else
            echo "Dumped $APP_LONG_NAME."
        fi
    fi
}

case "$1" in

    'start')
        start
        ;;

    'stop')
        stop
        ;;

    'restart')
        stop
        start
        ;;

    'dump')
        dump
        ;;

    *)
        echo "Usage: $0 { start | stop | restart | dump }"
        exit 1
        ;;
esac

exit 0



Copyright ©2000-2001 by Silver Egg Technology Co., Ltd. All Rights Reserved. last modified: