What problem does @SafeVarargs solve, and where can it be applied?

## Two background concepts **Varargs** (variable arguments): a method like `void log(String... parts)` accepts any number of `String` arguments. Under the hood the compiler packs them into an **array** — `parts` is really a `String[]`. **Type erasure & non-reifiable types:** Java generics are a compile-time feature. At runtime, the type parameter `T` (and parameterized types like `List<String>`) is **erased** — the JVM doesn't fully know the element type. Types whose full type information isn't available at runtime are called **non-reifiable**. Arrays, by contrast, *do* carry their element type at runtime, so combining the two — an **array of a generic type** — is inherently leaky. ## The warning and 'heap pollution' When you write a generic varargs method: ```java static <T> List<T> listOf(T... items) { ... } ``` the compiler creates a `T[]` array, but it can't guarantee at runtime that the array really contains only `T`s. This mismatch is called **heap pollution**: a variable of a parameterized type refers to an object that is not of that parameterized type, which can later blow up with an unexpected `ClassCastException`. So the compiler issues an **'unchecked' / 'Possible heap pollution from parameterized vararg type'** warning at both the **declaration** and every **call site**. ### How it can actually go wrong The danger is real if the method **stores into** the array or **leaks the array reference** to code that treats it as a plain `Object[]`: ```java static <T> T[] dangerous(T... arr) { Object[] o = arr; o[0] = Integer.valueOf(42); // pollutes a String[] if called with Strings return arr; // later reads -> ClassCastException } ``` ## What @SafeVarargs asserts `@SafeVarargs` is the author's **promise** that the method is in fact safe — typically because it only **reads** from the varargs array and never **writes** an incompatible element nor **exposes** the array to be mutated. With that promise, the compiler suppresses the unchecked/heap-pollution warning **both in the method body and at all call sites** — which is the key benefit over `@SuppressWarnings("unchecked")`, which only silences the declaration site, not callers. It is **`SOURCE`**-retained — purely a compile-time directive. ## Where it is allowed The author can only vouch for an implementation they fully control, so `@SafeVarargs` is restricted to methods that **cannot be overridden**: - **`static` methods** - **`final` instance methods** - **`private` instance methods** (allowed since **Java 9**) - **constructors** Putting it on a **non-final, non-static, non-private instance method** is a **compile error** (an overriding subclass could be unsafe). Applying it to a method that has **no varargs parameter** is also an error/warning — there's nothing to assert. ## Relationship to other annotations - It is a more **targeted, correct** tool than `@SuppressWarnings({"unchecked","varargs"})` for this specific case, and it also covers call sites. - JDK examples: `Arrays.asList(T...)`, `List.of(E...)`, `EnumSet.of(...)`, `Collections.addAll(...)` are annotated `@SafeVarargs`. ## Responsibility caveat The annotation **does not verify** safety — it **suppresses** the warning based on your assertion. If you annotate an actually-unsafe method, you've hidden a real risk. So only apply it after confirming the method merely reads the array and never lets it escape mutably. ## Takeaway Use `@SafeVarargs` on un-overridable generic-varargs methods that only read their varargs array, to remove the heap-pollution warning at the declaration and all call sites — but only when you've verified the method truly is safe.