JTrek Release Notes

Introduction

This kit contains the Trek class library, which allows you to navigate and instrument Java classfiles. It also contains several applications built using this library.

This kit is version V1.1 (#7).

Required Software

To use the Trek class library and the included applications, you need to have a Java Software Development Kit or Java Runtime Environment installed on your system. The Java system can be v1.1.7+.

Supported Platforms

JTrek should work on any platform on which Java itself runs. However it is regression-tested only on Windows and Compaq Tru64 UNIX.

Changes

Between T1.1 and V1.1

Accessing code objects:

  1. Added statement.getSourceNumber() for accessing the line number of a statement within its source file.
  2. Added statement.getPc() for accessing the offset of a statement within its method (including 0-length ones).
  3. Provided access to a method's exception info:
    • Added method.getExceptionHandlers().
    • Added ExceptionHandler class for accessing info in exception handlers.
    • Added method.toThrowsTypes() for accessing the exceptions specified in a method's throws clause.

Modifying code:

  1. Enhanced profile to work on programs that exit with a call to System.exit.
  2. Enhanced JTrek to write the attribute com.compaq.JTrekCreated when it creates a classfile, and to report in trek.log when it scans an already instrumented classfile.
  3. Broadened passStack support:
    • Enhanced passStack() to support invoke* and monitor*.
    • Added passStack(descriptor) to support instructions with untyped stack arguments, like dup.
    • Clarified documentation to indicate that doing passStack() for an instruction with no stack arguments is a noop.
  4. Added support for passing the insert point object of invoke's.
  5. Added methodref.redirect for doing method-level instrumentation by redirection.
  6. Added classfile.addInterface for adding interfaces to a classfile.
  7. Clarified how system classes are handled and added the boolean field Call.systemMethodsSafe to control this.

Other changes:

  1. Deleted demo directory from kit, and instead put all JTrek source files within src under the JTrek install directory.
  2. Added a PrintWriter version of trek.setLogStream and made PrintWriter the data type of RunLog's textStream field.
  3. Enhanced Code and Instruction classes to transparently support the wide instruction. For example,  instruction.getOpcode() for a wide instruction returns the underlying opcode (e.g. astore or iinc).
  4. Enhanced dump to show bytecode offset of each statement when -inc's arguments include both s(ource) and a(ttributes), but not i(nstructions).

Between V1.0 and T1.1

Accessing code objects:

  1. Enabled variable references to include method references (as well as field and local variable references).
  2. Added trek.getObject(variable ref, inst/stmt) to give easy access to the code objects accessible at a specific point in a program.
  3. Provided access to constant pool entries:
    • Added classfile.firstXxxRef() for initiating constant pool scans.
    • Added xxxRef classes for accessing the value constants and object references in a classfile's constant pool.
  4. Added instruction.getReferenceArg() to give a JVM-level view of what instructions actually manipulate. Amongst other things, this facilitates inserting an instruction that works on a code object used in another instruction.

Modifying code:

  1. Added the Code class to allow the insertion of arbitrary instructions into a program.
  2. Added Local(name, object, method) to allow usage of created local variables when inserting code.
  3. Added statement.delete(change ID) and instruction.delete(change ID) to allow code (such as debugging assertions) to be removed from a program.
  4. Added notion of change IDs, plus statement.hasChange(change ID) and statement.undoChange(change ID), to enable easy manipulation of already inserted calls and code.
  5. In call.pass(variable ref), the variable reference may now be a method whose return type is void. When this is done, the string "<Side Effects>" is the value that is actually passed.
  6. Added field Call.systemMethodsSafe and better documented the issues surrounding instrumentation of java. and sun. classes.

Manipulating classfiles:

  1. Added classfile.refresh() so that the in-memory representation of a classfile in a trek could be updated if the underlying file is later recompiled.
  2. Added ClassFile.read(instream, trek) and classfile.write(outstream, doclean) to provide maximum flexibility in manipulating classfile data, such as interfacing with a ClassLoader.
  3. Added trek.findClassFile(name) to access in-memory classfiles. Also clarified which methods may throw an error when they cannot read a classfile whose data they need to accomplish their function.
  4. Made dump of constant pool more readable.

The watch application:

  1. Added -inc switch to allow user to log context info for a watchpoint, such as its thread and its call stack.
  2. Added trace-options to a method watch term to control what info is traced for the method.
  3. Allowed methods to be specified in a watch term's show-list.
  4. Modified watch runtime to handle hitting watchpoints in multiple threads.

Other changes:

  1. Added support for 1.2-style classpaths to -ip switch.
  2. Added instruction.getArrayLoad() to give access to the instruction that loaded the array being used by this array-element instruction.
  3. Added statement.canCall(method) to provide the run-time complement to statement.references(member).
  4. Added the RunLog constructor RunLog(sug, logtype) to allow an instrumentation class to specify the type of log.
  5. Added symbols for instruction opcodes (Code.*) and clarified which instructions have each instruction type.

Known Problems

  1. JTrek may misanalyze a code pattern or throw an error when it processes a code pattern that could not have resulted from legal source code.

    Note that using the Code and Call classes (and thus the watch and profile applications) can result in the creation of classfiles that contain such code patterns. Also note that trek.log will indicate which classfiles of a trek have already been modified by JTrek.