The BCEL-builder module

Java 5 support

The best way to see how it works is look in the testcases. The only feature that is definetly not implemented yet is package level annotations. What is working is:

• You can ask a type: are you an annotation type? are you an enum type?
• You can ask a method: were you defined with varargs? Are you a bridge method?
• All annotation values types are supported (primitive, string, array, enum, annotation, class).
• Runtime visible and invisible annotations are supported.
• Annotations are accessible on types, methods, fields.
• Parameter annotations are accessible on methods.
• You can programmatically construct annotations and attach them to types, methods, fields.
• You can construct parameter annotations and add them to methods.
• The EnclosingMethod attribute is supported (it is used to let you know the containing method for local/anonymous types)
• The LocalVariableTypeTable attribute is supported (used for generics to tell you the original variable signature)

All this is implemented without using any Java 5 APIs.

There are a number of new TODO type tags in the code that may prove useful:

• J5SUPPORT: Marks places where BCEL has been changed for 1.5 (might have missed a couple...)
• BCELBUG: Marks things that might be BCEL problems that I came across
• J5TODO: Marks either a missing bit of implementation (hopefully corner case) or an optimization we could make

The contents of this directory are:

• This file
• src -- contains the source for BCEL, a modified variant of BCEL 5.1 that includes bug fixes and Java 5 support
• testsrc -- JUnit test cases for the Java 5 support
• testdata -- Java5 testcode that can be built using the build.xml script in the testdata directory (see note on this below)
• build.xml -- an ant script for manipulating the src folder, possibly useful if ever merging a base BCEL version

Development Process

We can now follow normal TDD for this. Add a JUnit testcase to the testsrc folder, plus any associated test materials into the testdata directory. Then change BCEL to get your test passing, when you are happy with the result (i.e. all the tests in the bcel-builder module are passing), you should execute the build.xml script whose default target will package up bcel (and bcel src) and deliver it into the lib module, the rest of AspectJ is driven off the version of bcel in the lib/bcel folder - it is *not* driven off the bcel-builder code (we could choose to change that sometime later).

Once you have done this execute all the tests for AspectJ, if they all pass you can check in your mods for bcel-builder and to the lib project.

testdata

The old stuff...

And pretty much nothing else. Well, then, what do you do with this directory? Well, the whole point is to generate bcel/bcel.jar in the lib package. To do so, first stick bcel-5.1-src.zip in this directory, then run ant. (at one point, this was available at http://archive.apache.org/dist/jakarta/bcel/source/bcel-5.1-src.zip) After much unzipping, patching, and compiling, you should get an appropriate bcel.jar file. Now put it in the appropriate place.

If there's something wrong with the bcel.jar in the lib project, well, then you've got some development to do. You'll need to know some more ant targets. But before anything, get that bcel-5.1-src.zip and stick it in this directory. NOTE: You should be working on BCEL when the package names are org.aspectj.apache.bcel, and *not* when the package names are org.apache.bcel. If you run the extractAndPatch task below, you will be left with a src folder in the correct state for further development.

There are five top-level ant targets apart from the usual "clean":

• ant extractAndPatchAndJar -- this is just the composition of the extract, jar and srcjar targets, and is the default. It extracts the source from bcel-5.1-src.zip, patches it, renames the files to start org.aspectj.apache rather than org.apache then compiles the patched version into a jar and drops the new archives: bcel.jar and bcel-src.zip, into the project root. This is the default task, mainly used to sanity check the building and make sure we're generating something. The bcel.jar and bcel-src.zip generated should be the same as that in ..\lib\bcel\.
• ant extractAndPatch -- this extracts the source from bcel-5.1-src.zip, patches it, renames the files to start org.aspectj.apache rather than org.apache then copies the patched source into the project src directory, there to be visible by eclipse for people to do development on it. For the patch file to be applied you need to have a patch.exe on your path, this bcel building process was tested with the version from cygwin.
• ant jar -- this copies the edited source from the project source directory and jars it up into bcel.jar, there to be tested.
• ant srcjar -- this copies the edited source from the project source directory and jars up the source code into bcel-src.zip.
• ant push -- this pushes the new bcel.jar and bcel-src.zip into ..\lib\bcel\. - ready to be used by the greater compiler.
• ant diff -- this creates the patch.txt file, composed of the differences between the project src directory and the original bcel-5.1 source. In order to create the patch, we transform the packages back to org.apache from org.aspectj.apache. To continue working on BCEL once you have done this, you might need to run the transformToAJ task to switch the packages back to the AJ prefix. For the patch file to be built successfully you need to have a diff.exe on your path, this bcel building process was tested with the version from cygwin.
• ant transformToAJ - this changes the packages for the BCEL classes to org.aspectj.apache from org.apache. This is used by the extractAndPatch task above.
• ant transformFromAJ - this changes the packages for the BCEL classes to org.apache from org.aspectj.apache. This is used by the diff task.

All of the tasks are destructive, so don't do "ant extract", for example, if you have anything in the project source directory you care about.