org.tanukisoftware.wrapper

Class WrapperStartStopApp

java.lang.Object

org.tanukisoftware.wrapper.WrapperStartStopApp

All Implemented Interfaces:

java.lang.Runnable, WrapperListener

public class WrapperStartStopApp
extends java.lang.Object
implements WrapperListener, java.lang.Runnable

By default the WrapperStartStopApp will only wait for 2 seconds for the main method of the start class to complete. This was done because the main methods of many applications never return. It is possible to force the class to wait for the startup main method to complete by defining the following system property when launching the JVM (defaults to FALSE): -Dorg.tanukisoftware.wrapper.WrapperStartStopApp.waitForStartMain=TRUE

Using the waitForStartMain property will cause the startup to wait indefinitely. This is fine if the main method will always return within a predefined period of time. But if there is any chance that it could hang, then the maxStartMainWait property may be a better option. It allows the 2 second wait time to be overridden. To wait for up to 5 minutes for the startup main method to complete, set the property to 300 as follows (defaults to 2 seconds): -Dorg.tanukisoftware.wrapper.WrapperStartStopApp.maxStartMainWait=300

By default, the WrapperStartStopApp will tell the Wrapper to exit with an exit code of 1 if any uncaught exceptions are thrown in the configured main method. This is good in most cases, but is a little different than the way Java works on its own. Java will stay up and running if it has launched any other non-daemon threads even if the main method ends because of an uncaught exception. To get this same behavior, it is possible to specify the following system property when launching the JVM (defaults to FALSE): -Dorg.tanukisoftware.wrapper.WrapperStartStopApp.ignoreMainExceptions=TRUE

By default, passthrough parameters are ignored, however it is possible to specify a different behaviour using the following system property: -Dorg.tanukisoftware.wrapper.WrapperStartStopApp.passthroughMode=START
Possible values are:

• START : add passthrough parameters to the parameters list of the start method
• STOP : add passthrough parameters to the parameters list of the stop method
• BOTH : add passthrough parameters to both parameters lists of the start and stop methods
• IGNORE : (default) ignore the passthrough parameters

It is possible to extend this class but make absolutely sure that any overridden methods call their super method or the class will fail to function correctly. Most users will have no need to override this class. Remember that if overridden, the main method will also need to be recreated in the child class to make sure that the correct instance is created.

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 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 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.

Author:

Tanuki Software Development Team <support@tanukisoftware.com>

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	WrapperStartStopApp(java.lang.reflect.Method startMainMethod, java.lang.reflect.Method stopMainMethod, boolean stopWait, java.lang.String[] stopMainArgs) Helper method to make it easier for user classes extending this class to have their own methods of parsing the command line.
protected	WrapperStartStopApp(java.lang.String[] args) Creates an instance of a WrapperStartStopApp.

Method Summary

Modifier and Type	Method and Description
void	controlEvent(int event) Called whenever the native wrapper code traps a system control signal against the Java process.
static void	main(java.lang.String[] args) Used to Wrapper enable a standard Java application.
void	run() Used to launch the application in a separate thread.
protected void	showUsage() Displays application usage
java.lang.Integer	start(java.lang.String[] args) The start method is called when the WrapperManager is signaled by the native wrapper code that it can start its application.
int	stop(int exitCode) Called when the application is shutting down.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WrapperStartStopApp

protected WrapperStartStopApp(java.lang.String[] args)

Creates an instance of a WrapperStartStopApp.

Parameters:

args - The full list of arguments passed to the JVM.

WrapperStartStopApp

protected WrapperStartStopApp(java.lang.reflect.Method startMainMethod,
                              java.lang.reflect.Method stopMainMethod,
                              boolean stopWait,
                              java.lang.String[] stopMainArgs)

Helper method to make it easier for user classes extending this class to have their own methods of parsing the command line.

Parameters:

startMainMethod - Name of the start method.

stopMainMethod - Name of the stop method.

stopWait - Should the stop process force the JVM to exit, or wait for all threads to die on their own.

stopMainArgs - Arguments for the stop method.

Method Detail

run

public void run()

Used to launch the application in a separate thread.

Specified by:

run in interface java.lang.Runnable

start

public java.lang.Integer start(java.lang.String[] args)

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.

Specified by:

start in interface WrapperListener

Parameters:

args - List of arguments used to initialize the application.

Returns:

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.

stop

public int stop(int exitCode)

Called when the application is shutting down.

Specified by:

stop in interface WrapperListener

Parameters:

exitCode - The suggested exit code that will be returned to the OS when the JVM exits. If WrapperManager.stop was called to stop the JVM then this exit code will reflect that value. However, if System.exit or Runtime.halt were used then this exitCode will always be 0. In these cases, the Wrapper process will be able to detect the actual JVM exit code and handle it correctly.

Returns:

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.

controlEvent

public void controlEvent(int event)

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

Specified by:

controlEvent in interface WrapperListener

Parameters:

event - The system control signal.

showUsage

protected void showUsage()

Displays application usage

main

public static void main(java.lang.String[] args)

Used to Wrapper enable a standard Java application. This main expects the first argument to be the class name of the application to launch. All remaining arguments will be wrapped into a new argument list and passed to the main method of the specified application.

Parameters:

args - Arguments passed to the application.