Safe Varargs

[Neal Gafter]

This documentation uses the phrase "potentially unsafe operations"
without defining it.  Presumably such unsafe operations include an
assignment to a variable of the same type (i.e. allowing the varargs
parameter to escape).

On Monday, December 13, 2010, Joe Darcy <joe.darcy at oracle.com> 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.
>
>
>
>