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:

  1. 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.
  2. 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 location’s method are logged.
  • Field-ref’s and method-ref’s 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 package’s 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 object’s class has no such method, Java will simply find the nearest ancestor class which does – like Object). If a class’s 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 object’s 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 location’s method, (2) a static member of the match location’s class, (3) a non-static member of the match location’s class if the match location’s method is not static, (4) the special name @, which means name-ref’s new value, (5) the special name @@, which means name-ref’s 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.