Return-Path: Delivered-To: apmail-geronimo-scm-archive@www.apache.org Received: (qmail 23355 invoked from network); 15 Feb 2007 05:49:34 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 15 Feb 2007 05:49:34 -0000 Received: (qmail 33866 invoked by uid 500); 15 Feb 2007 05:49:42 -0000 Delivered-To: apmail-geronimo-scm-archive@geronimo.apache.org Received: (qmail 33728 invoked by uid 500); 15 Feb 2007 05:49:41 -0000 Mailing-List: contact scm-help@geronimo.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: dev@geronimo.apache.org List-Id: Delivered-To: mailing list scm@geronimo.apache.org Received: (qmail 33717 invoked by uid 99); 15 Feb 2007 05:49:41 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 14 Feb 2007 21:49:40 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 14 Feb 2007 21:49:26 -0800 Received: by eris.apache.org (Postfix, from userid 65534) id 2F8F51A9823; Wed, 14 Feb 2007 21:49:06 -0800 (PST) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r507826 [4/26] - in /geronimo/sandbox/build-support/libraries/jsw: ./ 3.2.3/ 3.2.3/bin/ 3.2.3/conf/ 3.2.3/doc/ 3.2.3/doc/english/ 3.2.3/doc/english/images/ 3.2.3/doc/english/style/ 3.2.3/jdoc/ 3.2.3/lib/ 3.2.3/logs/ 3.2.3/src/ 3.2.3/src/bin... Date: Thu, 15 Feb 2007 05:48:58 -0000 To: scm@geronimo.apache.org From: jdillon@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070215054906.2F8F51A9823@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-listener.html URL: http://svn.apache.org/viewvc/geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-listener.html?view=auto&rev=507826 ============================================================================== --- geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-listener.html (added) +++ geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-listener.html Wed Feb 14 21:48:50 2007 @@ -0,0 +1,853 @@ + + + +Java Service Wrapper - WrapperListener Integration + + + + + + + + + + + + + +
+ + + + + + + +
+ + + + +
+ + +

+Hosted by: +
+SourceForge +
+

+
+
+		 + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + + + + + +
WrapperListener Integration
+WrapperListener Integration + + + + + + + + + + + + + +
Integration Methods
+ + + + +
+ + + + + + + + + + + + +
Method 3 - WrapperListener Integration
+ + + + + + + + + + + + + + + +
Overview
+ + +

+ The third and final method, while providing the most flexibility and + access to all of the Wrapper's features, is also the only one which + requires some coding to complete the integration. This method + involves creating a class which implements the + WrapperListener interface. An + instance of the user class is then instantiated and registered with + the WrapperManager. +

+ +

+ While this method provides features that are not available with + either of the first two methods, it does add some complexity. + If the additional features are not required, implementing a + shutdown hook to enable the use of Method 1, or implementing + a shutdown class should be considered as options. The main method + of a shutdown class can be as simple as just calling a shutdown + method in the application. +

+ +

+ This method will explain how the + TestWrapper application which ships + with the Wrapper works. +

+ +
+ + + + +
+

+NOTE MEG +

+		 + +

+ This document will not cover the installation of the Wrapper files + or scripts which will be used to launch the application. Both of + these subjects are covered in detail in the descriptions of the + first two integration methods. +

+ +
+
+ +
+ + + + + + + + + + + + +
Detailed Instructions
+ + + + + + + + + + + + +
The Application Main Class
+ + +

+ Before explaining the process in too much detail, we will start with + an example main class and then explain each of its components. The + code below is a simple class which implements the + WrapperListener interface and + contains a main method which instantiates the class and calls + start on the WrapperManager. Give + it a brief once over, we go through it step by step below. +

+ + + + + +
+
import org.tanukisoftware.wrapper.WrapperManager;
+import org.tanukisoftware.wrapper.WrapperListener;
+                    
+public class Main
+    implements WrapperListener
+{
+    private MyApp m_app;
+
+    /*---------------------------------------------------------------
+     * Constructors
+     *-------------------------------------------------------------*/
+    private Main()
+    {
+    }
+
+    /*---------------------------------------------------------------
+     * WrapperListener Methods
+     *-------------------------------------------------------------*/
+    /**
+     * The start method is called when the WrapperManager is signaled by the 
+     *	native wrapper code that it can start its application.  This
+     *	method call is expected to return, so a new thread should be launched
+     *	if necessary.
+     *
+     * @param args List of arguments used to initialize the application.
+     *
+     * @return Any error code if the application should exit on completion
+     *         of the start method.  If there were no problems then this
+     *         method should return null.
+     */
+    public Integer start( String[] args )
+    {
+        m_app = new MyApp( args );
+        m_app.start();
+
+        return null;
+    }
+
+    /**
+     * Called when the application is shutting down.  The Wrapper assumes that
+     *  this method will return fairly quickly.  If the shutdown code code
+     *  could potentially take a long time, then WrapperManager.signalStopping()
+     *  should be called to extend the timeout period.  If for some reason,
+     *  the stop method can not return, then it must call
+     *  WrapperManager.stopped() to avoid warning messages from the Wrapper.
+     *
+     * @param exitCode The suggested exit code that will be returned to the OS
+     *                 when the JVM exits.
+     *
+     * @return The exit code to actually return to the OS.  In most cases, this
+     *         should just be the value of exitCode, however the user code has
+     *         the option of changing the exit code if there are any problems
+     *         during shutdown.
+     */
+    public int stop( int exitCode )
+    {
+        m_app.stop();
+        
+        return exitCode;
+    }
+    
+    /**
+     * Called whenever the native wrapper code traps a system control signal
+     *  against the Java process.  It is up to the callback to take any actions
+     *  necessary.  Possible values are: WrapperManager.WRAPPER_CTRL_C_EVENT, 
+     *    WRAPPER_CTRL_CLOSE_EVENT, WRAPPER_CTRL_LOGOFF_EVENT, or 
+     *    WRAPPER_CTRL_SHUTDOWN_EVENT
+     *
+     * @param event The system control signal.
+     */
+    public void controlEvent( int event )
+    {
+        if (WrapperManager.isControlledByNativeWrapper()) {
+            // The Wrapper will take care of this event
+        } else {
+            // We are not being controlled by the Wrapper, so
+            //  handle the event ourselves.
+            if ((event == WrapperManager.WRAPPER_CTRL_C_EVENT) ||
+                (event == WrapperManager.WRAPPER_CTRL_CLOSE_EVENT) ||
+                (event == WrapperManager.WRAPPER_CTRL_SHUTDOWN_EVENT)){
+                WrapperManager.stop(0);
+            }
+        }
+    }
+    
+    /*---------------------------------------------------------------
+     * Main Method
+     *-------------------------------------------------------------*/
+    public static void main( String[] args )
+    {
+        // Start the application.  If the JVM was launched from the native
+        //  Wrapper then the application will wait for the native Wrapper to
+        //  call the application's start method.  Otherwise the start method
+        //  will be called immediately.
+        WrapperManager.start( new Main(), args );
+    }
+}
+
+ +
+ + + + + + + + + + + + +
The Main Method
+ + +

+ The main method should in most cases be extremely simple. It has + the job of instantiating a class which implements + WrapperListener instance and + then passing that instance along with any arguments to the + start method of the + WrapperManager class. + While it is not a strict rule, in general, the main method should + do nothing else. All application initialization should be + performed from within the start + method. +

+ + + + + +
+
    public static void main( String[] args )
+    {
+        // Start the application.  If the JVM was launched from the native
+        //  Wrapper then the application will wait for the native Wrapper to
+        //  call the application's start method.  Otherwise the start method
+        //  will be called immediately.
+        WrapperManager.start( new Main(), args );
+    }
+
+ +
+ + + + + + + + + + + + +
Constructor
+ + +

+ The constructor should usually be empty as it has to complete within + the scope of the main method above. + In general, the rule of doing nothing until the + start method has been called should + be followed. +

+ + + + + +
+
    private Main()
+    {
+    }
+
+ +
+ + + + + + + + + + + + +
WrapperListener start Method
+ + +

+ The start method is where things + start to happen. This is called by the + WrapperManager after it has + established a connection with the Wrapper process. Once the Wrapper + has confirmed that the Java process has been successfully launched + and that the WrapperManager + class has been loaded, it will request that the user application be + started by calling the + WrapperListener.start method. +

+ +

+ In many ways, the start method + can be thought of as replacing an application's + main method. There are some + differences that you will have to keep in mind however. The + start method is called while the + application is in its startup phase and the application will not be + considered to have started until the + start method has returned. +

+ +

+ The Wrapper needs to be able to tell when an application has actually + completed its startup in order to defer the launching of other + processes which depend on the application being controlled by the + Wrapper. This is currently only an issue with the Windows version, + in cases where another NT Service has the Wrapper on its list of + service dependencies. Those dependencies state that the Wrapper + must be started before and stopped after the dependent service. +

+ +

+ In this first example, the start + method simply calls the main method + of another class. Remember, this will only work if we know for sure + that the main method will return within a few seconds. +

+ + + + + +
+
    public Integer start( String[] args )
+    {
+        MyApp.main( args );
+        
+        return null;
+    }
+
+ +

+ This next example instantiates an application's main class and then + tells it to start up. +

+ + + + + +
+
    public Integer start( String[] args )
+    {
+        m_app = new MyApp( args );
+        m_app.start();
+
+        return null;
+    }
+
+ +

+ The return value of the start method gives the application a chance + to abort the startup process before the application has actually + been officially started. This can be important where dependent + services are concerned. If you have such concerns then you must + use this integration method. Both the + WrapperSimpleApp and + WrapperStartStopApp helper classes + both call the application's main method in a background thread and + report that the application has successfully started within a few + seconds. +

+ +

+ A return value of null indicates + a successful startup, where as any + Integer object is used to indicate + the exit code which the Wrapper should return when it quits. +

+ + + + + +
+
    public Integer start( String[] args )
+    {
+        m_app = new MyApp( args );
+        m_app.start();
+        if ( m_app.isOk() )
+        {
+            return null;
+        }
+        else
+        {
+            System.out.println( "MyApp startup failed." );
+            return new Integer( 1 );
+        }
+    }
+
+ +

+ As stated above, the Wrapper assumes that the + start method returns + after the application has started. By default, the Wrapper will + wait for 30 seconds for the start method to complete. This timeout + can be set using the + wrapper.startup.timeout + property, but it is not always desirable to set that property to a + large value. +

+ +

+ For applications which take a variable amount of time to start up, + the Wrapper provides a way for the application to report on its + progress. At various points during the startup phase, user code + can call + WrapperManager.signalStarting(waitHint). + This method tells the Wrapper that startup is going well, but that + additional time is required. It can be called as many times as needed. +

+ + + + + +
+
    public Integer start( String[] args )
+    {
+        m_app = new MyApp( args );
+        
+        WrapperManager.signalStarting( 60000 );
+        // Do something that takes a while
+        
+        WrapperManager.signalStarting( 60000 );
+        // Do something else that also may take a while
+        
+        return null;
+    }
+
+ +
+ + + + + + + + + + + + +
WrapperListener stop Method
+ + +

+ The stop method is called by the Wrapper whenever the JVM needs + to be shutdown. It will always be called, whether a user presses + CTRL-C, the application is + stopped via the NT service manager or from a script, or user code + calls System.exit or + WrapperManager.stop. +

+ +

+ If there is some code in your application to perform a clean shutdown, + it should be called from within this method, rather than having your + shutdown code call WrapperManager.stop. + This will guarantee that the shutdown code is always called at the + correct time. Be aware that existing shutdown hooks will continue + to work as always. +

+ +

+ The stop method is called with + the exit code that the Wrapper is planning on exiting with. You have + the choice of returning this same exit code, or changing the exit + code to reflect a problem while stopping the application. +

+ + + + + +
+
    public int stop( int exitCode )
+    {
+        m_app.stop();
+        
+        return exitCode;
+    }
+
+ +

+ As with the start method. There + are times when the act of stopping an application may take longer + than the time available in the default stop timeout. In such a case, + you have the option of extending the stop timeout using the + wrapper.shutdown.timeout + property. Rather than changing this property, it is also possible + to inform the Wrapper that more time is needed by calling the + WrapperManager.signalStopping(waitHint) + method. +

+ + + + + +
+
    public int stop( int exitCode )
+    {
+        WrapperManager.signalStopping( 60000 );
+        // Do some cleanup that takes a while
+                    
+        WrapperManager.signalStopping( 60000 );
+        // Do some more cleanup that takes a while
+        
+        return exitCode;
+    }
+
+ +
+ + + + + + + + + + + + +
WrapperListener controlEvent Method
+ + +

+ The controlEvent method is used to + receive control events from the system. These include + CTRL-C on all platforms, as well + as events for when the user logs off or the machine wants to + shutdown, under windows. +

+ +

+ If most cases, the Wrapper will correctly handle all of these events + and trigger the shutdown process. However, it is also possible to + run the Java application directly without using the Wrapper. This + can be done for testing or any number of reasons. In this case, it + is the responsibility of the Java application to handle its own + life-cycle. +

+ +

+ The following example will trigger a shutdown of the JVM if the user + presses CTRL-C, hits the close box, + logs out, or shuts down the machine. But only if not controlled by + the Wrapper. +

+ + + + + +
+
    public void controlEvent( int event )
+    {
+        if (WrapperManager.isControlledByNativeWrapper()) {
+            // The Wrapper will take care of this event
+        } else {
+            // We are not being controlled by the Wrapper, so
+            //  handle the event ourselves.
+            if ((event == WrapperManager.WRAPPER_CTRL_C_EVENT) ||
+                (event == WrapperManager.WRAPPER_CTRL_CLOSE_EVENT) ||
+                (event == WrapperManager.WRAPPER_CTRL_SHUTDOWN_EVENT)){
+                WrapperManager.stop(0);
+            }
+        }
+    }
+
+ +
+ +
+ +
+ +
+

+by Leif Mortenson +

+
+
+
+
+ + + + +
+ last modified: +
+ + Propchange: geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-listener.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-listener.html ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL Propchange: geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-listener.html ------------------------------------------------------------------------------ svn:mime-type = text/html Added: geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-simple-nix.html URL: http://svn.apache.org/viewvc/geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-simple-nix.html?view=auto&rev=507826 ============================================================================== --- geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-simple-nix.html (added) +++ geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-simple-nix.html Wed Feb 14 21:48:50 2007 @@ -0,0 +1,1123 @@ + + + +Java Service Wrapper - WrapperSimpleApp Integration (Linux / UNIX) + + + + + + + + + + + + + +
+ + + + + + + +
+ + + + +
+ + +

+Hosted by: +
+SourceForge +
+

+
+
+		 + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + + + + + +
WrapperSimpleApp Integration (Linux / UNIX)
+WrapperSimpleApp Integration (Linux / UNIX) + + + + + + + + + + + + + +
Integration Methods
+ + + + +
+ + + + + + + + + + + + +
Method 1 - WrapperSimpleApp Integration (Linux / UNIX)
+ + + + + + + + + + + + + + + +
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 + /usr/lib directory, resulting + in a JBoss Home directory of + /usr/lib/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 a script which makes it easy to + launch and control the Wrapper. +

+ +
+ + + + +
+

+NOTE MEG +

+		 + +

+ Please make sure that you are using the + wrapper, and + libwrapper.so files which + were built for the platform being run. It sounds obvious, + but the Linux version will not work on Solaris for example. +

+ +
+
+ + + + + + + + + + + + +
bin directory
+ + +

+ The Wrapper is shipped with a sh + script which can be used to reliably start and stop any Java + application controlled by the Java Service Wrapper. +

+ +

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

+ + + + + +
+
{WRAPPER_HOME}/bin/wrapper
+{WRAPPER_HOME}/src/bin/sh.script.in
+
+ +

+ Rename the script file to reflect the name of the application. +

+ + + + + +
+
{JBOSS_HOME}/bin/jboss
+
+ +

+ 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 + JBoss. You will see two variables immediately after the header + of the script. APP_NAME + and APP_LONG_NAME. Note that + the default values of both of these variables are + Ant friendly + tokens which can easily be replaced as part of a build. + Suggested values for these variables are shown below. +

+ + + + + +
+
APP_NAME="jboss"
+APP_LONG_NAME="JBoss Application Server"
+
+ +

+ These script should not require any additional modification. + 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 locate this file someplace else, then that can also + be set using the WRAPPER_CONF + variable in the script. +

+ +
+ + + + +
+

+NOTE MEG +

+		 + +

+ Important! Before proceeding, please make sure that all + three files copied into the bin + directory have their executable bit set. +

+ +
+
+ +
+ + + + + + + + + + + + +
lib directory
+ + +

+ Copy the following two files into the JBoss lib directory: +

+ + + + + +
+
{WRAPPER_HOME}/lib/libwrapper.so
+{WRAPPER_HOME}/lib/wrapper.jar
+
+ +

+ The libwrapper.so 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. 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 script to build up the actual + command line. These scripts 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 script called + run.sh. It is + launched by first changing the current directory to the + bin directory and then + run from there. If you open + run.sh into an editor, you + will notice the following lines towards the end of the file: +

+ + + + + +
+
    exec $JAVA $JAVA_OPTS \
+            -classpath "$JBOSS_CLASSPATH" \
+            org.jboss.Main "$@"
+
+ +

+ The majority of the script has the task of collecting system + specific information and storing that information into environment + variables. The lines above then expands all of the collected + information into the final Java command which launches the + application. From looking at the source of the script, + 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 script by changing it as follows: +

+ + + + + +
+
    #exec $JAVA $JAVA_OPTS \
+    #        -classpath "$JBOSS_CLASSPATH" \
+    #        org.jboss.Main "$@"
+    echo "exec $JAVA $JAVA_OPTS -classpath $JBOSS_CLASSPATH org.jboss.Main $@"
+
+
+ +

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

+ + + + + +
+
exec /opt/IBMJava2-131/bin/java  -Dprogram.name=run.sh
+  -classpath /usr/lib/jboss-3.0.4/bin/run.jar:/opt/IBMJava2-131/lib/tools.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=/opt/IBMJava2-131/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.sh, but + for consistency we will leave it as is.: +

+ + + + + +
+
wrapper.java.additional.1=-Dprogram.name=run.sh
+
+ +

+ 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=/usr/lib/jboss-3.0.4/wrapper.jar
+wrapper.java.classpath.2=/usr/lib/jboss-3.0.4/bin/run.jar
+wrapper.java.classpath.3=/opt/IBMJava2-131/lib/tools.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 + libwrapper.so 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=/usr/lib/jboss-3.0.4/lib
+
+ +
+ + + + + + + + + + + + +
Putting It All Together
+ + +

+ Putting it all together, we get the following: +

+ + + + + +
+
wrapper.java.command=/opt/IBMJava2-131/bin/java
+
+wrapper.java.additional.1=-Dprogram.name=run.sh
+
+wrapper.java.classpath.1=/usr/lib/jboss-3.0.4/wrapper.jar
+wrapper.java.classpath.2=/usr/lib/jboss-3.0.4/bin/run.jar
+wrapper.java.classpath.3=/opt/IBMJava2-131/lib/tools.jar
+
+wrapper.java.library.path.1=/usr/lib/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'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.additional.1=-Dprogram.name=run.sh
+
+wrapper.java.classpath.1=../lib/wrapper.jar
+wrapper.java.classpath.2=./run.jar
+wrapper.java.classpath.3=%JAVA_HOME%/lib/tools.jar
+
+wrapper.java.library.path.1=../lib
+
+wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp
+
+wrapper.app.parameter.1=org.jboss.Main
+
+ +
+ +
+ + + + + + + + + + + + +
Trying It Out
+ + +

+ JBoss can now be run by simply executing + bin/jboss 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. +

+ +
+ +
+ +
+ +
+

+by Leif Mortenson +

+
+
+
+
+ + + + +
+ last modified: +
+ + Propchange: geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-simple-nix.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-simple-nix.html ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL Propchange: geronimo/sandbox/build-support/libraries/jsw/3.2.3/doc/english/integrate-simple-nix.html ------------------------------------------------------------------------------ svn:mime-type = text/html