|
watch application
Instruments a program to display code and data tracing information. You control what is
traced via the watch command line, which is described below. (Note: you cannot instrument
contructors in the java. and sun. classes).
After the program has been instrumented, you can now do tracing runs:
- Whenever you run the instrumented program, specify a classpath that includes the
directory used in the -op switch (if any) and the JTrek kit directory.
- After the program is run, the gathered tracing data will be in the current directory, in
the text file watch.log.
watch command line
The command line of the watch application is: base-classes watchlist [watch
and common switches]. (Note: some JVMs expand a watchlist
of xxx* to the files in the current directory that match this
pattern. To workaround this, add a semi-colon to it or quote it)
A watchlist is one or more watch terms separated by semi-colons. This
argument is used to identify what to watch. An individual watch term may always be a name-ref. If it identifies a variable, it may
also be name-ref:show-list or name-ref::condition or name-ref:show-list:condition.
If it identifies a method, it may also be name-ref:::trace-options. .
The switches defined by the watch application are:
-cs
The terms in watchlist are matched with names in the program using a
case-sensitive comparison. If this switch is omitted, the matching is case-insensitive.
This switch does not affect conditions in a watchlist. Names in conditions
must exactly match the variables they are intended to identify.
-inc optionlist
If this switch is omitted, no context info is logged for watchpoints. Optionlist
can be one or more of the letters a, e, h, s, and t.
The specified sorts of context info will be logged each time a watchpoint is hit.
If e or any other option is specifed, the entry into and exit from the
watchpoint's method will be logged. If a is specifed, the arguments and
return value of the watchpoint's method will be logged. If h is specifed,
the thread in which the watchpoint was hit will be logged. If s is
specifed, the call stack of the watchpoint's method will be logged. If t
is specifed, the instance fields of the watchpoint's class will be logged (assuming it is
in an instance method).
-quiet
If this is switch is omitted, a message is output each time a condition cannot be applied
at a match location. If this switch is specified, such messages are not output.
A name-ref may be of the form field-ref ,
method-ref() , or method-ref ().wild-string. The last form is
used to identify local variables within the specified method.
- If name-ref identifies a method, the watch application traces calls
to the method. It logs entry into and exit from the method, plus whatever trace-options
are specified.
- If name-ref identifies a field or local variable, the watch
application inserts code in the program at each location where the specified variable is
assigned a value. When the program is run, the inserted code causes changes to the
specified variable to be logged. Also calls to and returns from the match locations
method are logged.
- Field-refs
and method-refs are of the form wild-string
or class-name.wild-string.
- A wild-string may be *, string, *string,
string*, or *string*. These respectively match any name, names
that are the same as string, names that end with string, names
that start with string, and names that contain string.
- A class-name may omit the leftmost terms of its packages name. For
example, String.equal*() would match methods starting with equal in packages
other than java.lang, whereas java.lang.String.equal*() would match only java.lang.String.equals().
Similarly profileLog.end*().*ream would match stream in profileLog.endTrek().
- If a watched variable is an object or array, toString() is used to get its value.
(Of course, if the objects class has no such method, Java will simply find the
nearest ancestor class which does like Object). If a classs toString()
is not coded to handle all contexts in which it could be used, an exception may result. If
such an exception occurs, the watch application will intercept it (if the program
does not intercept it sooner) and fallback to using Object.toString() to get the
objects value. When Object.toString() is used, it outputs encoded data
type@address for the watched variable.
- If a watched variable is an array, code insertion and logging are done for each element
of the array, as well as the array itself.
- Because name-ref may include wildcarding, and does not have to include a
fully qualified class name, a watch term may actually identify several names. When you do
this, it is exactly the same as if you wrote out a similar watch term for each identified
name.
A show-list is a list of variable references,
separated by commas. A show-list allows you to display the values that these
things have each time the watchpoint is hit. A variable reference is of the form name[.name...name].
- The leftmost name may be: (1) a local variable defined in the match
locations method, (2) a static member of the match locations class, (3) a
non-static member of the match locations class if the match locations method
is not static, (4) the special name @, which means name-refs
new value, (5) the special name @@, which means name-refs
object if name-ref is a non-static field, or (6) /each-package-piece/class/name,
which means a static member of the specified class.
- As in normal Java source code, a subsequent name in a variable reference must be a
member field of the name preceding it.
- A member name may be a method reference. This causes the
return value of the method to be shown unless the method is void. In that
case, "<Side Effects>" is shown instead. Conversely it is
when a method has interesting side effects (like printing something) that you might want
to do this.
- A method reference is of the form: method-name(0 or more arguments
separated by commas). An argument may itself be a variable
reference, or it may be a constant. String constants are enclosed in quotes ("),
boolean constants are either false or true, and long,
float, and double constants must respectively end with L,
F, and D.
A condition allows you to further refine what is
logged. A change to a variable is logged only if condition is true at the
time of the change. However if the condition is not valid at a match location, the
watchpoint is not inserted there at all. A condition can be invalid because you entered
the condition improperly or because the context say a local variable definition
does not exist at this match location. A condition consists of variable-ref
opr value.
- Value
may be a variable reference, a string value, or an integer value. Value
should be enclosed in single quotes () if it is a String value.
- Opr
may be == (or just =), !=, {, }, {=,
or }=. However for non-numeric comparisons, it must be == or !=.
These respectively mean equal, not equal, less than, greater than, less than or equal, and
greater than or equal.
- The data type of variable-ref must match the data type of value.
However byte, char, and short variables are viewed as having a data
type of int.
A trace-options value can be one
or more of the letters a, c, n, and t.
It controls what kind of logging code is inserted into the method being traced. If
a trace-options value is omitted, it defaults to c.
- If a is specified, the method's arguments and return value will be
logged.
- If c is specified, the method's control actions will be logged. Control
actions are things like loop iterations, switches, and if tests.
- If n is specified, the method's assignment statements will be logged.
- If t is specifed, the instance fields of the watchpoint's class will be
logged (assuming the method being traced is an instance method).
Example watch command
java watch dec.trek.Trek next();ClassFile.size::@}10000 sc pkg
would insert watch points into the Trek package itself. It would insert code to
watch:
- Each next() method in the scope of the trek.
- Each location where the field ClassFile.size is changed to a value greater than
10000.
|