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

[Igor Peshansky]

Michael Ernst <mernst at csail.mit.edu> wrote on 11/04/2007 09:15:58 PM:

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

Thanks, Mike, for a clear and succinct summary.

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

A disadvantage (in my view) is that it decouples the annotation from
the level at which it appears.  Just as we were concerned that the
original type would be lost with all the annotations permeating it,
so in this case the annotation itself may be lost in the tangle of
array annotations associated with it.

I'm also very wary of allowing square brackets to follow annotations.
Even barring the weird cases like

  @None[@Length(3)] int foo(SomeLongList ofParameters)[] {...}

there may be times when this syntax will be, if not grammatically
ambiguous, at least confusing to the programmer.

Also, we would have to allow the brackets syntactically to appear
after all annotations...  Don't know yet if this is a big problem.

Finally, it sounds close enough to the "annotations as parameters
to annotations" proposal to make the pitch for both together.

> 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;

This is bound to be confusing.  It might actually make more sense to
go with Gary's suggestion, but rename the @None annotation to @_.
That way we don't have to explain two new concepts.

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

I'd argue against this proposal.  On one hand, what you said makes
sense so that programmers can rely on exactly one set of annotation
brackets corresponding to each dimension of the array.  On the other,
it might make more sense to group the annotations when expressing
different concepts.  For example

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

might be a better way to express which levels are read-only, and which
are non-null.  Also, consider wanting to comment out one of the
attributes.  In the example above, you only need to comment out one
line, whereas if this proposal went through, you'd need a lot of small
commented-out sections.

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

I'd call this PARALLEL, because the structure of the annotation parallels
that of the type (also, brackets in the annotation create essentially a
parallel specifier to the type definition).

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

I agree that the ELTS syntax looks counter-intuitive.  In this case,
more than in all of the other proposals, it makes sense to go with
the ARRAY binding, since the structure of the annotation exactly
parallels the structure of the type.

All told, I'd rather see the annotations on the individual brackets
(with whatever syntax and binding we eventually decide on).  It seems
much clearer than having to count off brackets (FWIW, the numbered
proposals in section B.3 of the document suffer from the same malady).
To be fair, though, this proposal certainly looks better than those
two proposals (1 and 2 in B.3 -- BTW, should we give them names too?).
        Igor
-- 
Igor Peshansky  (note the spelling change!)
IBM T.J. Watson Research Center
XJ: No More Pain for XML's Gain (http://www.research.ibm.com/xj/)
X10: Parallel Productivity and Performance (http://x10.sf.net/)