Java Service Wrapper



Documentation


Users


Download


Get Involved


Hosted by:
SourceForge Logo

API Overview

API Overview


Overview of the Wrapper's Java API

The Java-side API for Wrapper is quite simple and can be run in one of three modes.

Using the WrapperSimpleApp class

The first is to use the WrapperSimpleApp class to launch your Java application with out any modifications. This class handles all communication with the native wrapper and simply launches your application by calling its main method as would be done from the command line.

The drawback to this method is that when your service is stopped, it is killed as if the user had hit CTRL-C in the console. This means that your application may not be able to shut itself down cleanly. One option that you have is to register a shutdown hook. A shutdown hook is a thread that is run when a JVM shuts down normally. See the java.lang.Runtime.addShutdownHook javadocs for more information.

The benefit is that almost any Java application will work as is using this class. All you need to do is set the following properties in your wrapper.conf file. They are described in detail in the Configuration Overview.

# Set the main class to be the WrapperSimpleApp
wrapper.java.mainclass=com.silveregg.wrapper.WrapperSimpleApp

# Set the first application parameter to the name of the class whose main method
# is to be launched.  Additional parameters come after this one.
wrapper.app.parameter.1=com.widgetsrus.MyAppMain
wrapper.app.parameter.2=parameter1
wrapper.app.parameter.3=parameter2

# Be sure to set your classpath.
wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=../lib/myapp.jar

In most cases, that should be it. Your application can now be launched using the scripts found in the Launch Overview.


Using the WrapperStartStopApp class

The second is to use the WrapperStartStopApp class to launch your Java application, once again, without any modifications. This class is useful for applications which are designed to be shutdown externally. An example is Tomcat4, shown in the Samples section of this documentation.

The WrapperStartStopApp actually requires that two seperate Main classes be configured. The first is to start the application, just like is done with the WrapperSimpleApp above. The second class is used to stop the application.

The most common case is for applications which are modeled after unix services. An application is launched and then it is killed using a command sent via a socket connection from another application instance.

This helper class was implemented is a way that does not require any special feature from the Wrapper or its configuration file. Both the start and stop class, along with all of their parameters are specified in the parameters to the WrapperStartStopApp main method. In conjunction with the Wrapper, it will then make sure that the main method of the start class is called at startup, and that the main method of the stop class is called at shutdown.

To configure the Wrapper to use the WrapperStartStopApp to control your application, you must set the following properties in your wrapper.conf file. They are described in detail in the Configuration Overview.

# Set the main class to be the WrapperStartStopApp
wrapper.java.mainclass=com.silveregg.wrapper.WrapperStartStopApp

# Set the first application parameter to the name of the class whose main method
# is to be launched. The class is followed by the number of parameters to be passed
# to the main method.  Then the actual parameters.
wrapper.app.parameter.1=com.widgetsrus.MyAppStart
wrapper.app.parameter.2=2
wrapper.app.parameter.3=startparameter1
wrapper.app.parameter.4=startparameter2

# The start parameters are followed by the name of the class whose main method
# is to be called to stop the application.  The class is followed by a flag which
# controls whether or not the Wrapper should wait for all non daemon threads to
# complete before exiting the JVM.  The flag is followed by the number of
# parameters to be passed to the main method.  Then the actual parameters.
wrapper.app.parameter.5=com.widgetsrus.MyAppStop
wrapper.app.parameter.6=true
wrapper.app.parameter.7=1
wrapper.app.parameter.8=stopparameter1

# Be sure to set your classpath.
wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=../lib/myapp.jar

That should be all that you have to do. com.widgetsrus.MyAppStart.main will be called at startup and com.widgetsrus.MyAppStop.main will be called at shutdown.


Implement the WrapperListener interface

The third method is to have your application implement the WrapperListener interface. This interface provides three methods used to inform your application when it should start and stop as well as when a system control event takes place (for example, the user hitting CTRL-C, or logging out under windows)

The WrapperListener class has the following methods.

public interface WrapperListener {
    /**
     * 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.
     * If there are any problems, then an Integer should be returned, set to
     *	the desired exit code.  If the application should continue,
     *	return null.
     */
    Integer start(String[] args);
    
    /**
     * 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.stopping()
     *  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.
     */
    int stop(int 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
     */
    void controlEvent(int event);
}

An application implementing the WrapperListener should not directly start the application in the main method. Everything that would normally be in the main method should be moved into the start method.

The main method should simply contain the following code:

public class MyApp implements WrapperListener {
    ... Application methods ...
    ... WrapperListener methods...

    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 MyApp(), args);
    }
}


API Available to Your Application

It is often necessary for your application to control its own lifecycle as a service. This includes requesting that your application be stopped or restarted.

The Java Service Wrapper allows your application access to the Wrapper via the WrapperManager class.

Please see the JavaDocs for details.



Copyright ©2000-2001 by Silver Egg Technology Co., Ltd. All Rights Reserved. last modified: