Instructions for BCEL Tool Demo/Exercise.

Written by Godmar Back, Jan 2007.

All files for this demo are in
http://people.cs.vt.edu/~gback/cs6304/bcel/
which you find on our machines in
/web/people/gback/cs6304/bcel

You need these files

    build.sh
    run.sh
    Example.java
    intercept/BCELInterceptor.java
    intercept/HashcodeInterceptor.java
    intercept/StringInterceptor.java
    bcel-5.2-patched.jar (*)

out of that directory.

You should check that you are using Sun's JDK 1.5 or 1.6
With the recent upgrade on the lab machines, paths have
been rearranged.  Use "which java" to check which one
you're using:

# which java
/usr/local/jdk1.6.0/bin/java

Add /usr/local/jdk1.6.0/bin to your path as appropriate.

To compile the files, run 
./build.sh

To run the example, do
./run.sh

You should see:
---
java.lang.Throwable: Strings are equal but != at 
        at intercept.StringInterceptor.cmp(StringInterceptor.java:6)
        at Example.main(Example.java:15)
Hello != Hello
java.lang.Throwable: Objects are equal but have unequal hashCodes (22710119 != 7306473)
        at intercept.HashcodeInterceptor.cmp(HashcodeInterceptor.java:17)
        at Example.main(Example.java:23)
---

Tasks.

0. Read Example.java

1. Use the commands

        jcf-dump -c Example.class
        jcf-dump -c Example-patched.class

   to examine the contents of the Example bytecode file,
   in the original and patched form. (**)

   Although the BCEL-based interceptor performs bytecode
   rewriting on the fly, it will leave a copy of the file
   it created in the directory.

   Find the instructions that the equals checker and 
   string checker had to change and see how they changed.

2. Extend intercept/BCELInterceptor.

   Implement a method that rewrites a program such that it
   announces whenever a new object is allocated, or whenever
   an instance field or a static field is written.
   (Hint: rewrite NEW, PUTFIELD, PUTSTATIC. Add new classes 
   to intercept/*)

   The BCEL API documentation is here:
   http://jakarta.apache.org/bcel/apidocs/overview-summary.html
   The manual is here:
   http://jakarta.apache.org/bcel/manual.html

   Play with it as much as you like.
   (maybe add announcements for local variable assignments?)

   Enjoy!

(*) This file is BCEL 5.2 with a small patch.
To build it, I downloaded from
http://www.eng.lsu.edu/mirrors/apache/jakarta/bcel/
the -src.zip file, extracted it, applied this patch: 
http://issues.apache.org/bugzilla/attachment.cgi?id=18930
and did an "ant jar"

(**) jcf-dump is part of GNU Java.
    javap -c Example
    javap -c Example-patched
are the Sun equivalents, but they are not as verbose.