[JSR308] JSR 308 alternative proposal for array annotation syntax (TYPE)

[Gary T. Leavens]

Hi all,

After the OOPSLA BoF session on JSR 308 I had a crazy idea about the
array annotation syntax...

The idea is to use square brackets in the annotations themselves when
annotating an array type.  This changes the grammar for the
nonterminal Annotation itself, instead of just where Annotation may
occur.  The grammar change would be to change the current Java 5 grammar
production

   Annotation:
       @ TypeName [( [Identifier =] ElementValue)]

to

   Annotation:
       @ TypeName [( [Identifier =] ElementValue)] {'['Annotations']'}

(where the first use of "[" indicates something is optional, and the
'[' and ']' are literally the left and right square bracket
characters). So an annotation may be followed by zero or more
square-bracketed annotations, each of which refers to the element type
in an array type's corresponding dimension.

This syntax would replace the 3rd syntax change in section 2.2 of the
current JSR 308 proposal, which would thus *not* permit writing
annotations within the brackets of an array type itself.

For terminology, let's call this option TYPE (in contrast to IN, PRE,
and POST) of section B.3 of the JSR 308 draft that is current).

For static checking, the square-bracketed annotations would only be
allowed on type qualifiers for array types, and must have the same
number of dimensions as the array type they are qualifying.

The semantics is that the Annotations within a bracketed type
annotation refer to the type of those elements for that dimension.
Thus in

    @Readonly[@Readonly] @Nonnull[@Nonnull] Document[] ds;

the type of ds is a read-only, non-null array of Documents, and
the type of ds[i] is a read-only, non-null Document.

An annotation that qualifies an array type is disambiguated by
using empty brackets, so that it's clear what parts apply to the
element types and what to the array as a whole.  For example,

    @Readonly[][] Document[][]

can be interpreted as having @Readonly apply just to the type
Document[][], and not to any level of elements.

For examples we have as in section B.3 of the current JSR
using the following variables (I changed the name of the last one,
which seems confusing in the current JSR):

     array_of_rodocs a mutable one-dimensional array of immutable Documents
     roarray_of_docs an immutable one-dimensional array of mutable Documents
     array_of_array_of_rodocs a mutable array, whose elements are
             mutable one-dimensional arrays of immutable Documents
     array_of_roarray_of_docs an immutable array, whose elements are
             mutable one-dimensional arrays of mutable Documents
     roarray_of_array_of_rodocs an imutable array, whose elements are
             mutable one-dimensional arrays of immutable Documents

The example variables would be declared as follows:

   @Mutable[@Readonly] Document[] array_of_rodocs;

(note that you need an "opposite" or "nothing applies" annotation for
the outer level in such cases, as the grammar needs an Anotation
before the square brackets.  Perhaps we could have a standard @None
annotation for such situations, in which case we could write:
   @None[@Readonly] Document[] array_of_rodocs
for the above.)

   @Readonly[] Document[] roarray_of_docs;
or
   @Readonly[@Mutable] Document[] roarray_of_docs;

   @Mutable[][@Readonly] Document[][] array_of_array_of_rodocs
                         = new Document[2][12];
or
   @Mutable[@Mutable][@Readonly] Document[][] array_of_array_of_rodocs
                                 = new Document[2][12];

   @Mutable[@Readonly][] Document[][] array_of_roarray_of_docs
                                = new @Mutable[@Readonly][] Document[2][12];
or
   @Mutable[@Readonly][@Mutable] Document[][] array_of_roarray_of_docs
                        = new @Mutable[@Readonly][@Mutable] Document[2][12];

   @Readonly[][@Readonly] Document[][] roarray_of_array_of_rodocs
                    = new @Readonly[][@Readonly] Document[2][12];
or
   @Readonly[@Mutable][@Readonly] Document[][] roarray_of_array_of_rodocs
                    = new @Readonly[@Mutable][@Readonly] Document[2][12];

Well, you can see the advantages and disadvantages of this from the
examples, I think.  A big advantage is that it groups the annotations
completely, and doesn't mix them with the expressions and the type
being declared.  However, the departure from the traditional
Annotation syntax is pretty significant.  In any case, 
I offer this crazy alternative syntax for discussion.

         Gary T. Leavens
         210 Harris Center (Bldg. 116)
         School of EECS, University of Central Florida
         4000 Central Florida Blvd., Orlando, FL 32816-2362 USA
         http://www.eecs.ucf.edu/~leavens  phone: +1-407-823-4758
         leavens at eecs.ucf.edu