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

[Michael Ernst]

Thanks, Gary, for your suggestion about array annotation syntax.

I've been traveling with limited access to email, but I'm a bit surprised
that no one has responded, either positively or negatively.  Let me
summarize it again (and apologies if I get anything wrong), in hopes of
getting some others to comment.

The essential idea is to group together, in one place, annotations on both
an array and its elements.  Whereas the previous proposals place
annotations directly on the brackets of an array declaration, Gary's
proposal introduces new brackets in the annotation itself.  Another way of
saying this is that proposal changes the syntax of annotations themselves,
rather than changing where annotations appear.  The proposal has no effect
on the classfile format.

As an example, previous proposals would write a 365-element array of
readonly Dates as (say)

  @Readonly Date @Length(365) [] myDates;

The new scheme expresses this as

  @Readonly[@Length(365)] Date[] myDates;

(The examples above use the ARRAY convention for the meaning of an
annotation on brackets; you could swap the two annotations if you prefer
the ELTS convention.)

An advantage of the proposal is that it leaves the original type
unmodified, so that original type is potentially easier to read.



I would like to broach a few changes to Gary's proposal.

1. Rather than requiring the use of a pre-defined @None annotation to
indicate that no annotations appear on that level, permit omitting the
annotation.  For instance,

  @[@Length(365)] Date[] myDates;

if the dates in the array are un-annotated.

2. Consider prohibiting multiple annotation-carrying brackets.  Gary gave
the example

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

which could instead be written

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

The grammar changes slightly more, but the changes can be encapsulated with
an "Annotations" non-terminal.



Here is a terminological issue:

> 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).

This new option is orthogonal to the choice of IN, PRE, and POST, since
it's possible to combine any of those with it:

  @Readonly[@Length(365)] Date[] myDates;       // IN
  @Readonly @Length(365) [] Date[] myDates;     // PRE
  @Readonly [] @Length(365) Date[] myDates;     // POST

Of these, only the IN variety seems workable (the PRE variant is
ambiguous), but in that case perhaps TYPE-IN is a better name.

I think the mnemonic for "TYPE" is that the annotation is on the top level
only (annotations cannot be on array levels), but I find that term a bit
confusing.  Perhaps we can find a clearer name.  ANNO-IN is one possibility
("ANNO" meaning the brackets are in the annotation itself), but I'm sure
someone can come up with something better.


The new option is also orthogonal to the ARRAY vs. ELTS question:  do
annotations on a set of brackets refer to the array itself, or to the
elements of that array?  Gary's original message suggests that he prefers
the ELTS interpretation, but that is not a necessary consequence of the
syntax proposal.  In fact, it's a bit surprising that in this ELTS example
of a mutable array of read-only documents,

>    @Mutable[@Readonly]  Document[]  array_of_rodocs;

the "@Mutable" annotation does not apply to the type (Document) that is in
the same syntactic location as it.  This might help to inform the ARRAY
vs. ELTS decision even if we don't choose this particular syntax.

                    -Mike