public class Trace extends java.lang.Object
Traces the execution of a target program.
See http://fpl.cs.depaul.edu/jriely/visualization/
Command-line usage: java Trace [OptionalJvmArguments] fullyQualifiedClassName
Starts a new JVM (java virtual machine) running the main program in fullyQualifiedClassName, then traces it's behavior. The OptionalJvmArguments are passed to this underlying JVM.
Example usages:
java Trace MyClass java Trace mypackage.MyClass java Trace -cp ".:/pathTo/Library.jar" mypackage.MyClass // mac/linux java Trace -cp ".;/pathTo/Library.jar" mypackage.MyClass // windows
Two types of display are support: console and graphviz In order to use graphziv, you must install http://www.graphviz.org/ and perhaps call graphvizAddPossibleDotLocation to include the location of the "dot" executable.
You can either draw the state at each step --- drawSteps()
--- or
you can draw states selectively by calling Trace.draw()
from the program
you are tracing. See the example in ZTraceExample.java
.
Modifier and Type | Method and Description |
---|---|
static void |
addDrawingIncludePattern(java.lang.String value)
Add an include pattern for drawing.
|
static void |
addExcludePattern(java.lang.String value)
Add an exclude pattern.
|
static void |
addGraphvizIgnoredFields(java.lang.String value)
Do not display any fields with this name (default includes only
"$assertionsDisabled").
|
static void |
addPrefixOptionsForVm(java.lang.String value)
Prefix options for the debugger VM.
|
static void |
clearCallTree()
Clear the call tree, removing all previous entries.
|
static void |
consoleMaxArrayElementsObject(int value)
The maximum number of displayed elements when printing an object array on
the console (default==8).
|
static void |
consoleMaxArrayElementsPrimitive(int value)
The maximum number of displayed elements when printing a primitive array
on the console (default==15).
|
static void |
consoleMaxFields(int value)
The maximum number of displayed fields when printing an object on the
console (default==8).
|
static void |
consoleShow(boolean value)
Show events on the console (default==false).
|
static void |
consoleShowNestedArrayIds(boolean value)
Show object ids inside multidimensional arrays (default==false).
|
static void |
consoleShowTypeInObjectName(boolean value)
Show the object type in addition to its id (default==false).
|
static void |
consoleShowVerbose(boolean value)
Show events on the console, including code (default==false).
|
static void |
debug(boolean value)
Turn on debugging information (default==false).
|
static void |
draw()
Draw all stack frames and static variables, as well as all reachable
objects.
|
static void |
drawCallTree(boolean value)
When the debugged program ends, create a graphviz file showing the call tree (default==false).
|
static void |
drawObject(java.lang.Object object)
Draw the given object.
|
static void |
drawObjects(java.lang.Object... objects)
Draw the given objects.
|
static void |
drawObjectsWithNames(java.lang.Object... namesAndObjects)
Draw the given objects, labeling them with the given names.
|
static void |
drawObjectWithName(java.lang.String name,
java.lang.Object object)
Draw the given object, labeling it with the given name.
|
static void |
drawSteps()
Start drawing steps.
|
static void |
drawStepsEnd()
Stop drawing steps.
|
static void |
drawStepsOfMethod(java.lang.String methodName)
Create a new graphviz drawing for every step of the named method.
|
static void |
drawStepsOfMethods(java.lang.String... methodName)
Create a new graphviz drawing for every step of the named methods.
|
static void |
drawThisFrame()
Draw the current frame, as well as all reachable objects.
|
static void |
graphvizAddPossibleDotLocation(java.lang.String value)
Add a filesystem location to search for the dot executable that comes
with graphviz.
|
static void |
graphvizArrayArrowAttributes(java.lang.String value)
Graphviz style for an arrow from an array to an Object.
|
static void |
graphvizArrayBoxAttributes(java.lang.String value)
Graphviz style for an array.
|
static void |
graphvizCallTreeArrowAttributes(java.lang.String value)
Graphviz style for a call tree arrow.
|
static void |
graphvizCallTreeBoxAttributes(java.lang.String value)
Graphviz style for a call tree node.
|
static void |
graphvizFrameBoxAttributes(java.lang.String value)
Graphviz style for a frame.
|
static void |
graphvizFrameExceptionAttributes(java.lang.String value)
Graphviz style for an arrow from an exception to a frame.
|
static void |
graphvizFrameFrameArrowAttributes(java.lang.String value)
Graphviz style for an arrow from a frame to another frame.
|
static void |
graphvizFrameObjectArrowAttributes(java.lang.String value)
Graphviz style for an arrow from a frame to an Object.
|
static void |
graphvizFrameReturnAttributes(java.lang.String value)
Graphviz style for an arrow from a return value to a frame.
|
static void |
graphvizLabelArrowAttributes(java.lang.String value)
Graphviz style for arrow labels.
|
static void |
graphvizLabelBoxAttributes(java.lang.String value)
Graphviz style for box labels.
|
static void |
graphvizObjectArrowAttributes(java.lang.String value)
Graphviz style for an arrow from an object to an object.
|
static void |
graphvizObjectBoxAttributes(java.lang.String value)
Graphviz style for an object (non-array).
|
static void |
graphvizOutputFormat(java.lang.String value)
The graphviz format -- see http://www.graphviz.org/doc/info/output.html .
|
static void |
graphvizPutLineNumberInFilename(boolean value)
Include line number in graphviz filename (default==true).
|
static void |
graphvizRemoveGvFiles(boolean value)
Remove graphviz files for which graphic files have been successfully
generated.
|
static void |
graphvizRunGraphviz(boolean value)
Run graphviz "dot" program to produce an output file (default==true).
|
static void |
graphvizSetFieldAttribute(java.lang.String field,
java.lang.String attrib)
Set the graphviz attributes for all fields with the given name.
|
static void |
graphvizSetFrameAttribute(java.lang.Class<?> cz,
java.lang.String attrib)
Set the graphviz attributes for frames of the given class.
|
static void |
graphvizSetObjectAttribute(java.lang.Class<?> cz,
java.lang.String attrib)
Set the graphviz attributes for objects of the given class.
|
static void |
graphvizSetStaticClassAttribute(java.lang.Class<?> cz,
java.lang.String attrib)
Set the graphviz attributes for objects of the given class.
|
static void |
graphvizStaticClassArrowAttributes(java.lang.String value)
Graphviz style for an arrow from a static class to an object.
|
static void |
graphvizStaticClassBoxAttributes(java.lang.String value)
Graphviz style for a static class.
|
static void |
graphvizWrapperBoxAttributes(java.lang.String value)
Graphviz style for a wrapper object (in simple form).
|
static void |
main(java.lang.String[] args)
The debugger can be invoked from the command line using this method.
|
static void |
removeDrawingIncludePattern(java.lang.String value)
Add an include pattern.
|
static void |
removeExcludePattern(java.lang.String value)
Remove an exclude pattern.
|
static void |
run()
Run the debugger on the current class.
|
static void |
run(java.lang.Class<?> mainClass)
Run the debugger on the given class.
|
static void |
run(java.lang.Class<?> mainClass,
java.lang.String[] args)
Run the debugger on the given class.
|
static void |
run(java.lang.String mainClassName)
Run the debugger on the given class.
|
static void |
run(java.lang.String[] args)
Run the debugger on the current class.
|
static void |
run(java.lang.String mainClassName,
java.lang.String[] args)
Run the debugger on the given class.
|
static void |
runWithArgs(java.lang.Class<?> mainClass,
java.lang.String... args)
Run the debugger on the given class.
|
static void |
runWithArgs(java.lang.String mainClassName,
java.lang.String... args)
Run the debugger on the given class.
|
static void |
setConsoleFilename()
Sets the console output to the default (the terminal).
|
static void |
setConsoleFilename(java.lang.String filename)
Sets the console output to the given filename.
|
static void |
setConsoleFilenameRelativeToUserHome(java.lang.String filename)
Sets the console output to the given filename.
|
static void |
setGraphizOutputDir(java.lang.String dirName)
Sets the graphviz output directory.
|
static void |
showBuiltInObjects(boolean value)
Show String, Integer, Double, etc as simplified objects (default==false).
|
static void |
showBuiltInObjectsVerbose(boolean value)
Show String, Integer, Double, etc as regular objects (default==false).
|
static void |
showFieldNamesInLabels(boolean value)
In graphviz, show field name in the label of an object (default==true).
|
static void |
showFilenamesOnConsole(boolean value)
Show file names on the console (default==false).
|
static void |
showFrameNumbers(boolean value)
In graphviz, show stack frame numbers (default==true).
|
static void |
showNullFields(boolean value)
In graphviz, show null fields (default==true).
|
static void |
showNullVariables(boolean value)
In graphviz, show null variabels (default==true).
|
static void |
showObjectIds(boolean value)
In graphviz, show object ids (default==false).
|
static void |
showOuterClassInClassName(boolean value)
Include fully qualified class names (default==false).
|
static void |
showPackageInClassName(boolean value)
Show fully qualified class names (default==false).
|
static void |
showSyntheticFields(boolean value)
Show fields introduced by the compiler (default==true);
|
static void |
showSyntheticMethods(boolean value)
Show methods introduced by the compiler (default==true);
|
public static void drawObject(java.lang.Object object)
public static void drawObjectWithName(java.lang.String name, java.lang.Object object)
public static void drawObjects(java.lang.Object... objects)
public static void drawObjectsWithNames(java.lang.Object... namesAndObjects)
public static void drawThisFrame()
public static void drawStepsEnd()
public static void drawSteps()
public static void draw()
public static void clearCallTree()
public static void graphvizRunGraphviz(boolean value)
public static void graphvizOutputFormat(java.lang.String value)
public static void setGraphizOutputDir(java.lang.String dirName)
public static void setConsoleFilenameRelativeToUserHome(java.lang.String filename)
(user home directory)/(filename)
public static void setConsoleFilename(java.lang.String filename)
public static void setConsoleFilename()
public static void drawStepsOfMethod(java.lang.String methodName)
public static void drawStepsOfMethods(java.lang.String... methodName)
public static void consoleShow(boolean value)
public static void consoleShowVerbose(boolean value)
public static void showBuiltInObjects(boolean value)
public static void showBuiltInObjectsVerbose(boolean value)
public static void run()
public static void run(java.lang.String[] args)
public static void run(java.lang.String mainClassName)
public static void run(java.lang.Class<?> mainClass)
public static void run(java.lang.String mainClassName, java.lang.String[] args)
public static void run(java.lang.Class<?> mainClass, java.lang.String[] args)
public static void runWithArgs(java.lang.Class<?> mainClass, java.lang.String... args)
public static void runWithArgs(java.lang.String mainClassName, java.lang.String... args)
public static void main(java.lang.String[] args)
public static void addPrefixOptionsForVm(java.lang.String value)
public static void debug(boolean value)
public static void addExcludePattern(java.lang.String value)
com.sun.jdi.request.WatchpointRequest
. The default exclude
patterns include:
"*$$Lambda$*" "java.*" "jdk.*" "sun.*" "com.*" "org.*" "javax.*" "apple.*" "Jama.*" "qs.*" "stdlib.A*" "stdlib.B*" "stdlib.C*" "stdlib.D*" "stdlib.E*" "stdlib.F*" "stdlib.G*" "stdlib.H*" "stdlib.I*" "stdlib.J*" "stdlib.K*" "stdlib.L*" "stdlib.M*" "stdlib.N*" "stdlib.O*" "stdlib.P*" "stdlib.Q*" "stdlib.R*" "stdlib.S*" "stdlib.U*" "stdlib.V*" "stdlib.W*" "stdlib.X*" "stdlib.Y*"The JDI excludes classes, but does not allow exceptions. This is the reason for the unusual number of excludes for
stdlib
. It is important that
stdlib.Trace
not be excluded --- if it were, then callBacks
to Trace.draw
would not function. As a result, all classes in stdlib
that start with a letter other than T
are excluded.
Be careful when adding classes to stdlib
.
Exclude patterns must include
"*$$Lambda$*" "java.*" "jdk.*" "sun.*"otherwise the Trace code itself will fail to run.
public static void removeExcludePattern(java.lang.String value)
addExcludePattern
public static void addDrawingIncludePattern(java.lang.String value)
"java.util.*"
public static void removeDrawingIncludePattern(java.lang.String value)
addDrawingIncludePattern
public static void drawCallTree(boolean value)
public static void graphvizCallTreeBoxAttributes(java.lang.String value)
public static void graphvizCallTreeArrowAttributes(java.lang.String value)
public static void graphvizArrayBoxAttributes(java.lang.String value)
public static void graphvizArrayArrowAttributes(java.lang.String value)
public static void graphvizFrameBoxAttributes(java.lang.String value)
public static void graphvizFrameObjectArrowAttributes(java.lang.String value)
public static void graphvizFrameReturnAttributes(java.lang.String value)
public static void graphvizFrameExceptionAttributes(java.lang.String value)
public static void graphvizFrameFrameArrowAttributes(java.lang.String value)
public static void graphvizObjectBoxAttributes(java.lang.String value)
public static void graphvizWrapperBoxAttributes(java.lang.String value)
public static void graphvizObjectArrowAttributes(java.lang.String value)
public static void graphvizStaticClassBoxAttributes(java.lang.String value)
public static void graphvizStaticClassArrowAttributes(java.lang.String value)
public static void graphvizLabelBoxAttributes(java.lang.String value)
public static void graphvizLabelArrowAttributes(java.lang.String value)
public static void graphvizAddPossibleDotLocation(java.lang.String value)
public static void graphvizRemoveGvFiles(boolean value)
public static void showPackageInClassName(boolean value)
public static void showOuterClassInClassName(boolean value)
public static void consoleShowTypeInObjectName(boolean value)
public static void consoleMaxFields(int value)
public static void consoleMaxArrayElementsPrimitive(int value)
public static void consoleMaxArrayElementsObject(int value)
public static void consoleShowNestedArrayIds(boolean value)
public static void showSyntheticFields(boolean value)
public static void showSyntheticMethods(boolean value)
public static void showFilenamesOnConsole(boolean value)
public static void showFieldNamesInLabels(boolean value)
public static void showObjectIds(boolean value)
public static void showFrameNumbers(boolean value)
public static void showNullFields(boolean value)
public static void showNullVariables(boolean value)
public static void graphvizPutLineNumberInFilename(boolean value)
public static void addGraphvizIgnoredFields(java.lang.String value)
public static void graphvizSetObjectAttribute(java.lang.Class<?> cz, java.lang.String attrib)
public static void graphvizSetStaticClassAttribute(java.lang.Class<?> cz, java.lang.String attrib)
public static void graphvizSetFrameAttribute(java.lang.Class<?> cz, java.lang.String attrib)
public static void graphvizSetFieldAttribute(java.lang.String field, java.lang.String attrib)