|
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:
- Added statement.getSourceNumber() for accessing the line
number of a statement within its source file.
- Added statement.getPc() for accessing the offset of a
statement within its method (including 0-length ones).
- 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:
- Enhanced profile to work on programs that exit with a call to System.exit.
- 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.
- 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.
- Added support for passing the insert point object of invoke's.
- Added methodref.redirect for doing method-level
instrumentation by redirection.
- Added classfile.addInterface for adding interfaces to a
classfile.
- Clarified how system classes are handled and added the boolean field Call.systemMethodsSafe
to control this.
Other changes:
- Deleted demo directory from kit, and instead put all JTrek source files
within src under the JTrek install directory.
- Added a PrintWriter version of trek.setLogStream and made
PrintWriter the data type of RunLog's textStream field.
- 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).
- 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:
- Enabled variable references to include method references (as well as field and local
variable references).
- Added trek.getObject(variable ref, inst/stmt)
to give easy access to the code objects accessible at a specific point in a program.
- 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.
- 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:
- Added the Code class to allow the insertion of arbitrary instructions into a program.
- Added Local(name, object, method) to allow usage of created
local variables when inserting code.
- Added statement.delete(change ID) and instruction.delete(change
ID) to allow code (such as debugging assertions) to be removed from a
program.
- 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.
- 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.
- Added field Call.systemMethodsSafe and better documented the issues
surrounding instrumentation of java. and sun. classes.
Manipulating classfiles:
- 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.
- Added ClassFile.read(instream, trek) and classfile.write(outstream,
doclean) to provide maximum flexibility in manipulating classfile data,
such as interfacing with a ClassLoader.
- 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.
- Made dump of constant pool more readable.
The watch application:
- Added -inc switch to allow user to log context info for a watchpoint,
such as its thread and its call stack.
- Added trace-options to a method watch term to control what
info is traced for the method.
- Allowed methods to be specified in a watch term's show-list.
- Modified watch runtime to handle hitting watchpoints in multiple
threads.
Other changes:
- Added support for 1.2-style classpaths to -ip switch.
- Added instruction.getArrayLoad() to give access to the
instruction that loaded the array being used by this array-element instruction.
- Added statement.canCall(method) to provide the
run-time complement to statement.references(member).
- Added the RunLog constructor RunLog(sug, logtype) to
allow an instrumentation class to specify the type of log.
- Added symbols for instruction opcodes (Code.*) and clarified which
instructions have each instruction type.
Known Problems
- 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.
|