Commands are the invokable objects in JSwat that perform some kind of operation. Some example commands are: attach, stop, step, disablegc, print, and threads. Below is a brief discussion of how to write new commands for JSwat, including what features are available to commands.
All commands must subclass the JSwatCommand
class,
defined in the com.bluemarsh.jswat.command
package.
JSwatCommand
provides some basic functionality needed
for all JSwat commands. Each JSwat command class is named using the
name of the command as the prefix, followed by the
"Command" suffix. For example, the new
'friday
' command class must be named
"fridayCommand
" and placed in the
com.bluemarsh.jswat.command
package. When the user
invokes 'friday' at the JSwat command prompt, the
CommandManager
class will find the
fridayCommand
class, create an instance of it, and call
its "perform
" method.
One instance of each command is created per instance of a JSwat session.
JSwat commands can do just about anything any ordinary Java code
can do. But you are probably more concerned with what JSwat commands
can do in the context of JSwat. All of the work of a JSwat command is
carried out in its perform
method. This method is given
several parameters which enable the command to perform its task. The
first parameter is the Session object running the
command. The Session
provides access to most everything
the command could ever want, including threads, context manager,
event handler, CommandManager
, etc. The second argument
is a CommandArguments
which provides the command
arguments. For instance, if the friday
command took two
arguments, a thread ID and an object reference, those would be passed
in the args
parameter. It is up to the
friday
command to parse the strings and resolve the
arguments. The third and final argument to the perform
method is the Log
instance to which the command may
write messages. This is the same log as the one returned from
Session.getStatusLog()
.
To make the new command available to users, edit the file
classes/com/bluemarsh/jswat/command/Bundle.properties
as
described below.
commandList
property.Insert your new entries in alphabetical order so they are easy to locate.
When the new command is ready for general use, write a unit test
case for it. If the command requires an active session and/or
arguments, add the test case to the appropriate test case suites. See
the examples in the
test/junit/classes/com/bluemarsh/jswat/command
directory.