Comments and questions on JSR 308 draft from January 23, 2013

[Joe Darcy]

Dear type annotations experts,

I've read through the January 23, 2013 JSR 308 specification [1], which 
is the most recent one I'm aware of.

I have comments and questions about the draft. Some of these issues may 
have already been discussed on JSR 308 mailing lists, but perhaps adding 
some more notes on design rationale might help answer similar questions 
for future readers of the document.

Section 1
"[JSR 308] does not change the abilities of Java annotation processors 
as defined in JSR 269 [Dar06]."

The phrasing "does not directly change..." would be more accurate since 
the JSR 269 API is being extended to support type annotations.

Section 2.1

Annotation syntax the syntax to annotate a fully-qualitied type use is

     "java.lang. at NonNull String"

rather than

     "@NonNull java.lang.String"

I understand this point has been considered by the EG previously, but I 
find it surprising and would be interested in seeing the rationale 
disclosed in the specification document.

"(Note that the result of a constructor is different from the receiver. 
The receiver only exists for inner class
constructors, as in theReceiver.new InnerClass(). The receiver is the 
containing object, and in the body of the
constructor it is referred to as Supertype.this. In the constructor 
body, the result is referred to as this. In any
non-constructor, the receiver (if any) is referred to as this.)"

I don't have a better terminology suggestion offhand, but I'm 
uncomfortable with using the term "receiver" to describe the outer this 
object. At a VM level, a constructor is an odd sort of static method and 
does not have a receiver; indeed, in the implementation the outer this 
is passed as an argument to the constructor. No method is dispatched off 
of the outer this.

This fact also filters through to core reflection; when invoking "new 
InnerClass()" reflectively, the "theReceiver" object is passed as a 
parameter, not the other way around.

"It is permitted to explicitly declare the method receiver as the first 
formal parameter. (Each non-static method
has an implicit formal parameter, this, which is called the receiver.) 
Then, no special syntax is needed for
expressing a receiver type annotation: it is simply an annotation on the 
type of the this formal parameter."

"The optional receiver parameter has no effect on execution — it only 
serves as a place to write annotations
on the receiver. The compiler generates the same bytecodes, and 
reflection returns the same results regarding
number of method formal parameters, whether or not the optional receiver 
parameter is present."

In Java SE 8, we are also adding support for more reflective information 
about method and constructor parameters, including modifiers as to 
whether or not they are "synthetic" vs "mandated". The explicit 
"receiver" parameter declarations may alter how the corresponding 
java.lang.reflect.Parameter objects should behave in some situations. In 
any case, the specification should be updated to be explicit about any 
interaction or non-interaction here.

It was not clear to me from reading the specification whether or not "C 
style" mixed array declarations were able to be annotated. If the answer 
is "no", that is fine by me.

Section 3

"The VM does not have to validate all the constraints in Section 3.3, 
such as that offsets point to the right type of
instruction. The VM does not do format checking (JVMS 4.8) on attributes 
used solely for reflection."

The JVMS has a rich terminology in terms of what checks happen (or not) 
where and when in the linking and loading process. This description 
above should be tied more directly to the JVMS concepts.

"For backward compatibility, JSR 308 uses new attributes for storing the 
type annotations. In other words, JSR 308 merely reserves the names of a 
few new attributes and specifies their layout. JVMs ignore unknown 
attributes."

"JVMs ignore unknown attributes" is a true statement, but one not 
directly relevant to this document since JSR 308 is adding the 
attributes to the set of known attributes. If the new attributes appear 
in a 51.0 or earlier class file, they should be ignored.

Section 3.2

Declaration annotations on type parameters are stored in the 
*TypeAnnotations attributes as opposed to the pre-existing *Annotations 
attributes used to store the annotations on all other declarations. This 
is at least initially surprising and I think a discussion of this point 
is warranted.

Section 3.3

Figure 1 lists the target_type values for different locations. There 
seem to be inconsistencies in how method vs constructors are 
distinguished or not. Within code blocks, there are different 
target_types for methods vs constructors. In contrast, the METHOD TYPE 
PARAMETER value presumably covers both methods parameters as well as 
constructor parameters.

(Note to future maintainers of the platform: one of the new to-do items 
for evolving the language may be to add new target_type values [2].)

"The symbolic constants appear in the enums 
com.sun.tools.javac.code.TargetType and
com.sun.tools.classfile.TypeAnnotation.TargetType."

The implementation note above seems off-topic for this document.

Stepping back a bit, while this JSR is adding "Annotations on Java 
Types" and is thus focused on the Java programming language, are any 
additional facilities / escape hatches needed to allow annotations in 
source language other than Java? The class / method / field / 
constructor representations should stable across most language targeting 
the JVM.

Section 3.3.10

"If the compiler eliminates an annotated cast, it is required to retain 
the annotations on the cast in the class file. "

Presumably only if the corresponding annotation types have at least 
CLASS retention.

Section A

"No modifications to the virtual machine are necessary."

... other than the changes to the class file format discussed in section 
...

Cheers,

-Joe

[1] 
http://mail.openjdk.java.net/pipermail/type-annotations-spec-experts/2013-January/000053.html

[2] "So you want to change the Java Programming Language...",
https://blogs.oracle.com/darcy/entry/so_you_want_to_change