The fourth and final method is to use the WrapperJarApp helper class to launch the application.
This is another simple way to integrate with the Wrapper when the application is
already configured to run as an executable jar.
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 shuts down 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 shut down cleanly.
If, on the other hand, a Shutdown Hook is not registered, then the application will suddenly
exit like when 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 4, the WrapperJarApp helper class replaces an application's main class.
This gives the WrapperJarApp class a chance to immediately initialize the
WrapperManager and register the JVM with the Wrapper.
The WrapperJarApp 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 jar's manifest is inspected and its configured main class is called.
The WrapperJarApp creates a new ClassLoader, which is able to load classes from
the executable jar as well as any other jar files referenced within its manifest file.
The WrapperJarApp helper class is told how to launch the application by passing the absolute or relative location of
the executable jar file, followed by any additional application parameters to the main method of the WrapperJarApp.
Detailed Instructions
This section will walk you through a detailed explanation of how to configure
JBoss to run within the Wrapper.
Most other applications deployed as executable jars can be integrated by following the same steps.
Install JBoss
This tutorial will start with a clean install of JBoss.
We used JBoss EAP 7.0.0, so the exact steps may be slightly different depending on the exact version installed.
After downloading JBoss, extract the files somewhere. In this tutorial we will use the folder D:\JBoss.
Then create the following folders:
D:\JBoss\lib
D:\JBoss\conf
D:\JBoss\logs
Installing Wrapper Files
After downloading the Wrapper, extract the files somewhere, that will be referenced as {WRAPPER_HOME}.
There are four directories which are required to be configured in order to be able to use the Wrapper.
bin directory
First, copy the following files into the JBoss bin directory:
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 Windows 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.
lib directory
Copy the following two files into the JBoss lib directory:
The wrapper.dll file is a native library file
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 "wrapper.conf" for each application.
The standard location for this file is in a conf directory in the application's home directory.
Copy the following template file wrapper.conf.in
into the conf directory of JBoss.
{WRAPPER_HOME}\src\conf\wrapper.conf.in
Rename the file and 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.
logs directory
The default configuration file wrapper.conf will place a
wrapper.log file into the JBoss logs directory.
{JBOSS_HOME}\logs
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.
The Java Command Line
The Java command line of an executable jar is quite simple.
In the case of JBoss, you would simply go to the JBoss directory and execute:
In order 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
For all properties 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, extract the Java executable and assign the location path to the
wrapper.java.command property:
wrapper.java.command=java
Wrapper Jar
The Wrapper requires that its wrapper.jar be specified:
wrapper.jarfile=D:\JBoss\lib\wrapper.jar
WARNING
The wrapper.jarfile property was introduced in version 3.5.55.
When using earlier Wrapper versions, it is necessary to include wrapper.jar in the classpath:
Then, the indices of next classpath elements must be adjusted so that the wrapper.java.classpath.1 property is not repeated.
Classpath
Next comes the classpath, which is configured using the
wrapper.java.classpath.<n> properties.
Java does not actually allow you to specify a classpath when running with the -jar parameter
but this integration with the Wrapper works a little differently.
The Wrapper requires that its wrapper.jar be specified in the classpath:
When using the Wrapper and the WrapperJarApp helper class, Java is not executing the jar directly.
It is necessary to specify the helper class as the main class of the application.
The main class executed by Java when launched is specified by using the
wrapper.java.mainclass property as follows:
Application parameters are set using the
wrapper.app.parameter.<n> properties.
In this case, the command line to launch JBoss requires some application parameters.
It is necessary to tell the WrapperJarApp helper class which jar to execute.
This is done as follows:
Java additional parameters are set using the
wrapper.java.additional.<n> properties.
Some parameters must be set for the JVM in order to start JBoss correctly.
In order to use the Wrapper, one more property must be set.
The Wrapper makes use of a native library to control interactions with the system.
This library filewrapper.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.
Notice, while these configurations will work correctly on our test 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:
The final step is to set the Windows Service 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.
The properties are set in the wrapper.conf file
found in the conf folder from the Wrapper installation.
Trying It Out
JBoss can now be run by simply executing the batch file bin\myJBoss.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.
The first time JBoss starts up, it will create its configuration files within the current user's home directory.
Note that this will most likely be a different location when running as a service versus when running in a console window.
Congratulations, your application should now be up and running.
If you have any problems, please take a look at the Troubleshooting section for help with tracking down the problem.