What hazards arise when combining varargs with generics, and what is @SafeVarargs for?

## Background you need first Two Java facts collide here: 1. **A varargs parameter is an array** (`T... x` becomes `T[] x`). 2. **Generics are erased at runtime** — `List<String>` and `List<Integer>` are both just `List` once compiled. Java therefore **forbids creating arrays of a parameterized type**: `new List<String>[10]` is a compile error, because arrays are *reified* (they remember their element type at runtime) while generics are not, and the combination is unsound. ## The conflict So what happens with `static <T> void f(List<T>... lists)`? The compiler *must* create an array to hold the varargs — but it's a generic array, which is normally illegal. The compiler allows it as a special case but **flags it with an 'unchecked generic array creation' warning**, because the resulting `List[]` cannot fully police its element types at runtime. ## Heap pollution defined **Heap pollution** is the situation where a variable of a parameterized type (e.g. `List<String>`) refers to an object that is *not* of that parameterized type (e.g. a `List<Integer>`). Because erasure removed the type tag, the JVM can't catch this at the point of assignment; instead you get a surprising `ClassCastException` *later*, when the value is finally used and an implicit cast fails. Generic varargs is a prime way to introduce it. The dangerous pattern is when the method **stores the varargs array somewhere or returns it / passes it out**, letting code observe or corrupt it with the wrong type: ```java @SafeVarargs // <-- WRONG: this method is NOT safe static <T> T[] toArray(T... args) { return args; } // leaks the array static <T> T[] pickTwo(T a, T b) { return toArray(a, b); // creates an Object[] at runtime } String[] s = pickTwo("x", "y"); // ClassCastException: Object[] is not String[] ``` ## When generic varargs IS safe A generic varargs method is safe when it: - **Only reads** from the varargs array (iterates, indexes for reading), and - **Never stores** anything into the array, and - **Never lets the array reference escape** (doesn't return it or pass it to untrusted code that could store the wrong type). Methods like `List.of`, `Arrays.asList`, `Collections.addAll`, and `Stream.of` satisfy this — they consume the elements without leaking the array. ## @SafeVarargs `@SafeVarargs` is your **promise to the compiler** that the method is safe despite the unchecked warning, and it suppresses the warning **at the declaration and at every call site** (the call-site suppression is the real win — otherwise every caller sees the warning). Constraints: - It may only be applied to methods that **cannot be overridden**: `static` methods, `final` instance methods, **`private` instance methods** (Java 9+), and **constructors**. A non-final, non-static, non-private instance method is rejected, because a subclass override could violate the safety contract. - It is an **assertion you must justify** — the compiler does not verify the safety; it trusts you. Applying it to an unsafe method (like the leaking `toArray` above) silences the very warning that was protecting you. ## Practical guidance - Prefer a `List<T>` parameter over `T...` for generic APIs when you can — it sidesteps the whole issue (this is Effective Java's advice). - If you do expose generic varargs and the method is genuinely read-only, annotate it `@SafeVarargs` so callers aren't spammed with warnings. - Never annotate a method that writes to or leaks the varargs array. ## Summary Generic varargs forces an unsound generic array; the compiler warns about heap pollution. Read-only methods are safe and should carry `@SafeVarargs` (allowed only on non-overridable methods). The annotation suppresses the warning at declaration and call sites but is an unverified promise — use it only when the safety conditions truly hold.