1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html> <head>
<title>The BCEL-builder module</title>
</head>
<body>
<h1>The BCEL-builder module</h1>
This module includes a modified form of BCEL - with some fixes in *and* support for Java5.
<hr>
<h3>Java 5 support</h3>
<p>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:</p>
<ul>
<li>You can ask a type: are you an annotation type? are you an enum type?</li>
<li>You can ask a method: were you defined with varargs? Are you a bridge method?</li>
<li>All annotation values types are supported (primitive, string, array, enum, annotation, class).</li>
<li>Runtime visible and invisible annotations are supported.</li>
<li>Annotations are accessible on types, methods, fields.</li>
<li>Parameter annotations are accessible on methods.</li>
<li>You can programmatically construct annotations and attach them to types, methods, fields.</li>
<li>You can construct parameter annotations and add them to methods.</li>
<li>The EnclosingMethod attribute is supported (it is used to let you know the containing method for local/anonymous types)</li>
<li>The LocalVariableTypeTable attribute is supported (used for generics to tell you the original variable signature)</li>
</ul>
<p>All this is implemented without using any Java 5 APIs.</p>
<p>There are a number of new TODO type tags in the code that may prove useful:</p>
<ul>
<li>J5SUPPORT: Marks places where BCEL has been changed for 1.5 (might have missed a couple...)</li>
<li>BCELBUG: Marks things that might be BCEL problems that I came across</li>
<li>J5TODO: Marks either a missing bit of implementation (hopefully corner case) or an optimization we could make</li>
</ul>
<hr>
<p> The contents of this directory are:
</p>
<ul>
<li>This file</li>
<li>src -- contains the source for BCEL, a modified variant of BCEL 5.1 that includes bug fixes and Java 5 support</li>
<li>testsrc -- JUnit test cases for the Java 5 support</li>
<li>testdata -- Java5 testcode that can be built using the build.xml script in the testdata directory (see note on this below)</li>
<li>build.xml -- an ant script for manipulating the src folder, possibly useful if ever merging a base BCEL version</li>
</ul>
<hr>
<h3>Development Process</h3>
<p>
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).
<p>
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.
<hr>
<h3>testdata</h3>
The testdata folder includes a load of Java5 code, it needs to be built with a Java5 compiler. There
is an ant script in there (build.xml) that builds all the source code into a testcode.jar which is
then used by the testcases - so if you do change the testdata code then you should run build.xml
to rebuild testcode.jar.
<hr>
<h3>The old stuff...</h3>
Before the Java 5 support was added we maintained this module as basically a patch to apply against
a particular download of BCEL. Changes to BCEL are occurring more frequently than we integrate
a new version of BCEL so it made sense to make the patching process easier, so we have checked in
the modified source for BCEL.
The original instructions for patching BCEL in the old way are below...
<p> 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
<strong>bcel-5.1-src.zip</strong> in this directory, then run ant.
(at one point, this was available at
<a href="http://archive.apache.org/dist/jakarta/bcel/source/bcel-5.1-src.zip">
http://archive.apache.org/dist/jakarta/bcel/source/bcel-5.1-src.zip</a>)
After much unzipping, patching, and compiling, you should get an
appropriate bcel.jar file. Now put it in the appropriate place. </p>
<p> If there's something <em>wrong</em> 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
<strong>bcel-5.1-src.zip</strong> and stick it in this directory.
<b>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.</b>
</p>
<p> There are five top-level ant targets apart from the usual "clean":</p>
<ul>
<li>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\.
</li>
<li>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.
</li>
<li>ant jar -- this copies the edited source from the project source
directory and jars it up into bcel.jar, there to be tested.
</li>
<li>ant srcjar -- this copies the edited source from the project source
directory and jars up the source code into bcel-src.zip.
</li>
<li>ant push -- this pushes the new bcel.jar and bcel-src.zip into ..\lib\bcel\.
- ready to be used by the greater compiler.</li>
<li>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.
</li>
<li>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.
</li>
<li>ant transformFromAJ - this changes the packages for the BCEL classes to
org.apache from org.aspectj.apache. This is used by the diff task.
</li>
</ul>
<p> 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.
</p>
</body> </html>
|
