How to Write JSwat Commands

How to Write New Commands

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

Connecting the command

To make the new command available to users, edit the file classes/com/bluemarsh/jswat/command/Bundle.properties as described below.

• Add command name to commandList property.
• Add a "<name>Desc" entry.
• Add a "<name>Help" entry.

Insert your new entries in alphabetical order so they are easy to locate.

Testing the command

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.