Overloading and varargs

For this lesson, we'll go from the rules you can recite (what makes a signature) to the rules most engineers can't: the exact order in which javac tries conversions, why null breaks overloads, and why generic varargs come with a compiler warning about "heap pollution". Interviewers like this topic because one tiny snippet can test widening, boxing, varargs and compile-time binding at once.

01Signature rules: what counts as "different"

Two methods in the same class can share a name only if their signatures differ (JLS §8.4.2). The signature is the name plus the number, order and types of parameters. Everything else is decoration as far as overloading is concerned.

class Printer {
    void print(int x)            { }
    void print(long x)           { }   // OK: different parameter type
    void print(int x, String s)  { }   // OK: different count
    void print(String s, int x)  { }   // OK: different order

    // int print(int x) { }            // error: already defined (return type ignored)
    // void print(int count) { }       // error: parameter names are ignored
    // void print(int x) throws IOException { }  // error: throws clause ignored

    // void f(List<String> a) { }
    // void f(List<Integer> a) { }     // error: name clash, same erasure f(List)
}

Notice the last one. Generics are erased to List in the class file, so both methods would have the descriptor (Ljava/util/List;)V. The JVM can't tell them apart, and javac refuses to compile them.

Why isn't the return type part of the signature? Because a call can ignore the result. Given print(5); on its own line, there's nothing to tell the compiler which return type you meant.

02Picture it first: a three-phase funnel

Think of overload resolution as a funnel with three filters, each one more permissive than the last. javac gathers every accessible method with the right name, then tries phase 1. Only if nothing fits does it relax the rules and try phase 2, then phase 3. The first phase with a winner ends the search, even if a "better looking" overload would match in a later phase.

Fig. 1

Overload resolution as a funnel: strict (widening only), then loose (adds boxing), then variable arity (adds varargs); the first phase with an applicable method stops and the most specific one wins

This ordering exists for backward compatibility. Boxing and varargs arrived in Java 5. If they had been mixed into the existing rules, recompiling old code could silently switch which overload got called. Putting them in later phases guarantees that any call that compiled under Java 1.4 still binds to the same method.

03Under the hood: watching javac choose

public class Pick {
    static String a(long x)      { return "long"; }
    static String a(Integer x)   { return "Integer"; }

    static String v(Object x)    { return "Object"; }
    static String v(Object... x) { return "Object..."; }

    static String c(long... x)   { return "long..."; }
    static String c(int... x)    { return "int..."; }

    static String d(Object o)    { return "Object"; }
    static String d(String s)    { return "String"; }

    public static void main(String[] args) {
        System.out.println(a(5));     // long
        System.out.println(v(1));     // Object
        System.out.println(c(1));     // int...
        System.out.println(d(null));  // String
        Object o = "hi";
        System.out.println(d(o));     // Object
    }
}

Notice what each line reveals:

• a(5): int → long is a widening primitive conversion, legal in phase 1. int → Integer needs boxing (phase 2), so a(Integer) is never even considered. Widening beats boxing. (Boxing itself is covered in Wrapper classes and autoboxing.)
• v(1): phase 1 fails (an int isn't an Object without boxing). Phase 2 boxes to Integer and widens to Object, so v(Object) wins before varargs is tried. Boxing beats varargs.
• c(1): both need phase 3. Then the most specific rule applies (JLS §15.12.2.5): int... is more specific than long... because int widens to long and not the other way round.
• d(null): null fits both. String is a subtype of Object, so d(String) is more specific.
• d(o): the static type of o is Object, so d(Object) is chosen. The runtime class being String doesn't matter. Overloading is compile-time; only overriding looks at the runtime class.

You can see the decision frozen into the class file. javap -c Pick shows invokestatic Pick.a:(J)Ljava/lang/String;, where J is the descriptor for long. The JVM never re-runs overload resolution; it calls exactly the descriptor javac wrote.

04Ambiguity: when the compiler gives up

The most specific rule needs one candidate that beats all the others. When two candidates each win on a different parameter, or neither type is a subtype of the other, you get error: reference to m is ambiguous.

static void m(String s)  { }
static void m(Integer i) { }
static void g(int x, double y) { }
static void g(double x, int y) { }

m(null);          // ambiguous: String and Integer are unrelated
g(1, 2);          // ambiguous: each overload is better on one argument
m((String) null); // fixed: a cast picks the overload

The null case is the classic interview trap. null converts to every reference type, so it matches both overloads, and there's no subtype relationship to break the tie. A cast is the fix, and it's also good documentation for the reader.

05Varargs is an array in disguise

static int count(Object... items) compiles to a method taking Object[], with the ACC_VARARGS flag set in the class file. At each call site, javac allocates the array for you: count(1, 2) becomes count(new Object[]{1, 2}). A few rules follow directly:

• Only one varargs parameter is allowed, and it must be last.
• count() passes an empty array (length 0), never null.
• Passing an existing array passes it as-is: count(new Object[]{"a", "b"}) sees length 2, not 1 (pass a String[] and you get the same result plus an "inexact argument type" warning).
• count(null) compiles with a warning and passes a null array; count((Object) null) passes an array holding one null.

Inside the method you treat it as an array: items.length, items[0], a for-each loop. One subtlety: in phases 1 and 2, a varargs method still competes as if its last parameter were a plain array. That's why passing an existing array or null binds without ever reaching phase 3.

06Advanced: varargs pitfalls, @SafeVarargs and heap pollution

Mixing varargs with overloading gets ugly fast. Both of these are compile errors in Java 21:

• m(int...) and m(Integer...) with m(1): phase 3 finds both, and neither int nor Integer is a subtype of the other.
• w(int, int...) and w(int...) with w(1): neither is more specific.

Now the senior part. A varargs parameter of a generic type, like T... or List<String>..., can't create a real T[] at runtime because of erasure. The compiler creates an Object[] or List[] instead and warns: possible heap pollution. Heap pollution (JLS §4.12.2) means a variable of a parameterized type points to an object that isn't of that type.

static <T> T[] toArray(T... items) { return items; }        // leaks the array

static <T> T[] pickTwo(T a, T b, T c) { return toArray(a, b); }

String[] s = pickTwo("x", "y", "z");
// ClassCastException: [Ljava.lang.Object; cannot be cast to [Ljava.lang.String;

Inside pickTwo, T is erased, so the varargs array is an Object[]. Returning it to a caller that expects String[] fails at the cast javac inserted. Nothing looked wrong at the call site; the pollution happened two methods away.

@SafeVarargs is your promise that the method only reads the elements and never stores into the array or lets it escape. It silences the warning for callers. It's allowed on constructors, static methods, final instance methods and, since Java 9, private instance methods: places where an override can't break the promise.

@SafeVarargs
static <T> List<T> listOf(T... items) {
    List<T> out = new ArrayList<>(items.length);
    for (T t : items) out.add(t);   // read-only use: safe
    return out;
}

My default: avoid overloads that differ only by boxed vs primitive or by varargs. Give them different names (removeAt, removeValue) unless the overloads do the same thing and the choice can never surprise a caller.

07How to say it in the interview

When I ask this, I'm listening for whether you know overloading is decided at compile time from static types, whether you can name the three phases in order, and whether you can explain an ambiguity instead of guessing. Mentioning heap pollution and @SafeVarargs without prompting is a strong senior signal.

Here's how this might look if you sketch it on the whiteboard: