Re: First push into ASM_4_FUTURE

Rémi Forax wrote:
> As a preparation work before introducing JSR292 new constant pool

we also need to add support for JSR 294 and JSR 308. The case of JSR 294 
is quite simple. Here are some proposed API changes for ASM 4.0, in 
order to support JSR 308 
(http://types.cs.washington.edu/jsr308/specification/java-annotation-design.html)

The API proposed here is designed from a user point of view (with ease 
of use for class generation and class transformation in mind), and 
follows the "spirit" of the current API. It may not be the most 
efficient from an implementation point of view (I'm not sure about 
that). The only exception to this is the "location" parameter (see 
below). Comments are welcome.

JSR 308 does not modify the format of annotations: it "only" specifies 
new annotation locations. So AnnotationVisitor need not be changed. In 
fact we "only" need to add new "visitXxxAnnotation" methods in Class, 
Field and MethodVisitor.

Eric

----------------------------------

Proposed API (for core API only):

8 new methods in MethodVisitor (some methods can be merged into a single 
one taking an additional, discriminating argument; I did not use 
"TypeAnnotation" in the method names because they are already quite long):

- visitInsnAnnotation(long[] location, String desc, bool visible) : must 
be called just before a visitXxxInsn to annotate the type of the result 
of this instruction (see 4.3.1 in JSR 308). See below for a description 
of the "location" parameter.

- visitLocalVariableAnnotation(Label start, Label end, int index, long[] 
location, String desc, bool visible) : must be called like 
visitLocalVariable, i.e., with the same ordering constraints with 
respect to the other methods (see 4.3.2 - in fact the JSR specifies an 
array of start/end/index values; if we use one visit call per array 
element as proposed here, the challenge is to rebuild the array 
automatically in MethodWriter; the alternative is to use a method like 
visitLocalVariableAnnotation(Label[] start, Label[] end, int[] index, 
long[] location, String desc, bool visible)).

- visitParameterAnnotation(int parameter, long[] location, String desc, 
bool visible) : must be called like visitAnnotation (see 4.3.3).

- visitReceiverAnnotation(long[] location, String desc, bool visible) : 
must be called like visitAnnotation (see 4.3.4).

- visitReturnAnnotation(long[] location, String desc, bool visible) : 
must be called like visitAnnotation (see 4.3.5).

- visitSignatureAnnotation(int parameter, int bound, long[] location, 
String desc, bool visible) : must be called like visitAnnotation method 
(see 4.3.6 and 4.3.7; bound = -1 corresponds to 4.3.6).

- visitMethodInsnAnnotation(int argument, long[] location, String desc, 
bool visible) : must be called just before (or after?) a visitMethodInsn 
to annotate the type of an argument of a method or constructor call (see 
4.3.8).

- visitExceptionAnnotation(int exception, long[] location, String desc, 
bool visible) : must be called like visitAnnotation (see 4.3.10).

1 new method in FieldVisitor:

- visitAnnotation(long[] location, String desc, bool visible) : must be 
called like visitAnnotation (see 4.3.5).

2 new methods in ClassVisitor:

- visitSignatureAnnotation(int parameter, int bound, long[] location, 
String desc, bool visible) : must be called like visitAnnotation method 
(see 4.3.6 and 4.3.7; bound = -1 corresponds to 4.3.6).

- visitInterfaceAnnotation(int interface, long[] location, String desc, 
bool visible) : must be called like visitAnnotation (see 4.3.9).

----------------------------------

"location" parameter

Each visit method above specifies, by its name and first parameters, a 
target for a type annotation. But it is sometimes necessary to define a 
location within this target, due to type arguments, array types, and 
wildcards (see 4.3.10 and 4.3.11). I propose here to encode this 
location as an array of long, as follows (this array can be null for the 
common case where a location within the targeted type is not needed).

First, each long value encodes an array of bytes, which itself specifies 
a path in a tree (see 4.3.12). For instance, the array { 0x1A, 0x1B, 
0x1C } is represented with 0x00000000FF1C1B1A, with each byte one after 
the other, and 0xFF to signal the end of the array. Of course, with this 
encoding, arrays of more than 8 values cannot be represented. But this 
case is very unlikely to occur: it would correspond to a generic type 
with more than 8 levels of nesting, like A<B<C<D<E<F<G<H<I>>>>>>>>, or 
to an array of dimension 9 or more, like A[][][][][][][][][].

Then, the array of long, if not null, should contain at least one value. 
The last value corresponds to the content of the fields specified in 
4.3.12. The other values correspond to the structure specified in 
4.3.11. This structure is recursive, but can only have the topology of a 
linear list (it can not be a tree). Morever, each element except the 
leaf is either empty or a location as specified in 4.3.12. Hence, this 
list structure can be encoded with an array of long (an empty list 
element is encoded with an empty tree, i.e., with 0x00000000000000FF).

An alternative to this encoding is to replace "long[]" with "byte[][]". 
This is easier to use, but may be less efficient. Both could be tested 
to decide which one to choose. Another possibility is to use a String 
encoding of this array of arrays.

Examples:

- the locations for the B, C, D, F, G, and H annotations in Figure 2 in 
4.3.12 are encoded as
       B: { 0x000000000000FF00 }
       C: { 0x000000000000FF01 }
       D: { 0x0000000000FF0001 }
       F: { 0x000000000000FF00 }
       G: { 0x000000000000FF01 }
       H: { 0x000000000000FF02 }

- the location for A in 4.3.11 is encoded as (in a 
visitParameterAnnotation call):
       A: { 0x00000000000000FF, 0x000000000000FF00 }

- the location for B in 4.3.11 is encoded as (in a visitReturnAnnotation 
call):
       B: { 0x000000000000FF00, 0x000000000000FF01 }

With the alternative encoding, this gives:

- the locations for the B, C, D, F, G, and H annotations in Figure 2 in 
4.3.12 are encoded as
       B: { { 0 } }
       C: { { 1 } }
       D: { { 1, 0 } }
       F: { { 0 } }
       G: { { 1 } }
       H: { { 2 } }

- the location for A in 4.3.11 is encoded as (in a 
visitParameterAnnotation call):
       A: { { }, { 0 } }

- the location for B in 4.3.11 is encoded as (in a visitReturnAnnotation 
call):
       B: { { 0 }, { 1 } }

-- 
You receive this message as a subscriber of the [email protected] mailing list.
To unsubscribe: mailto:[email protected]
For general help: mailto:[email protected]?subject=help
OW2 mailing lists service home page: http://www.ow2.org/wws