YouDebug

Defining Breakpoints

Breakpoints are event callback handlers that are invoked when a certain event occurs in the target JVM. You can create breakpoints by calling breakpoint mtehods on the 'vm' object. These methods takes a closure that gets invoked when the event occurs, and they often takes additional arguments to control the nature of the breakpoint.

The following code defines a breakpoint on line 7 of the org.acme.SubStringTest.java (or whichever source file this class is defined in:)

vm.breakpoint("org.acme.SubStringTest",7) {
  println "I'm at SubStringTest.java line 7";
}

Some breakpoints have parameters for closures. For example, an exception breakpoint takes an object that represents the exception being thrown in the target JVM:

vm.exceptionBreakpoint("java.lang.IllegalArgumentException") { e ->
  e.dumpStackTrace(System.out);
}

In YouDebug scripts, you often need to deal with classes in the target JVM. You can always use the string representation of the class name, but you can also use the java.lang.Class object in the YouDebug process, if it's available (that is, either those classes are the ones defined in JavaSE, or you've added your classes into the classpath of YouDebug invocation.) So the above code can be written a little more concisely as this:

vm.exceptionBreakpoint(IllegalArgumentException.class) { e ->
  e.dumpStackTrace(System.out);
}

... or, by further using Groovy's shorthand for omitting the ".class" portion, you can do:

vm.exceptionBreakpoint(IllegalArgumentException) { e ->
  e.dumpStackTrace(System.out);
}

vm.breakpoint("org.acme.SubStringTest",7) {
  vm.exceptionBreakpoint(IllegalArgumentException) { e ->
    e.dumpStackTrace(System.out);
  }
}

vm.breakpoint("org.acme.SubStringTest",7) {
  def ebp = vm.exceptionBreakpoint(IllegalArgumentException) { e ->
    e.dumpStackTrace(System.out);
  }
  def x = vm.breakpoint("org.acme.SubStringTest",14) {
    // cancel the exception breakpoint and this breakpoint
    ebp.delete();
    x.delete();
  }
}

Evaluating Expressions

In various places in YouDebug, proxy objects are used to represent objects in the target JVM. For example, in the above example, the variable 'e' refers to an object in the YouDebug JVM, which acts as a proxy to the exception object in the target JVM.

You can invoke methods and access fields on these objects, and they'll translate into the corresponding method invocations and field access on the target JVM. For example, the following code evaluates "e.getMessage()" on the thrown exception and prints the resutling String on the YouDebug JVM. Parameters and arguments are marshalled/unmarshalled. In this way, you can transparently access data in the target JVM.

vm.exceptionBreakpoint(IllegalArgumentException) { e ->
  String x = e.getMessage();
  println x;
}

Since the proxy object is still a Java object, some of the method calls (most notably equals and hashCode) are interpreted locally, not remotely. To invoke these methods on remote objects, instead on proxy objects, escape them by prepending it with '@', like this:

x.'@hashCode'()   // calls hashCode() on the remote object
x.hashCode()      // calls hashCode() on the proxy object

In addition, proxy objects implement ObjectReference from JDI, so methods defined in those also need to be escaped.

vm.breakpoint("Main",5) {
  // this will print a message in the target JVM
  vm.ref("java.lang.System").out.println("Hello from debugger");
  
  // '_' is a synonym of 'ref'. Plus you can use a Class object instead of name,
  // hence the following equivalent code is bit shorter
  vm._(System).out.println("Hello from debugger");
}

def f = vm._new(File,"/tmp/hello");
println f.exists()

vm.exceptionBreakpoint(IllegalArgumentException) { e ->
  // create another instance of the same exception type. this is a contrived example.
  // 'type()' gets you a type proxy from an instance proxy.
  def x = e.type()."@new"();
}

// or similarly,
vm._(File)."@new"("/tmp/hello");

Inspecting/Manipulating Stack Frames

When a breakpoint is hit and the target JVM is suspended, you can walk the stack frames of threads and inspect variables. You do this through ThreadReference.

For example, in the following code, the debugger prints the visible variable 'i' from the current stack frame of the target JVM. A 'visible variable' includes local variables, instance fields, and then static fields in this order.

vm.breakpoint("Main",5) {
  println i;
}

This is actually just a short-hand for delegate.i (where delegate is a reserved variable in Groovy to point to the closure delegate.) The short form is concise, but a verbose form can be useful for disambiguation, where the variable name hits other Groovy-reserved keywords, like 'owner', 'metaClass', and so on.

According to Groovy's language rules, the reserved delegate variable is only accessible from within the closure. To access the current thread from elsewhere (such as from a subroutine you define), use vm.currentThread.

vm.breakpoint("Main",5) {
  println self;
}

// test program
class Main {
  public static void main(String[] args) {
    foo();
  }
  public static void foo() {}
}

// YouDebug script
vm.methodEntryBreakpoint("Main","foo") {
  println thread.frame(1).args[0];
}

vm.methodEntryBreakpoint("Main","main") {
  // print the first argument to the main method
  // the explicit use of 'delegate.' is necessary, or else it becomes just a bare literal.
  println delegate."@0";
}

vm.breakpoint("Main",5) {
  thread.dumpThread(); // short for 'delegate.dumpThread()', which is the same as 'vm.currentThread.dumpThread()'
}

for (t in vm.threads)
  t.dumpThread();

vm.threads*.dumpThread()   // or more concisely in the Groovy way