Proposal to make new-in-Java-SE-8 methods on AnnotatedElement default methods

[Joe Darcy]

Hi Alex,

On 10/28/2013 10:19 AM, Alex Buckley wrote:
> Semantics look good; some wording concerns below.
>
> On 10/25/2013 1:35 AM, Joe Darcy wrote:
>> Second iteration for the default method aspects of getAnnotationsByType:
>>
>> +     * @implSpec The default implementation first calls {@link
>> +     * #getDeclaredAnnotationsByType(Class)} on the argument type. If
>> +     * the returned array has size greater than zero, the array is
>> +     * returned. If the returned array has size zero and this {@code
>> +     * AnnotatedElement} is a class and the argument type is an
>> +     * inheritable annotation, and the superclass of this {@code
>> +     * AnnoatedElement} is non-null, then the result of {@code
>> +     * getAnnotationsByType(annotationClass)} on the superclass is
>> +     * returned. Otherwise, a zero-length array is returned.
>
> "calls getDeclaredAnnotationsByType(Class) on the argument type" can 
> be read as "executes 
> annotationClass.getDeclaredAnnotationsByType(Class)" - that's how you 
> use "on" in the penultimate sentence. Generally "argument type" is 
> problematic - the type Class<T> is not especially interesting here. 
> Try "calls getDeclaredAnnotationsByType(Class) passing the 
> annotationClass argument."
>
> "and annotationClass represents an inheritable annotation _type_, and 
> ..."
>
> "then the result of calling getAnnotationsByType(Class) on the 
> superclass, _once again passing annotationClass,_ is returned."

Changed to:

+     * @implSpec The default implementation first calls {@link
+     * #getDeclaredAnnotationsByType(Class)} passing {@code
+     * annotationClass} as the argument. If the returned array has
+     * size greater than zero, the array is returned. If the returned
+     * array has size zero and this {@code AnnotatedElement} is a
+     * class and the argument type is an inheritable annotation type,
+     * and the superclass of this {@code AnnoatedElement} is non-null,
+     * then the returned result is the result of calling {@code
+     * getAnnotationsByType} on the superclass with {@code
+     * annotationClass} as the argument. Otherwise, a zero-length
+     * array is returned.
+     *

>
>> Second iteration for the default method aspects of
>> getDeclaredAnnotationsByType:
>>
>> +     * @implSpec The default implementation may call {@link
>> +     * #getDeclaredAnnotation(Class)} one or more times to find a
>> +     * directly present annotation and, if the annotation type is
>> +     * repeatable, to find a container annotation. If the annotation
>> +     * type is both directly and indirectly present, {@link
>> +     * getDeclaredAnnotations()} will get called to determine the
>> +     * order of the elements in the returned array. Alternatively,
>> +     * {@link getDeclaredAnnotations()} may be called a single time
>> +     * and the returned array examined for both directly and
>> +     * indirectly present annotations. The results of calling {@link
>> +     * getDeclaredAnnotations()} are assumed to be consistent with the
>> +     * results of calling {@code #getDeclaredAnnotation}
>
> "If the annotation type is both directly and indirectly present" - 
> annotations, not their types, are directly/indirectly present. Try "If 
> annotations of type annotationClass are determined to be directly 
> present and indirectly present, then getDeclaredAnnotations() is 
> called to determine the order ..."
>
> I think the middle part should read "Alternatively, the default 
> implementation may call ..." because otherwise the remainder of the 
> @implSpec is too easily read as a sub-clause of of determining the 
> order of elements in the returned array.
>
> Need a (Class) in the final @code.
>
>

Changed to:

+     * @implSpec The default implementation may call {@link
+     * #getDeclaredAnnotation(Class)} one or more times to find a
+     * directly present annotation and, if the annotation type is
+     * repeatable, to find a container annotation. If annotations of
+     * the annotation type {@code annotationClass} are found to be both
+     * directly and indirectly present, then {@link
+     * #getDeclaredAnnotations()} will get called to determine the
+     * order of the elements in the returned array.
+     *
+     * <p>Alternatively, the default implementation may call {@link
+     * #getDeclaredAnnotations()} a single time and the returned array
+     * examined for both directly and indirectly present
+     * annotations. The results of calling {@link
+     * #getDeclaredAnnotations()} are assumed to be consistent with the
+     * results of calling {@link #getDeclaredAnnotation(Class)}.
+     *

Thanks,

-Joe