|
|
 |
 |
| WrapperSimpleApp Integration (Windows) |
WrapperSimpleApp Integration (Windows)
 |
|
|
|
|
|
|
The Method 1 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 like pressing CTRL-C in the console (command window).
Both cases, with and without a Shutdown Hook,
provide the exact same behavior as if the application was running without the Wrapper.
When integrating with this Method 1 (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.
|
|
|
|
This 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.
|
|
|
This tutorial will start with a clean install of
JBoss.
We used "JBoss 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.
|
|
|
|
There are four directories which are required to be configured in order to be able to use the Wrapper.
|
|
|
First, please 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 with refrecting your application name 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 on your computer,
you may not be able to see file extensions.)
You should now have:
{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 uninstall it as a Wiindows Service.
These batch files 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 place the wrapper.conf file somewhere else,
then the three batch files will require appropriate modification.
|
|
|
|
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.
|
|
|
|
The Wrapper requires a configuration file
wrapper.conf for each application.
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 copy the following template file wrapper.conf.in
into the conf directory of JBoss.
{WRAPPER_HOME}\src\conf\wrapper.conf.in
|
Rename the file as follows.
Be sure to remove the .in
extension so that the file is named
wrapper.conf.
You should now have:
{JBOSS_HOME}\conf\wrapper.conf
|
If you wish to relocate the configuration file wrapper.conf, you are free
to do so. You will need to modify the batch files copied
into the bin directory above,
to reflect the new location.
|
|
|
|
The default wrapper.conf file
will place a wrapper.log file
in a logs directory under the application's home directory.
JBoss does not have such a directory by default, so we will need to create one.
You should now have the following directory:
If you wish to place the wrapper.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.
|
|
|
|
|
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 but
in fact, the featured ability to avoid having to work with them is
one of the benefits of working with the Wrapper.
JBoss is launched by default 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 script 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 run.bat 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 batch file, 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
|
|
|
|
|
In order to be able to use the above Java command line with the Wrapper,
we need to break up the command line's components into a configuration file.
Open the wrapper.conf file
into an editor and make the changes below.
|
NOTE
| |
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.
|
|
|
|
First is to extract the Java executable and assign the location path to the
wrapper.java.command
property:
wrapper.java.command=D:\Sun\j2sdk1.4.0_03\bin\java
|
|
|
|
|
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 additional Java Argument.
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.
|
|
|
|
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
|
|
|
|
|
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 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
|
|
|
|
|
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 library 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, 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, while these configurations will work 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
|
|
|
|
|
(See:Windows Versions supported by Wrapper)
The final step is to set the
Windows 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.
Suggested values for these variables are shown below.
wrapper.ntservice.name=JBoss
wrapper.ntservice.displayname=JBoss Application Server
wrapper.ntservice.description=JBoss Application Server
|
|
|
|
|
|
JBoss can now be run by simply executing the batch file
bin\JBoss.bat.
Because of the way the Wrapper sets its current directory,
it is not necessary to run this batch file 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 default the WrapperSimpleApp class
will wait 2 seconds for the user application's main method to complete.
After that,
it assumes that the application has started and reports back to the Wrapper process.
This is done because many user applications are written with main methods
that do not return for the life of the application.
In such cases, there is no reliable way for the
WrapperSimpleApp class to tell
when and if the application has completed its startup.
If, however, it is known that the application's main method will return
once the application is started,
it would be ideal for the Wrapper to wait until it has done so before continuing.
For main methods that return in this way,
the WrapperSimpleApp looks for
the org...WrapperSimpleApp.waitForStartMain
system property.
If it is set to TRUE,
the WrapperSimpleApp
will wait indefinitely for the main method to complete.
wrapper.java.additional.1=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.waitForStartMain=TRUE
|
Waiting indefinitely is an advantageous option
if it known for sure that the main method will return in a timely manner.
But on the other hand, while it is waiting eternally,
the Wrapper will never give up on the startup process, no matter how long it takes.
So, if there is any chance that this startup could hang, then
the org...WrapperSimpleApp.maxStartMainWait
system property to set the maximum wait time may be a better option.
For instance, to wait for up to 5 minutes for the startup main method to complete,
set the property to 300 as follows (the default value is 2 seconds):
wrapper.java.additional.1=-Dorg.tanukisoftware.wrapper.WrapperSimpleApp.maxStartMainWait=300
|
|
NOTE
| |
The main methods of many applications are designed not to return.
In these cases, you must either stick with the default 2 second startup timeout
or specify a slightly longer timeout, using the
maxStartMainWait property,
to simulate the amount of time your application takes to start up.
|
|
WARNING
| |
If "TRUE" in the waitForStartMain is specified for an application
whose start method never returns, the Wrapper will appear at first to be functioning correctly.
However the Wrapper is actually in a wait status eternally and will never enter a "running" state,
this means that the Windows Service Manager and several of the Wrapper's error recovery mechanisms
will not function correctly.
|
|
|
|
|
|
 | If you notice something that is incorrect, missing, or simply feel that some part of this page could be explained better, feel free to log in and add a comment. You will need to register before you can log on. |
|
|  |
|
 |
| |
