org.eclipse.hyades.probekit
Class ProbeInstrumenterDriver

java.lang.Object
  org.eclipse.hyades.probekit.ProbeInstrumenterDriver

public class ProbeInstrumenterDriver
extends java.lang.Object

This class exports an API that you can use to instrument class files and jar files on disk. Use cmdLineMain to pass command-line options and have errors reported to standard error using System.err.println.

Otherwise use instrumentItems() to pass a File object which refers to the saved BCI engine script from the probe compiler, and one or more File objects referring to files that you want to process. If a File object refers to a directory, all *.class and *.jar files (and *.war and *.ear) in that directory and its subdirectories, recursively, will be processed. "Processing" a file means rewriting the class or jar file in place with an instrumented verison of itself.

When using instrumentItems, error reports from the native executable are collected into an array of Strings and you can get them using getErrorStrings(). If any run of the native executable exits with a nonzero exit code, then the return value from instrumentItems will be nonzero. Instrumenter problems in one file don't prevent the continued processing of other files. If there are other problems (unrecoverable problems like an inability to run the instrumenter at all), they are reported by throwing an exception.

You can optionally call setExePath before calling instrumentItems, to give the full path to the native probeinstrumenter program. If you don't call setExePath and you are calling this code from an Eclipse plugin, the Probekit plugin's location and the current OS and Arch values are used to find the directory containing the native executable.

The actual byte-code instrumentation is done with a native executable. If you use this as a "main" program from the command line, the native executable "probeinstrumenter" should appear on your PATH, such that Runtime.exec can find it. If you use this as a plug-in, the logic in SetExePathFromPlugin will find the native executable relative to the plugin directory, in this subdirectory of the plugin's directory: os/$os$/$arch$/probeinstrumenter (with a .exe suffix on Windows).

Nested Class Summary

static class

ProbeInstrumenterDriver.StaticProbeInstrumenterException The exception type this subsystem can throw.

Constructor Summary

ProbeInstrumenterDriver()

Method Summary

static int	cmdLineMain(java.lang.String[] args) accepts command-line arguments and processes them.
int	getErrorCount() Returns the current error status value for the instrumenter driver.
java.lang.String[]	getErrorStrings() Return an array of strings describing errors that occurred during instrumentItems.
int	instrumentItems(java.io.File i_scriptFile, java.lang.String[] items, boolean saveBackups) This is the main API method for this subsystem: use it to instrument class files and jar files, including recursive operations on directories.
int	instrumentItems(java.io.File i_scriptFile, java.lang.String[] items, boolean saveBackups, boolean useJava6Verifier) This is the main API method for this subsystem: use it to instrument class files and jar files, including recursive operations on directories.
void	setExePath(java.lang.String s) Set the path and file name to use for the native instrumentation executable.
void	setVerbose(boolean f) The "verbose" flag, when true, results in output on System.out at major points in processing.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ProbeInstrumenterDriver

public ProbeInstrumenterDriver()

Method Detail

cmdLineMain

public static int cmdLineMain(java.lang.String[] args)

accepts command-line arguments and processes them. Errors are written to System.err.

First argument must be a probe script file name. Subsequent arguments are class file, jar file, or directory names to process. Errors are written using System.err.println(). Return value is zero if no errors, nonzero for any errors. TODO: we don't check the already-instrumented state and leave instrumented classes alone. TODO: consider detecting instrumented files and reinstrumenting from *.bak files.

Parameters:

args - the arguments: an engine script, and a list of class file, jar file, and directory names

Returns:

zero for no error, nonzero for any error. Errors are also reported to System.err.

getErrorCount

public int getErrorCount()

Returns the current error status value for the instrumenter driver.

Returns:

the error status

setVerbose

public void setVerbose(boolean f)

The "verbose" flag, when true, results in output on System.out at major points in processing. Default is false.

Parameters:

f -

setExePath

public void setExePath(java.lang.String s)

Set the path and file name to use for the native instrumentation executable. The format of the argument should be such that System.exec will accept it and run the native executable. For example, on Windows the ".exe" suffix is required. If the argument is a plain file name with no path information, it means the executable must be found on the user's PATH.

Parameters:

s - the fully-qualified path and file name of the "probeinstrumenter" executable.

getErrorStrings

public java.lang.String[] getErrorStrings()

Return an array of strings describing errors that occurred during instrumentItems.

Returns:

an error strings

instrumentItems

public int instrumentItems(java.io.File i_scriptFile,
                           java.lang.String[] items,
                           boolean saveBackups)
                    throws ProbeInstrumenterDriver.StaticProbeInstrumenterException

This is the main API method for this subsystem: use it to instrument class files and jar files, including recursive operations on directories. Errors in one item don't stop processing of other items. After using this method, use getErrorStatus() and getErrorStrings() to find out how it went.

Parameters:

scriptFile - a File that refers to the engine script file to use

items - each string should be a class file name, a jar file name, or a directory name.

saveBackups - true if you want this code to rename original class and jar files to *.bak - otherwise they'll be lost completely.

Throws:

ProbeInstrumenterDriver.StaticProbeInstrumenterException - for serious errors.

instrumentItems

public int instrumentItems(java.io.File i_scriptFile,
                           java.lang.String[] items,
                           boolean saveBackups,
                           boolean useJava6Verifier)
                    throws ProbeInstrumenterDriver.StaticProbeInstrumenterException

This is the main API method for this subsystem: use it to instrument class files and jar files, including recursive operations on directories. Errors in one item don't stop processing of other items. After using this method, use getErrorStatus() and getErrorStrings() to find out how it went.

Parameters:

scriptFile - a File that refers to the engine script file to use

items - each string should be a class file name, a jar file name, or a directory name.

saveBackups - true if you want this code to rename original class and jar files

useJava6Verifier - set to true to use the new java6 verifier. to *.bak - otherwise they'll be lost completely.

Throws:

ProbeInstrumenterDriver.StaticProbeInstrumenterException - for serious errors.

Provisional API: This API is subject to change in the next release.