org.tanukisoftware.wrapper

Class WrapperActionServer

public class WrapperActionServer extends Object implements Runnable

If an application instantiates an instance of this class, the JVM will listen on the specified port for connections. When a connection is detected, the first byte of input will be read from the socket and then the connection will be immediately closed. An action will then be performed based on the byte read from the stream.

The easiest way to invoke an action manually is to telnet to the specified port and then type the single command key. telnet localhost 9999, for example.

Valid commands include:

Additional user defined actions can be defined by calling the WrapperActionServer method. The Wrapper project reserves the right to define any upper case commands in the future. To avoid future conflicts, please use lower case for user defined commands.

This application will work even in most deadlock situations because the thread is in issolation from the rest of the application. If the JVM is truely hung, this class will fail to accept connections but the Wrapper itself will detect the hang and restart the JVM externally.

The following code can be used in your application to start up the WrapperActionServer with all default actions enabled:

  int port = 9999;
  WrapperActionServer server = new WrapperActionServer( port );
  server.enableShutdownAction( true );
  server.enableHaltExpectedAction( true );
  server.enableRestartAction( true );
  server.enableThreadDumpAction( true );
  server.enableHaltUnexpectedAction( true );
  server.enableAccessViolationAction( true );
  server.enableAppearHungAction( true );
  server.start();
 
Then remember to stop the server when your application shuts down:
  server.stop();
 

Author: Leif Mortenson

Field Summary
static byteCOMMAND_ACCESS_VIOLATION
Command to invoke an access violation.
static byteCOMMAND_APPEAR_HUNG
Command to invoke an appear hung action.
static byteCOMMAND_DUMP
Command to invoke a thread dump action.
static byteCOMMAND_HALT_EXPECTED
Command to invoke an expected halt action.
static byteCOMMAND_HALT_UNEXPECTED
Command to invoke an unexpected halt action.
static byteCOMMAND_RESTART
Command to invoke a restart action.
static byteCOMMAND_SHUTDOWN
Command to invoke a shutdown action.
Constructor Summary
WrapperActionServer(int port, InetAddress bindAddress)
Creates and starts WrapperActionServer instance bound to the specified port and address.
WrapperActionServer(int port)
Creates and starts WrapperActionServer instance bound to the specified port.
Method Summary
voidenableAccessViolationAction(boolean enable)
Enable or disable the access violation command.
voidenableAppearHungAction(boolean enable)
Enable or disable the appear hung command.
voidenableHaltExpectedAction(boolean enable)
Enable or disable the expected halt command.
voidenableHaltUnexpectedAction(boolean enable)
Enable or disable the unexpected halt command.
voidenableRestartAction(boolean enable)
Enable or disable the restart command.
voidenableShutdownAction(boolean enable)
Enable or disable the shutdown command.
voidenableThreadDumpAction(boolean enable)
Enable or disable the thread dump command.
voidregisterAction(byte command, Runnable action)
Registers an action with the action server.
voidrun()
Thread which will listen for connections on the socket.
voidstart()
Starts the runner thread.
voidstop()
Stops the runner thread, blocking until it has stopped.
voidunregisterAction(byte command)
Unregisters an action with the given command.

Field Detail

COMMAND_ACCESS_VIOLATION

public static final byte COMMAND_ACCESS_VIOLATION
Command to invoke an access violation.

COMMAND_APPEAR_HUNG

public static final byte COMMAND_APPEAR_HUNG
Command to invoke an appear hung action.

COMMAND_DUMP

public static final byte COMMAND_DUMP
Command to invoke a thread dump action.

COMMAND_HALT_EXPECTED

public static final byte COMMAND_HALT_EXPECTED
Command to invoke an expected halt action.

COMMAND_HALT_UNEXPECTED

public static final byte COMMAND_HALT_UNEXPECTED
Command to invoke an unexpected halt action.

COMMAND_RESTART

public static final byte COMMAND_RESTART
Command to invoke a restart action.

COMMAND_SHUTDOWN

public static final byte COMMAND_SHUTDOWN
Command to invoke a shutdown action.

Constructor Detail

WrapperActionServer

public WrapperActionServer(int port, InetAddress bindAddress)
Creates and starts WrapperActionServer instance bound to the specified port and address.

Parameters: port Port on which to listen for connections. bindAddress Address to bind to.

WrapperActionServer

public WrapperActionServer(int port)
Creates and starts WrapperActionServer instance bound to the specified port. The socket will bind to all addresses and should be concidered a security risk.

Parameters: port Port on which to listen for connections.

Method Detail

enableAccessViolationAction

public void enableAccessViolationAction(boolean enable)
Enable or disable the access violation command. Disabled by default. This command is useful for testing how an application handles the worst case situation where the JVM suddenly crashed. When this happens, the the JVM will simply die and there will be absolutely no chance for any shutdown or cleanup work to be done by the JVM.

Parameters: enable True to enable to action, false to disable it.

enableAppearHungAction

public void enableAppearHungAction(boolean enable)
Enable or disable the appear hung command. Disabled by default. This command is useful for testing how an application handles the situation where the JVM stops responding to the Wrapper's ping requests. This can happen if the JVM hangs or some piece of code deadlocks. When this happens, the Wrapper will give up after the ping timeout has expired and kill the JVM process. The JVM will not have a chance to clean up and shudown gracefully.

Parameters: enable True to enable to action, false to disable it.

enableHaltExpectedAction

public void enableHaltExpectedAction(boolean enable)
Enable or disable the expected halt command. Disabled by default. This will shutdown the JVM, but will do so immediately without going through the clean shutdown process.

Parameters: enable True to enable to action, false to disable it.

enableHaltUnexpectedAction

public void enableHaltUnexpectedAction(boolean enable)
Enable or disable the unexpected halt command. Disabled by default. If this command is executed, the Wrapper will think the JVM crashed and restart it.

Parameters: enable True to enable to action, false to disable it.

enableRestartAction

public void enableRestartAction(boolean enable)
Enable or disable the restart command. Disabled by default.

Parameters: enable True to enable to action, false to disable it.

enableShutdownAction

public void enableShutdownAction(boolean enable)
Enable or disable the shutdown command. Disabled by default.

Parameters: enable True to enable to action, false to disable it.

enableThreadDumpAction

public void enableThreadDumpAction(boolean enable)
Enable or disable the thread dump command. Disabled by default.

Parameters: enable True to enable to action, false to disable it.

registerAction

public void registerAction(byte command, Runnable action)
Registers an action with the action server. The server will not accept any new connections until an action has returned, so keep that in mind when writing them. Also be aware than any uncaught exceptions will be dumped to the console if uncaught by the action. To avoid this, wrap the code in a try { ... } catch (Throwable t) { ... } block.

Parameters: command Command to be registered. Will override any exiting action already registered with the same command. action Action to be registered.

run

public void run()
Thread which will listen for connections on the socket.

start

public void start()
Starts the runner thread.

Throws: IOException If the server socket is unable to bind to the specified port or there are any other problems opening a socket.

stop

public void stop()
Stops the runner thread, blocking until it has stopped.

unregisterAction

public void unregisterAction(byte command)
Unregisters an action with the given command. If no action exists with the specified command, the method will quietly ignore the call.
Copyright 1999, 2006 Tanuki Software Inc., All Rights Reserved.