[type-annos-observers] JLS and JVMS changes for JSR 308

[Markus Keller]

* 1.4 Special Parameter Contexts
The wording at the end of "8.4.1 Formal Parameters" is not precise enough:
        "If the receiver parameter is present, then its name must be 
either 'this' or the text of a qualified 'this' expression (15.8.3) [..]"

The grammar for ReceiverParameter only allows "{Identifier .} this". The 
java-annotation-design.html clearly says that the receiver parameter is 
named 'this', and then it adds a special case "In a constructor in an 
inner type, the receiver has a name such as Outer.this".

=> The spec should not say "either ... or", but it should say that the 
name is "this", except in a constructor in an inner class, where it is 
"EnclosingClassName.this".
=> The reference to (15.8.3) is problematic for two reasons:
  a) in JLS7, the "Qualified this" section is actually 15.8.4
  b) The grammar in JLS7 15.8 refers to ClassName, but this rule is not 
defined anywhere in JLS7 (already broken in JLS2 where "Qualified 'this'" 
was introduced). According to the grammar in ch. 18, it's a 
fully-qualified name. But the 'this' in the receiver parameter can only be 
qualified with an identifier.


* 1.7 Type Annotations
The end of this section defines the attachment points of annotations, but 
it misses to spell out details for annotations on array types. The last 
bullet point is:
"• If the annotation's type is applicable in the declaration context 
represented by D
and in type contexts, then the annotation is deemed to appear as both a 
modifier
for the declaration and a decorator for the type of the declared entity.

In this case, the annotation which syntactically appears in the grammar as 
a
modifier for the declaration is also implicitly declared to annotate the 
type of the
declared entity."

This is incorrect for array types with an unqualified element type.

Example:
@Foo int[] f;

As a type-use annotation, @Foo does *not* annotate the type of 'f' (which 
is 'int[]'), but it annotates only the array's element type 'int'!


Furthermore, the 308.pdf doesn't define the semantics of annotations on 
multi-level array types. Example:

String @A[][][] a;

The grammar rule for ArrayType (Type {Annotation} [ ])  parses this into a 
tree of ArrayTypes where the annotation @A appears on the innermost 
ArrayType:
ArrayType:        String @A[][][]
+ ArrayType:      String @A[][]
  + ArrayType:    String @A[]
    + Type:       String
    + Annotation:        @A
    + brackets:            []
  + brackets:                []
+ brackets:                    []

But as 
http://types.cs.washington.edu/jsr308/specification/java-annotation-design.html#array-syntax 
explains, that grammatical deconstruction is not the intended semantics 
for array types. In the language model, there's e.g. no type "String 
@A[]", since the array brackets are intended to be read from left to 
right. I.e. the component type of "a"'s declared type "String @A[][][]" is 
"String[][]", since the @A appears on the *first* brackets pair. It's not 
"String @A[][]" as one would think when studying the grammar.

This is an unexpected detail that should be explained by the spec, 
especially since this also shows up in reflective APIs like 
javax.lang.model.type.ArrayType#getComponentType(), which can no longer 
just map to AST nodes from a Java parser, but have to correctly turn a 
grammar-based AST inside-out, so that in the given example, @A is attached 
to the outermost ArrayType, and not to the innermost component type.


* 2 The Java Virtual Machine Specification
The section "4.7.20.2 The type_path structure" needs to explain the 
left-to-right semantics for multi-level array types in the type_path > 
path data structure.

Markus


P.S.: This concern is also still open: [type-annos-observers] 
RetentionPolicy.CLASS too broad for TYPE_USE annotations:
http://mail.openjdk.java.net/pipermail/type-annotations-spec-observers/2013-July/000172.html



From:   Alex Buckley <alex.buckley at oracle.com>
To:     type-annotations-spec-experts 
<type-annotations-spec-experts at openjdk.java.net>
Date:   2013-08-06 03:39
Subject:        [type-annos-observers] JLS and JVMS changes for JSR 308
Sent by:        type-annotations-spec-observers-bounces at openjdk.java.net



I have prepared a PDF containing the JLS and JVMS changes for JSR 308:

   http://cr.openjdk.java.net/~abuckley/308.pdf

If you're expecting a simple list of grammar changes, you may want to 
sit down before opening the PDF. There are significant clarifications to 
JLS chapters 4 and 6, all aimed at pinning down what exactly is a type 
use. The JLS has distinguished between types (a.k.a. type uses) and type 
names since JLS3, but it was very subtle, and it is essential for JLS8 
to take a comprehensive view of the language's syntactic contexts and 
the types and names allowed therein.

The ClassFile changes present a recurring challenge: how much to mention 
Java language features in the JVMS? The Signature attribute is a 
precedent, so for now, I have aimed for maximum clarity. An example 
would be mentioning both constructors and methods when describing 
target_info, even though the ClassFile structure is aware only of methods.

Text in the PDF is either normative or informative. Informative text is 
smaller and indented. The point of the PDF is that most text is ready to 
go into the JLS or JVMS as-is, although informative text which mentions 
JSR 308 is intended more as commentary for 2013 than as long-term 
specification; it will evolve further, or be removed.

The UW PDF at:

 
http://types.cs.washington.edu/jsr308/specification/java-annotation-design.pdf


remains an excellent source of background, examples, and rationale. This 
kind of material should be available on the JSR 308 page at jcp.org 
forever, so I envisage offering both 308.pdf and 
java-annotation-design.pdf in the milestone reviews yet to come.

Mike, it would be instructive to look at how JSR 334's specification 
changed between Public Review and Proposed Final Draft. Vast swathes of 
normative text were replaced with pointers to JLS sections. It would be 
appropriate to start the same "pruning" process on 
java-annotation-design.pdf. This will provide a double check on my 
extraction of normative clauses from java-annotation-design.pdf.

Alex