Class dec.trek.RunLog

The RunLog class provides services you can use in your instrumentation methods to log the information being collected.

Method Summary

The coding and run-time steps to use RunLog in your instrumentation class are as follows.

  • When you initialize your instrumentation class, create a RunLog object.
  • When you write log entries, use RunLog's entry-writing methods. You create an entry by calling writeItem for each data item in the entry and then calling writeEntry when you have output all its items. (For an all-text entry, you can also call writeEntry(string) instead of writeItem(string) plus writeEntry()).
  • When you are done logging, call closeLog. Note that this will happen when the RunLog object is finalized, in any event.
  • When you run an instrumented program, insure RunLog.class and RunLogSink.class are accessible via the current classpath.

The actual log is owned by the class that is supplying the RunLogSink interface. By default, that is the RunLog class itself. To set the RunLogSink supplier to a different class, set the RunLogSink property to the qualified name of the desired class. This is done on the JVM command line used to run the instrumented program. For example, for the JVM java, this is done via: -DRunLogSink=class-name

A log can be defined as a text log or as a data log.

  • A text log encodes items as text according to the default character-to-byte converter in your JVM.
  • A data log encodes each item as a log-item-type byte plus the DataOutputStream-conformant value of the item.

Nominally "text log or data log" makes no difference to your instrumentation class because writeItem and writeEntry support both kinds of logs. However there may be "little things" you want to do differently for the two cases. For example, for a text log you might want to output an entry that contains column headers, while for a data log you do not. Call getLogType if you need to output different stuff for text and data logs.

If your instrumentation class subclasses RunLog, you can define additional log item types and the methods to support them. More specifically, you would define item codes starting at RunLog.ITEM_EXTEND and define writeItem methods for each new item type. The basic model for a writeItem method is:

  if (logType==LOG_TEXT)
    textStream.print(item);
  else {
    dataStream.writeByte(ITEM_XXX);
    dataStream.writeXxx(item);
  }

Fields

protected boolean active

Field you can use to prevent infinite recursion when you have instrumented a method that your instrumentation class calls. To use active, put the following code in each method that can call an instrumented method: (1) Check if it is true on entry (2) If it is, return; if not, set it to true (3) Set it to false at the end of the method.

protected DataOutputStream dataStream

If you create a writeItem method, do dataStream.writeXxx() to write to a data log.

public static int sysInited

If you instrument JDK methods, you should set this field to 1 after you have initialized your instrumentation class.

protected PrintWriter textStream

If you create a writeItem method, textStream.printXxx() to write to a text log.

Methods

public RunLog(String sug)

This is equivalent to RunLog(sug, RunLog.LOG_DEFAULT).

public RunLog(String sug, int logtype)

Creates a RunLog object, and passes the specified name suggestion and log type to the RunLogSink object that owns the log.

Parameters:

sug – a suggested name for the log. For example, when RunLog is the log's owner, it creates a file log named current-directory/sug (or sug.log if there is no file extension in sug).

logtype – tells the log owner the type of log to create. RunLog.LOG_TEXT says create a text log. RunLog.LOG_DATA says create a data log. RunLog.LOG_DEFAULT tells the owner to create the type that it prefers.

public void closeLog()

Closes the log.

public int getLogType()

Returns the log's type.

If the log is a text log, it returns RunLog.LOG_TEXT. If the log is a data log, it returns RunLog.LOG_DATA.

public void writeEntry()

Terminates the current log entry.

public void writeEntry(String val)

Outputs a String value to the log and then terminates the current log entry.

Parameters:

val – the String value to output

public void writeItem(boolean val)

Outputs a boolean value to the log.

Parameters:

val – the boolean value to output

public void writeItem(boolean val, int left, int width)

Outputs a boolean value to the log. When the log is a text log, it uses left and width to control how val is converted to a string: it puts left spaces before the value and uses width characters for the value. For example, writeItem(true, 1, 6) would output " true  " to a text log.

Parameters:

val – the boolean value to output

left – the number of spaces to put before the value

width – the number of characters to use for the value

public void writeItem(Date val)

Outputs val.getTime() to a data log and val.toString() to a text log.

Parameters:

val – the Date value to output

public void writeItem(Date val, int left, int width)

Outputs a Date value to the log. When the log is a text log, it uses left and width to control how val is represented: it puts left spaces before the value and uses width characters for the value.

Parameters:

val – the Date value to output

left – the number of spaces to put before the value

width – the number of characters to use for the value

public void writeItem(double val)

Outputs a double value to the log

Parameters:

val – the double value to output

public void writeItem(double val, int whole, int frac)

Outputs a double value to the log. When the log is a text log, it uses whole and frac to control how val is converted to a string: it uses whole characters for the whole-number part of the value (blank padding on the left as necessary) and frac characters for the rounded fractional part of the value. For example, writeItem(3.67, 2, 1) would output " 3.7" to a text log.

Parameters:

val – the double value to output

whole – the number of characters to use for the whole part of the value

frac – the number of characters to use for the fractional part of the value

public void writeItem(float val)

Outputs a float value to the log

Parameters:

val – the float value to output

public void writeItem(float val, int whole, int frac)

Outputs a float value to the log. When the log is a text log, it uses whole and frac to control how val is converted to a string: it uses whole characters for the whole-number part of the value (blank padding on the left as necessary) and frac characters for the rounded fractional part of the value.

Parameters:

val – the float value to output

whole – the number of characters to use for the whole part of the value

frac – the number of characters to use for the fractional part of the value

public void writeItem(int val)

Outputs an int value to the log

Parameters:

val – the int value to output

public void writeItem(int val, int width)

Outputs an int value to the log. When the log is a text log, it uses width characters for the number (blank padding on the left as necessary).

Parameters:

val – the int value to output

width – the number of characters to use for the value

public void writeItem(long val)

Outputs a long value to the log

Parameters:

val – the long value to output

public void writeItem(long val, int width)

Outputs a long value to the log. When the log is a text log, it uses width characters for the number (blank padding on the left as necessary).

Parameters:

val – the long value to output

width – the number of characters to use for the value

public void writeItem(String val)

Outputs a String value to the log.

Parameters:

val – the String value to output

public void writeItem(String val, int left, int width)

Outputs a String value to the log. When the log is a text log, it uses left and width to control how val is represented: it puts left spaces before the value and uses width characters for the value.

Parameters:

val – the String value to output

left – the number of spaces to put before the value

width – the number of characters to use for the value

Methods from RunLogSink interface

This section describes RunLog's implementation of the RunLogSink interface.

(A different implementation could have different behavior. For example, its open method might implement a data log and return RunLog.LOG_DATA. Even radical differences are possible. You could  make multiple applications share the same log by implementing a RunLogSink that uses sockets to talk to the process that actually owns the shared log).

public void close()

Closes the actual log.

public int open(String sug, RunLog log)

Opens a file log  named current-directory/sug.log, and returns the type of log created. If RunLog.LOG_DEFAULT was passed to RunLog, RunLog.LOG_TEXT is returned.

Parameters:

sug – a suggestion for the name of the log

log – the current RunLog object (could be used by a RunLogSink to access RunLog's writeXxx methods)

public void write(byte [] entry)

Writes the specified byte array to the log.

Parameters:

entry – the byte array to output