The @SuppressWarnings Annotation
The annotation @SuppressWarnings can be used to suppress different kinds of warnings from the compiler in code that would otherwise result in these warnings being issued (§11.13, p. 623).
The SuppressWarnings annotation type is an array-valued single-element annotation type—that is, it defines a value() element of type String[]. It is used to indicate which kinds of warnings should be suppressed. Typical kinds of warnings that can be specified for the value array are “unchecked” and “deprecation”. Unchecked warnings caution about mixing legacy and generic code that might result in heap pollution (§11.13, p. 630). Deprecation warnings result from usage of deprecated code (p. 1580). Different Java compilers may provide different kinds of warnings that can be suppressed.
The @SuppressWarnings annotation can be applied at different nested levels of a program construct—for example, when it is applied to a class, it will suppress warnings of a specific kind for the entire class. It is advisable to apply the @SuppressWarnings annotation at the deepest nested level possible, such as a specific method, or a variable that may be the cause of the compiler warnings that a programmer wishes to suppress. Specifying the same kind of warning multiple times is permissible, but only the first occurrence of the name is applied and any other occurrences of this name are ignored.
In the code below, suppressing unchecked warnings in the method is redundant, as that is already the case since its class also suppresses unchecked warnings. However, deprecation warnings are only suppressed for the annotated method in the example below. Note also that the compiler will only suppress unchecked warnings relating to the declaration of the method, but it will not suppress any unchecked warnings at the call sites for this method, in contrast to the @SafeVarargs annotation (p. 1585).
@SuppressWarnings(“unchecked”)
public class PhoneCenter {
@SuppressWarnings({“unchecked”, “deprecation”})
public void callLandline() {}
}
Example 25.2 illustrates suppressing warnings with the @SuppressWarnings annotation. The intention is to suppress both unchecked and deprecation warnings. To show the potential problems in the code, it is first complied without the @Suppress-Warnings annotation using appropriate compiler options. The compiler output shows two unchecked warnings and two deprecation warnings in the undisciplined-Method() and the overridden finalize() method, respectively. With these issues in the code, it is hardly recommended to suppress the warnings using the @Suppress-Warnings annotation; doing so will suppress them, but it will not solve the potential problems in the code.
Example 25.2 Using the @SuppressWarnings Annotation
import java.util.ArrayList;
import java.util.List;
@SuppressWarnings(value={“unchecked”, “deprecation”}) // (1)
public class ATSuppressWarnings {
/** Mixing legacy code and generic code. */
public void undisciplinedMethod() {
List wordList1 = new ArrayList<String>(); // Assigning parameterized type
// to raw type.
List<String> wordList2 = wordList1; // (2) Unchecked conversion
wordList1.add(“911”); // (3) Unchecked call
wordList2.add(“119”); // OK
}
/** Overriding and using a deprecated method. */
@Override
public void finalize() throws Throwable { // (4) Overriding a deprecated method.
super.finalize(); // (5) Usage of deprecated method.
}
}
Compiling without the @SuppressWarnings annotation at (1) is shown below:
>javac -Xlint:unchecked -deprecation ATSuppressWarnings.java
ATSuppressWarnings.java:9: warning: [unchecked] unchecked conversion
List<String> wordList2 = wordList1; // (2) Unchecked conversion
^
required: List<String>
found: List
ATSuppressWarnings.java:10: warning: [unchecked] unchecked call to add(E) as a
member of the raw type List
wordList1.add(“911”); // (3) Unchecked call
^
where E is a type-variable:
E extends Object declared in interface List
ATSuppressWarnings.java:16: warning: [deprecation] finalize() in Object has been
deprecated
public void finalize() throws Throwable { // (4) Overriding a deprecated method.
^
ATSuppressWarnings.java:17: warning: [deprecation] finalize() in Object has been
deprecated
super.finalize(); // (5) Usage of deprecated method.
^
4 warnings
Suppressing warnings is generally considered to be potentially dangerous, as this might hide potential problems within the code. For example, suppressing deprecation warnings may result in a programmer not noticing that deprecated code is in use and may lead to the program not compiling in future versions of Java because the deprecated code has been removed. Regardless, the @SuppressWarnings annotation should not be used unless it has been manually verified that it is safe to do so. Any warnings not suppressed must always be looked into.
The API of the SuppressWarnings annotation type from the java.lang package is shown below:
@Target({TYPE,FIELD,METHOD,PARAMETER,CONSTRUCTOR,LOCAL_VARIABLE,MODULE})
@Retention(SOURCE)
public @interface SuppressWarnings
The annotation is primarily used for suppressing various warnings that the compiler would otherwise issue. Note that the annotation @SuppressWarnings can be applied to declarations of class, interface, enum type, fields, methods, parameters, constructors, local variables, and modules. Its retention policy is SOURCE and thus it is discarded by the compiler once the code is validated—in other words, it is not recorded in the class file and therefore not available at runtime.