| java.lang.Object
 org.tanukisoftware.wrapper.WrapperActionServer
| WrapperActionServer | | public class WrapperActionServer implements Runnable(Code) | | 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:
- S : Shutdown cleanly.
- H : Immediate forced shutdown.
- R : Restart
- D : Perform a Thread Dump
- U : Unexpected shutdown. (Simulate a crash for testing)
- V : Cause an access violation. (For testing)
- G : Make the JVM appear to be hung. (For testing)
Additional user defined actions can be defined by calling the
WrapperActionServer.registerAction(byte command,Runnable action) 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 |
| Constructor Summary | |
| public | WrapperActionServer(int port, InetAddress bindAddress)
Creates and starts WrapperActionServer instance bound to the
specified port and address. | | public | WrapperActionServer(int port)
Creates and starts WrapperActionServer instance bound to the
specified port. |
| COMMAND_ACCESS_VIOLATION | | final public static byte COMMAND_ACCESS_VIOLATION(Code) | | Command to invoke an access violation.
|
| COMMAND_APPEAR_HUNG | | final public static byte COMMAND_APPEAR_HUNG(Code) | | Command to invoke an appear hung action.
|
| COMMAND_DUMP | | final public static byte COMMAND_DUMP(Code) | | Command to invoke a thread dump action.
|
| COMMAND_HALT_EXPECTED | | final public static byte COMMAND_HALT_EXPECTED(Code) | | Command to invoke an expected halt action.
|
| COMMAND_HALT_UNEXPECTED | | final public static byte COMMAND_HALT_UNEXPECTED(Code) | | Command to invoke an unexpected halt action.
|
| COMMAND_RESTART | | final public static byte COMMAND_RESTART(Code) | | Command to invoke a restart action.
|
| COMMAND_SHUTDOWN | | final public static byte COMMAND_SHUTDOWN(Code) | | Command to invoke a shutdown action.
|
| WrapperActionServer | | public WrapperActionServer(int port, InetAddress bindAddress)(Code) | | Creates and starts WrapperActionServer instance bound to the
specified port and address.
Parameters:
port - Port on which to listen for connections.
Parameters:
bindAddress - Address to bind to. |
| WrapperActionServer | | public WrapperActionServer(int port)(Code) | | 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. |
| enableAccessViolationAction | | public void enableAccessViolationAction(boolean enable)(Code) | | 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)(Code) | | 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)(Code) | | 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)(Code) | | 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)(Code) | | 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)(Code) | | 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)(Code) | | 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)(Code) | | 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 exitingaction already registered with the same command.
Parameters:
action - Action to be registered. |
| run | | public void run()(Code) | | Thread which will listen for connections on the socket.
|
| start | | public void start() throws IOException(Code) | | Starts the runner thread.
throws:
IOException - If the server socket is unable to bind to thespecified port or there are any other problemsopening a socket. |
| stop | | public void stop() throws Exception(Code) | | Stops the runner thread, blocking until it has stopped.
|
| unregisterAction | | public void unregisterAction(byte command)(Code) | | Unregisters an action with the given command. If no action exists with
the specified command, the method will quietly ignore the call.
|
|
|