Description Ruth Lee 2005-02-16 22:49:24 EST

SOURCE OF THIS REQUIREMENT:
Development has opened this feature to track a known issue.

DESCRIPTION:
There are some issues about the instrumentation in eclipse:
1. Instrument once
2. Manual cleanup (especially of binary Java projects).

1. Instrument once
Instrumentation added by the probe BCI engine to .class files can be silently
removed. The problem is that the eclipse JDT "owns" the output folder of a Java
project, and thus any .class files in an output folder can be deleted and
recreated by the JDT javac builder. Which of the .class files is silently
recompiled depends on which build ran: only the file that changed (auto-build),
only the files that changed (build), and every file (rebuild). If a user has
instrumented a file, then that file should stay instrumented until the user
explicitly clicks an option to uninstrument it. Also, should the original .BAK
files be deleted after a build has run, since they've been replaced with the
newer .class file?

2. Manual cleanup
When the user has finished with instrumentation, she needs to manually clean up
the instrumented project. For source files that's not difficult (run a build),
but for JAR files she has to delete the instrumented JAR and manually rename the
.BAK file back to the original name. For binary Java projects, removing the
instrumentation also requires modifiying the project classpath and deleting the
class folder that was created.

Here's one option to fix the problem: A user could create a probe "working set"
of probe files with .class/.jar etc. files. The user could drag more than one
.probe file into a working set, and the instrumenter would silently concatenate
those files before instrumenting the .class/etc. with them. Once this working
set is created, the user can enable or disable the set, and if it's enabled then
the instrumenter listens for changes on the .class files. If they're changed,
then the instrumenter reinstruments the file. If the user disables the set, then
the instrumenter cleans up the .BAK files, classpaths, etc.

Some related thoughts from Allan (on the Instrument wizard):
1. You can instrument a class file that's already instrumented, and the
instrumentation will happen on top of what's already been done. Furthermore,
after doing this the BAK file is the once-instrumented version, not the
un-instrumented version. I think if there is a BAK file corresponding to a
selected class or jar file, the wizard should say "Do you want me to restore
from the BCK file first?"

EXPECTED RESULTS:
1. Some mechanism will exist to reinstrument the .class files if notification is
sent that the file was changed.
2. Some mechanism will exist to uninstrument the files and perform any necessary
cleanup if the user indicates that she wants to uninstrument the files.

RESULTS NOT SPECIFIED BY THIS FEATURE:
1. The feature does not attempt to design the UI. The option listed is for
illustration purposes only.