[JSR308] array-valued annotations

[Tom Ball]

Gary T. Leavens wrote:
> Hi Pavel and all,
> 
> On Thu, 25 Jan 2007, Pavel Krupets wrote:
> 
>> Hello,
>>
>> I don't think it's appropriate to use annotations like:
>> "Document[][@Readonly]". What I mean is that there is no much sense in
>> specifying different annotations for different dimensions of the 
>> array. If
>> such behavior is needed other types can be used (like List<...>, etc). I
>> think annotations should be used only with:
>>
>> - array as an object (like: @NonNull @Readonly Document[][] doc = ...)
>> - objects which are stored inside arrays (like: Document @NonNull
>> @Readonly [][] doc = ...)
>>
>> The reason behind this is that array (one or multi-dimensional) is an
>> 'atomic' type which has type of stored object and dimensions. Just 
>> want to
>> keep things simple.
> 
> I agree that keeping things simple is good when possible.  But
> semantically, each array declared is itself a location which holds a
> collection of locations.  Thus, to simplify to one dimension:
> 
>    Document[] docs;
> 
> could look like
> 
>                       0  1  2  3
>    docs [ *-]------> [  |  |  |  ]
> 
> and the location named doc can be null or readonly independent of the
> locations doc[0]..doc[3].  The same holds for readonly.
> 
> You would lose expressiveness if you can't independently talk about
> these different locations.

Computer language involves balancing the need to clearly express program 
intent with the costs associated with doing so.  All major language 
decisions lose some level of expressiveness; one only need look at the 
failure of the 80's executable specification language research efforts 
to realize that a language can be too-specific to be widely adopted.

I agree with Pavel that this area needs to be simplified.  Java doesn't 
support an array whose elements are specified as different types, and 
neither should its metadata define different constraints on them. 
Defining different policies on different elements implies that the 
decision to use an array is incorrect; instead of investing lots of 
effort adding metadata to clarify the policy, that time would be better 
spent designing a class that explicitly describes and enforces the 
policy.  Whether an array is actually used then becomes a hidden 
implementation decision.

For example, say you are storing a U.S. home address as an array of 
Strings.  You want to enforce that all of the elements (name, street 
address, city, state, and zip code) be NonNull, but the optional 
apartment number element may optionally be Null.  At this point in a 
design review, a senior engineer would take the developer out to the 
woodshed for some serious "feedback", as this is not a supportable API 
decision.  An array shouldn't be part of this API, it should instead be 
an implementation detail.  One alternative is to define the address as 
immutable class with two constructors, one with and one without the 
apartment number.  It would be reasonable then to have @NonNull 
annotations on each of the constructors' parameters.  These annotations 
don't belong in the declaration of the hidden array the class uses, but 
in the class's contract with its clients.

Tom