Java Reference
In-Depth Information
The
SafeVarargs
annotation has non-local effects because it suppresses unchecked
warnings at method invocation expressions in addition to an unchecked warning per-
taining to the declaration of the variable arity method itself (§
8.4.1
). In contrast, the
@SuppressWarnings("unchecked")
annotation has local effects because it only suppresses
unchecked warnings pertaining to the declaration of a method.
The
canonical
target
for
a
annotation
is
a
method
like
SafeVarargs
java.util.Collections.addAll
, whose declaration starts with:
public static <T> boolean
addAll(Collection<? super T> c, T... elements)
The variable arity parameter has declared type
T[]
, which is non-reifiable. However,
the method fundamentally just reads from the input array and adds the elements to
a collection, both of which are safe operations with respect to the array. Therefore,
any compile-time unchecked warnings at method invocation expressions for
java.util.Collections.addAll
are arguably spurious and uninformative. Applying a
SafeVarargs
annotation to the method declaration prevents generation of these un-
checked warnings at the method invocation expressions.
It is a compile-time error if a fixed arity method or constructor declaration is annotated
with the
SafeVarargs
annotation.
It is a compile-time error if a variable arity method declaration that is neither
static
nor
final
is annotated with the
SafeVarargs
annotation.
Since a
SafeVarargs
annotation is only applicable to
static
methods,
final
instance meth-
ods, and constructors, the annotation is not usable where method overriding occurs.
Annotation inheritance only works on classes (not methods, interfaces, or construct-
ors), so a
SafeVarargs
-style annotation cannot be passed through instance methods in
classes or through interfaces.
9.7. Annotations
An
annotation
is a modifier consisting of the name of an annotation type (§
9.6
) and zero or
more element-value pairs, each of which associates a value with a different element of the
annotation type.
The purpose of an annotation is simply to associate information with the annotated program
element.
