Class WrapperActionServer
- All Implemented Interfaces:
Runnable
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
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:
- Tanuki Software Development Team <support@tanukisoftware.com>
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final byte
Command to invoke an access violation.static final byte
Command to invoke an appear hung action.static final byte
Command to invoke a thread dump action.static final byte
Command to invoke an expected halt action.static final byte
Command to invoke an unexpected halt action.static final byte
Command to invoke a restart action.static final byte
Command to invoke a shutdown action. -
Constructor Summary
ConstructorsConstructorDescriptionWrapperActionServer
(int port) Creates and starts WrapperActionServer instance bound to the specified port.WrapperActionServer
(int port, InetAddress bindAddress) Creates and starts WrapperActionServer instance bound to the specified port and address. -
Method Summary
Modifier and TypeMethodDescriptionvoid
enableAccessViolationAction
(boolean enable) Enable or disable the access violation command.void
enableAppearHungAction
(boolean enable) Enable or disable the appear hung command.void
enableHaltExpectedAction
(boolean enable) Enable or disable the expected halt command.void
enableHaltUnexpectedAction
(boolean enable) Enable or disable the unexpected halt command.void
enableRestartAction
(boolean enable) Enable or disable the restart command.void
enableShutdownAction
(boolean enable) Enable or disable the shutdown command.void
enableThreadDumpAction
(boolean enable) Enable or disable the thread dump command.void
registerAction
(byte command, Runnable action) Registers an action with the action server.void
run()
Thread which will listen for connections on the socket.void
start()
Starts the runner thread.void
stop()
Stops the runner thread, blocking until it has stopped.void
unregisterAction
(byte command) Unregisters an action with the given command.
-
Field Details
-
COMMAND_SHUTDOWN
public static final byte COMMAND_SHUTDOWNCommand to invoke a shutdown action.- See Also:
-
COMMAND_HALT_EXPECTED
public static final byte COMMAND_HALT_EXPECTEDCommand to invoke an expected halt action.- See Also:
-
COMMAND_RESTART
public static final byte COMMAND_RESTARTCommand to invoke a restart action.- See Also:
-
COMMAND_DUMP
public static final byte COMMAND_DUMPCommand to invoke a thread dump action.- See Also:
-
COMMAND_HALT_UNEXPECTED
public static final byte COMMAND_HALT_UNEXPECTEDCommand to invoke an unexpected halt action.- See Also:
-
COMMAND_ACCESS_VIOLATION
public static final byte COMMAND_ACCESS_VIOLATIONCommand to invoke an access violation.- See Also:
-
COMMAND_APPEAR_HUNG
public static final byte COMMAND_APPEAR_HUNGCommand to invoke an appear hung action.- See Also:
-
-
Constructor Details
-
WrapperActionServer
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 Details
-
run
public void run()Thread which will listen for connections on the socket. -
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
Stops the runner thread, blocking until it has stopped.- Throws:
Exception
- If the thread is unable to interrupt.
-
registerAction
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 atry { ... } 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.
-
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.- Parameters:
command
- Command to be unregistered.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-