sandmark.util.exec
Class Overseer

java.lang.Object
  |
  +--sandmark.util.exec.Overseer

Direct Known Subclasses:

DumpAll, Recognizer, Tracer

public class Overseer

extends java.lang.Object

The sandmark.util.exec.Overseer class contains methods for running another program using the Java Debugger Interface (JDI).

To use this class you would typically extend it, and override one or more of the methods onMethodEntry, onMethodExit, and onProgramExit:

 public class MyOverseer extends sandmark.util.exec.Overseer {

  public MyOverseer(
     java.util.Properties props) {
     super(includeClasses,excludeClasses, constructArgv(props));
  }

  public void onMethodEntry (
    sandmark.util.exec.MethodCallData data) {
   }

  public void onMethodExit (
    sandmark.util.exec.MethodCallData data) {
   }

   public void onProgramExit (
      com.sun.jdi.VirtualMachine vm) {
   }
 }
 

The methods 'run' and 'waitToComplete' are used to start the program and wait for it to exit:

 
     MyOverseer O = new MyOverseer(includeClasses,excludeClasses,argv);
     O.run();
     ...
     O.waitToComplete();
 

Field Summary

(package private) java.lang.String[]	argv
protected java.util.List	breakPoints
(package private) EventThread	eventThread
protected java.lang.String[]	excludeClasses
protected java.lang.String[]	includeClasses
(package private) Output	out
protected com.sun.jdi.VirtualMachine	vm

Constructor Summary

Overseer(java.lang.String[] argv)

Overseer(java.lang.String[] includeClasses, java.lang.String[] excludeClasses, java.lang.String[] argv)
Prepare to run a program under JDI debugging.

Method Summary

static java.lang.String[]	constructArgv(java.util.Properties props) Given information in the props argument, construct an argv suitable to submit to an Overseer.
protected void	onMethodEntry(MethodCallData data) Override this method if you want some action to take place when a method is called.
protected void	onMethodExit(MethodCallData data) Override this method if you want some action to take place when a method is exiting.
protected void	onProgramExit(com.sun.jdi.VirtualMachine vm) Override this method if you want some action to take place when the program is exiting.
void	registerBreakpoint(Breakpoint bp)
void	run() Start running the program.
void	STOP() Stop the running program.
void	waitToComplete() Wait for the program to finish executing.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

vm

protected com.sun.jdi.VirtualMachine vm

excludeClasses

protected java.lang.String[] excludeClasses

includeClasses

protected java.lang.String[] includeClasses

breakPoints

protected java.util.List breakPoints

argv

java.lang.String[] argv

out

Output out

eventThread

EventThread eventThread

Constructor Detail

Overseer

public Overseer(java.lang.String[] includeClasses,
                java.lang.String[] excludeClasses,
                java.lang.String[] argv)

Prepare to run a program under JDI debugging.

Parameters:

includeClasses - Classes which should be traced.

excludeClasses - Classes which should not be traced.

argv - Command-line arguments to the program to be executed.

Note: Only one of includeClasses and excludeClasses can be non-empty!

Overseer

public Overseer(java.lang.String[] argv)

Method Detail

registerBreakpoint

public void registerBreakpoint(Breakpoint bp)

onMethodEntry

protected void onMethodEntry(MethodCallData data)

Override this method if you want some action to take place when a method is called.

Parameters:

data - Information about which method was called, where it's declared, who called it, etc.

onMethodExit

protected void onMethodExit(MethodCallData data)

Override this method if you want some action to take place when a method is exiting.

Parameters:

data - Information about which method is exiting, where it was declared from, who called it, etc.

onProgramExit

protected void onProgramExit(com.sun.jdi.VirtualMachine vm)

Override this method if you want some action to take place when the program is exiting.

Parameters:

vm - A handle to the virtual machine running the program.

waitToComplete

public void waitToComplete()

Wait for the program to finish executing. Shutdown begins when event thread terminates

run

public void run()
         throws TracingException

Start running the program.

TracingException

STOP

public void STOP()

Stop the running program.

constructArgv

public static java.lang.String[] constructArgv(java.util.Properties props)

Given information in the props argument, construct an argv suitable to submit to an Overseer.

Parameters:

props - should contain the following properties: