Safe Varargs

[Joe Darcy]

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.