|
|
 |
 |
| WrapperJarApp Integration (Linux / Unix) |
WrapperJarApp Integration (Linux / Unix)
 |
|
|
|
|
|
|
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 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 4
(WrapperJarApp helper class),
the WrapperJarApp 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 file 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.
|
|
|
|
This section will walk you through a detailed explanation of
how to configure Hudson,
an integration engine, to run within the Wrapper.
Most other applications deployed
as executable jars
can be integrated by following the same steps.
|
|
|
This tutorial will start with a clean install of
Hudson.
We used "Hudson version 1.285" so the exact steps may be slightly different
depending on the exact version installed.
Hudson is deployed as a file called hudson.war.
This is to enable it to be deployed as a web application,
but it is also an executable jar.
We will install Hudson in a directory, /usr/lib/hudson.
Create bin, lib,
conf, and logs
directories and place the hudson.war
file inside the lib directory.
|
|
|
|
There are four directories which are required to be configured in order to be able to use the Wrapper.
|
NOTE
| |
Please make sure that you are using the appropriate Wrapper, and
libwrapper.so files
which were built for the platform being run.
It sounds obvious,
but the Wrapper Linux version will not work on Solaris for example.
|
|
|
|
The Wrapper is shipped with a shell script (sh)
which can be used to reliably start and stop any Java application
controlled by the Java Service Wrapper.
First, please copy the following files into the Hudson
bin directory:
{WRAPPER_HOME}/bin/wrapper
{WRAPPER_HOME}/src/bin/sh.script.in
|
Rename the script file to reflect the name of the application.
Now open the script into an editor.
We need to set the long and short names
to reflect that the script is being used to launch Hudson.
You will see two variables immediately after the header of the script.
APP_NAME and APP_LONG_NAME.
Suggested values for these variables are shown below.
APP_NAME="hudson"
APP_LONG_NAME="Hudson Integration Engine"
|
The script should not require any additional modification.
However it does 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,
the WRAPPER_CONF variable in the script
will require appropriate modification.
|
NOTE
| |
Important! Before proceeding,
please make sure that all files copied into the
bin
directory have their executable bit set.
|
|
|
|
|
Copy the following two files into the Hudson lib directory:
{WRAPPER_HOME}/lib/libwrapper.so
{WRAPPER_HOME}/lib/wrapper.jar
|
The libwrapper.so 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.
|
NOTE
| |
Note that the native library follows slightly different naming
conventions on some platforms. Possible names include;
libwrapper.a,
libwrapper.sl,
libwrapper.so,
and libwrapper.jnilib.
In any case, the file should be copied over without changing the extension.
|
|
|
|
|
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.
Please copy the following template file wrapper.conf.in
into the conf directory of Hudson.
{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:
{HUDSON_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 scripts copied
into the bin directory above,
to reflect the new location.
|
|
|
|
The default configuration file wrapper.conf
will place a wrapper.log file
in a logs directory under the application's home 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.
|
|
|
|
|
In the case of an executable jar, the Java command line is quite simple.
In the case of Hudson, you would simply go to the Hudson directory and execute:
java -jar /usr/lib/hudson/lib/hudson.war
|
Any arguments would be passed in as follows:
java -jar /usr/lib/hudson/lib/hudson.war arg1 arg2 arg3
|
|
|
|
|
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=java
|
|
|
|
|
Next, comes the classpath, which is configured using the
wrapper.java.classpath.<n>
properties.
Java does not actually allow you to specifiy 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:
wrapper.java.classpath.1=/usr/lib/hudson/lib/wrapper.jar
|
|
|
|
|
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:
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperJarApp
|
|
|
|
|
Application parameters are set using the
wrapper.app-parameter.<n>
properties.
In this case, the command line to launch Hudson does not specifiy any application parameters,
but it is nessary to tell the WrapperJarApp helper class
which jar to execute. This is done as follows:
wrapper.app.parameter.1=/usr/lib/hudson/lib/hudson.war
|
|
|
|
|
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
libwrapper.so needs to be specified
on the library path supplied to the JVM.
Hudson 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=/usr/lib/hudson/lib
|
|
|
|
|
Putting it all together, we get the following:
wrapper.java.command=java
wrapper.java.classpath.1=/usr/lib/hudson/lib/wrapper.jar
wrapper.java.library.path.1=/usr/lib/hudson/lib
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperJarApp
wrapper.app.parameter.1=/usr/lib/hudson/lib/hudson.war
|
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's scripts always set the current directory to the
location of the script, 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.classpath.1=../lib/wrapper.jar
wrapper.java.library.path.1=../lib
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperJarApp
wrapper.app.parameter.1=../lib/hudson.war
|
|
|
|
|
|
Hudson can now be run by simply executing the script
bin/hudson console.
Because of the way the Wrapper sets its current directory,
it is not necessary to run this script from within the
bin directory.
As you will see if you omit a command,
the scripts shipped with the Wrapper are fairly standard daemon scripts.
They accept console,
start,
stop,
restart, and
dump commands.
The start,
stop, and
restart commands are common
to most daemon scripts and are used to control the Wrapper and
its application as a daemon process. The
status command
can be used to find out whether or not the Wrapper is currently
running. The console command
will launch the Wrapper in the current shell, making it
possible to kill the application with CTRL-C.
The final command, dump, will send a
kill -3 signal to the Wrapper
causing the its JVM to do a full thread dump.
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.
|
|
|
|
|
 | 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. |
|
|  |
|
 |
| |
