Hosted by:

WrapperSimpleApp Integration (Win32)

WrapperSimpleApp Integration (Win32)

Integration Methods

- Methods of Integrating with the Java Service Wrapper

Method 1 - WrapperSimpleApp Integration (Win32)

- Overview
- Detailed Instructions

| Overview

The first method is to use the `WrapperSimpleApp` helper class to launch the application. This is by far the simplest way to integrate with the Wrapper, and where possible, it is highly recommended. There are some things to be aware of when using this method however. When the Wrapper shuts down the JVM, there is no direct call to an application requesting that it shutdown cleanly. Rather, the Wrapper will exit the JVM by calling `System.exit()` from within the JVM. If the application has registered its own shutdown hook, it will be invoked, giving the application a chance to shutdown cleanly. If on the other hand, a shutdown hook is not registered, then the application will suddenly exit. Both cases, with and without a shutdown hook, provide the exact same behavior as if the application was running without the Wrapper and a user pressed CTRL-C in the console.

When integrating with the `WrapperSimpleApp` helper class, the `WrapperSimpleApp` class replaces an application's main class. This gives the `WrapperSimpleApp` class a chance to immediately initialize the `WrapperManager` and register the JVM with the Wrapper. The `WrapperSimpleApp` class then manages all interaction with the Wrapper as well as the life-cycle of an application. When the Wrapper sends a start message to the JVM via the `WrapperManager`, the main method of the application's actual main class is called.

The `WrapperSimpleApp` helper class is told how to launch the application by passing the application's main class name, followed by any additional application parameters to the main method of the `WrapperSimpleApp`.

The following section will walk you through a detailed explanation of how to configure JBoss to run within the Wrapper. Most other applications can be integrated by following the same steps.

| Detailed Instructions

| Install JBoss
This tutorial will start with a clean install of JBoss. We used version 3.0.4 so the exact steps may be slightly different depending on the exact version installed. JBoss was installed in the root directory, `D:\`, resulting in a JBoss Home directory of `D:\jboss-3.0.4`.

| Installing Wrapper Files

There are four files which are required to be able to use the Wrapper. We will also copy over three additional batch files which can be used to launch JBoss as well as install and uninstall it as an NT Service.

| bin directory

First we will copy the following files into the JBoss `bin` directory:

    {WRAPPER_HOME}\bin\Wrapper.exe
    {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. 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.

    {JBOSS_HOME}\bin\JBoss.bat
    {JBOSS_HOME}\bin\InstallJBoss-NT.bat
    {JBOSS_HOME}\bin\UninstallJBoss-NT.bat

The `Wrapper.exe` file is the actual Wrapper executable. The three batch files are used to run JBoss in a console, and to install and remove it as an NT Service. These scripts should not require any modification. They do assume that the `wrapper.conf` file will be located within a `conf` directory one level up, `../conf/wrapper.conf`. If you wish to locate this file someplace else, then the three batch files will require that small modification.

| lib directory

Copy the following two files into the JBoss lib directory:

    {WRAPPER_HOME}\lib\Wrapper.DLL
    {WRAPPER_HOME}\lib\wrapper.jar

The `Wrapper.DLL` file is a native library required by the portion of the Wrapper which runs within the JVM. The `wrapper.jar` file contains all of the Wrapper classes.

| conf directory

The Wrapper requires a configuration file. The standard location for this file is in a conf directory in the application's home directory. JBoss does not have such a directory by default, so we will need to create one. Please do so and copy the template `wrapper.conf` file to that location:

    {WRAPPER_HOME}\src\conf\wrapper.conf.in

Be sure to remove the `.in` extension so that the file is named `wrapper.conf`. Depending on how your file explorer is configured, you may not be able to see the extension. You should now have:

    {JBOSS_HOME}\conf\wrapper.conf

If you wish to relocate the configuration file, you are free to do so. You will need to modify the batch scripts copied into the `bin` directory above, to reflect the new location.

| logs directory

The default `wrapper.conf` file will place a `wrapper.log` file in a `logs` directory under the application home directory. JBoss does not have such a directory by default, so we will need to create one. Please do so. You should now have the following directory:

    {JBOSS_HOME}\logs

If you wish to place the log file in another location, you will need to edit the `wrapper.conf` file and modify the `wrapper.logfile` property to reflect the new location.

| Locate the Application's Java Command Line

Before the Wrapper can be configured to launch an Application, you will need to know the full Java command which is normally used.

Most applications make use of a batch file to build up the actual command line. These batch files tend to get quite unwieldy and in fact, the ability to avoid having to work with them is one of the benefits of working with the Wrapper.

JBoss is launched by using a batch file called `run.bat`. It is launched by first changing the current directory to the `bin` directory and then run from there. If you open `run.bat` into an editor, you will notice the following line towards the end of the file:

    %JAVA% %JAVA_OPTS% -classpath "%JBOSS_CLASSPATH%" org.jboss.Main %ARGS%

The majority of the batch file has the task of collecting system specific information and storing that information into environment variables. The line above then expands all of the collected information into the final Java command which launches the application. From looking at the source of the batch file, we hope you appreciate the complexity and the desire to have to avoid completely writing such scripts yourself.

In order to configure the Wrapper, all that is really needed is the final expanded command line. Rather than reading through the entire script and attempting to understand it, we will use a simple trick to display the final command line in the console. Edit the batch file by inserting "ECHO " at the beginning of the above line. After doing so, you should have:

    ECHO %JAVA% %JAVA_OPTS% -classpath "%JBOSS_CLASSPATH%" org.jboss.Main %ARGS%

If you now rerun the script, you will see something like the following in the console (Your output will all be on one line):

    D:\Sun\j2sdk1.4.0_03\bin\java  -Dprogram.name=run.bat
      -classpath ";D:\Sun\j2sdk1.4.0_03\lib\tools.jar;D:\jboss-3.0.4\bin\run.jar" org.jboss.Main

| Modifying the wrapper.conf File

In order to be able to use this command with the Wrapper, we need to break up its components. Open the `wrapper.conf` file into an editor and make the changes below.

NOTE MEG |  | Where properties are mentioned below, links are provided to their descriptions. Please take the time to review the descriptions of any properties which are modified. In many cases, there are further details on their usage which are not mentioned here.

| Java Executable

First is to extract the java executable and assign it to the `wrapper.java.command` property:

    wrapper.java.command=D:\Sun\j2sdk1.4.0_03\bin\java

| Java Arguments

Most applications provide a number of parameters to the Java executable when it is launched. The Wrapper provides special properties for configuring things like memory, as well as class and library paths. These will be covered below, however any other settings are configured using the `wrapper.java.additional.<n>` series of properties.

The JBoss command line only has one such property. In this case, we have changed the name of the script used to launch JBoss from `run.bat`, but for consistency we will leave it as is.:

    wrapper.java.additional.1=-Dprogram.name=run.bat

Notice that the full property was copied directly from the command line without any modifications. See the property documentation for details on how to handle properties containing spaces.

| Classpath

Next, comes the classpath, which is configured using the `wrapper.java.classpath.<n>` properties. The Wrapper requires that the classpath be broken up into its individual elements. Then, because we will also be making use of the Wrapper, it is necessary to include the `wrapper.jar` file as well:

    wrapper.java.classpath.1=D:\jboss-3.0.4\lib\wrapper.jar
    wrapper.java.classpath.2=D:\Sun\j2sdk1.4.0_03\lib\tools.jar
    wrapper.java.classpath.3=D:\jboss-3.0.4\bin\run.jar

| Main Class

The final component of the command used to launch JBoss is the main class, `org.jboss.Main`. The main class executed by Java when launched is specified by using the `wrapper.java.mainclass` property. As mentioned above however. Because the JBoss main class does not know how to communicate with the Wrapper, we will set the main class to be the full class name of `WrapperSimpleApp`. The JBoss main class is then specified as the first application parameter below.

    wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp

| Application Parameters

Application parameters are set using the `wrapper.app-parameter.<n>` properties. Application parameters appear in the Java command line directly after the main class. While JBoss does not have any such parameters, it is still necessary to set one of these properties. This is because we are using the `WrapperSimpleApp` helper class and as described above, its first parameter is the main class name of the application being run. in this case, `org.jboss.Main`:

    wrapper.app.parameter.1=org.jboss.Main

| Library Path

In order to use the Wrapper, there is one more property which much be set. The Wrapper makes use of a native library to control interactions with the system. This file `Wrapper.DLL` needs to be specified on the library path supplied to the JVM. JBoss does not have any native libraries of its own, but if it did, the directories where they were located would also need to be specified. The library path is set using the `wrapper.java-library-path.<n>` properties.

    wrapper.java.library.path.1=D:\jboss-3.0.4\lib

| Putting It All Together

Putting it all together, we get the following:

    wrapper.java.command=D:\Sun\j2sdk1.4.0_03\bin\java

    wrapper.java.additional.1=-Dprogram.name=run.bat

    wrapper.java.classpath.1=D:\jboss-3.0.4\lib\wrapper.jar
    wrapper.java.classpath.2=D:\Sun\j2sdk1.4.0_03\lib\tools.jar
    wrapper.java.classpath.3=D:\jboss-3.0.4\bin\run.jar

    wrapper.java.library.path.1=D:\jboss-3.0.4\lib

    wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp

    wrapper.app.parameter.1=org.jboss.Main

Notice what while this will function correctly on this particular machine, it is highly dependent on the directory structure and platform. By taking advantage of the fact that the Wrapper always sets the working directory to the location of the `Wrapper.exe` file and by making use of a single environment variable, we are able to modify the above properties so that they are completely platform and machine independent:

    wrapper.java.command=%JAVA_HOME%/bin/java

    wrapper.java.additional.1=-Dprogram.name=run.bat

    wrapper.java.classpath.1=../lib/wrapper.jar
    wrapper.java.classpath.2=%JAVA_HOME%/lib/tools.jar
    wrapper.java.classpath.3=./run.jar

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

    wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp

    wrapper.app.parameter.1=org.jboss.Main

| Wrapper NT/2000/XP Service Properties

The final step is to set the Windows specific `NT/2000/XP Service Properties` properties. We will just set the properties which should be changed. But there are several others available. See the documentation for details on their usage. Note that the default values of both of these variables are Ant friendly tokens which can easily be replaced as part of a build.

    wrapper.ntservice.name=JBoss
    wrapper.ntservice.displayname=JBoss Application Server
    wrapper.ntservice.description=JBoss Application Server

| Trying It Out

JBoss can now be run by simply executing the `bin\JBoss.bat` script. Because of the way the Wrapper sets its current directory, it is not necessary to run this script from within the `bin` directory. Please try running the application once as a console application to verify the configuration before attempting to run it as a service.

Congratulations. Your application should now be up and running.

If you did have any problems, please take a look at the Troubleshooting section for help with tracking down the problem.

by Leif Mortenson

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