Safe Varargs

[Joe Darcy]

FYI, I've pushed a changset [1] to annotate four core library methods 
with @SafeVarargs:

     * public static <T> List<T> java.util.Arrays.asList(T... a)
     * public static <T> boolean 
java.util.Collections.addAll(Collection<? super T> c, T... elements)
     * public static <E extends Enum<E>> java.util.EnumSet<E> 
EnumSet.of(E first, E... rest)
     * protected final void javax.swing.SwingWorker.publish(V... chunks)

I've also posted a description of the methodology used to find candidate 
methods to be so annotated [2].

-Joe

[1] http://hg.openjdk.java.net/jdk7/tl/jdk/rev/dbfc1e419cb2

[2] "Project Coin: Safe Varargs in JDK Libraries"
http://blogs.sun.com/darcy/entry/project_coin_safe_vararg_libraries

On 12/13/2010 3:17 PM, Joe Darcy wrote:
> Greetings.
>
> Following up on earlier work, the javac team has pushed a new 
> implementation of Project Coin's simplified varargs method invocation 
> feature. [1] The changes are scheduled to appear in the promotion of 
> JDK 7 b123.
>
> As envisioned previously, a new @Documented annotation type, 
> java.lang.SafeVararags, can be used to suppress warnings related to 
> unchecked warnings, both the new mandatory warnings at the declaration 
> site of a varargs method/constructor with a non-reifiable element type 
> and the existing unchecked warnings at the call sites of such methods. 
> A systematic application of this annotation to appropriate 
> declarations in the JDK libraries will follow as future work.
>
> Since new unchecked warnings are being introduced, those diligently 
> compiling with options like "-Xlint:unchecked -Werror" will see a 
> build error under JDK 7 if any of the suspicious varargs method 
> declarations are found. To address this, the @SafeVarargs annotation 
> can be applied to the declarations, if appropriate, or the 
> @SuppressWarnings({"unchecked", "varargs"}) annotation can be applied. 
> Unlike @SafeVarargs, the @SuppressWarnings annotation will not squelch 
> unchecked warnings at the call site of the annotated method.
>
> The specification of the new SafeVarargs annotation type is below.
>
> -Joe
>
> [1] http://hg.openjdk.java.net/jdk7/tl/jdk/rev/78885e69c42c
> http://hg.openjdk.java.net/jdk7/tl/langtools/rev/7b99f98b3035
>
> -=-=-=-=-=-=-
>
> Annotation Type SafeVarargs
>
>    @Documented
>    @Retention(value=RUNTIME)
>    @Target(value={CONSTRUCTOR,METHOD})
>    public @interface SafeVarargs
>
> A programmer assertion that the body of the annotated method or 
> constructor does not perform potentially unsafe operations on its 
> varargs parameter. Applying this annotation to a method or constructor 
> suppresses unchecked warnings about a non-reifiable variable-arity 
> (vararg) type and suppresses unchecked warnings about parameterized 
> array creation at call sites.
>
> In addition to the usage restrictions imposed by its @Target 
> meta-annotation, compilers are required to implement additional usage 
> restrictions on this annotation type; it is a compile-time error if a 
> method or constructor declaration is annotated with a @SafeVarargs 
> annotation, and either:
>
>        * the declaration is a fixed-arity method or constructor
>        * the declaration is a variable-arity method that is neither 
> static nor final.
>
> Compilers are encouraged to issue warnings when this annotation type 
> is applied to a method or constructor declaration where:
>
>        * The variable-arity parameter has a reifiable element type, 
> which includes primitive types, Object, and String. (The unchecked 
> warnings this annotation type suppresses already do not occur for a 
> reifiable element type.)
>        * The body of the method or constructor declaration performs 
> potentially unsafe operations, such as an assignment to an element of 
> the variable-arity parameter's array that generates an unchecked warning.
>
>          Future versions of the platform may mandate compiler errors 
> for such unsafe operations.
>
>