Java Method Signature Overloading: Rules and Resolution

What Defines a Method Signature in Java

In Java, a method signature consists of the method name and the parameter list. The parameter list includes the number, order, and types of parameters. The return type is not part of the signature. This distinction matters because it determines what counts as method overloading.

Java method signature overloading lets you define multiple methods with the same name in the same class, as long as their parameter lists differ. The compiler decides which method to call based on the arguments supplied at the call site.

public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }

    public int add(int a, int b, int c) {
        return a + b + c;
    }
}

Both methods share the name add but have different parameter counts, so they are valid overloads. When you call calculator.add(2, 3), the compiler picks the two-parameter version; when you call calculator.add(2, 3, 4), it picks the three-parameter version.

What Does Not Count as Overloading

The return type is not part of the method signature. This means you cannot define two methods that differ only in their return type:

public class Example {
    public int value() {
        return 1;
    }

    // Compilation error: value() is already defined
    public double value() {
        return 1.0;
    }
}

The same applies to access modifiers, the static keyword, and checked exceptions. Changing any of these without changing the parameter list does not create a new signature. The compiler reports a duplicate method error.

This rule exists because the compiler cannot determine which method to call based solely on the expected return type in all contexts. For example, example.value() as a standalone expression statement would be ambiguous.

Overloading with Different Parameter Types

Beyond parameter count, you can overload methods by changing the parameter types. The order of parameters also matters when the types are different.

public class Logger {
    public void log(String message) {
        System.out.println(message);
    }

    public void log(int code) {
        System.out.println("Code: " + code);
    }

    public void log(String message, int code) {
        System.out.println(message + " (" + code + ")");
    }

    public void log(int code, String message) {
        System.out.println("(" + code + ") " + message);
    }
}

Here, log("error", 500) and log(500, "error") call different methods because the parameter order differs. The compiler uses the static types of the arguments to select the most specific applicable method.

Compile-Time Resolution and Ambiguity

Overloaded methods are resolved at compile time, not at runtime. The compiler follows a three-phase process:

1. Phase 1: Identify applicable methods without allowing boxing, unboxing, or varargs.
2. Phase 2: Allow boxing and unboxing conversions.
3. Phase 3: Allow varargs.

Within each phase, the compiler picks the most specific method. If multiple methods are equally specific, the call is ambiguous and fails to compile.

public class Ambiguous {
    public void process(String s) {
        System.out.println("String");
    }

    public void process(Object o) {
        System.out.println("Object");
    }
}

Calling process("hello") selects the String version because String is more specific than Object. However, if you add a third overload:

public void process(CharSequence cs) {
    System.out.println("CharSequence");
}

The call process("hello") still picks String because String is a subtype of both CharSequence and Object.

A genuinely ambiguous case arises when the argument is null and the overloads are unrelated types:

public class AmbiguousNull {
    public void handle(String s) {
        System.out.println("String");
    }

    public void handle(Integer i) {
        System.out.println("Integer");
    }
}

Calling handle(null) fails to compile because neither String nor Integer is more specific than the other. You must cast the argument to resolve the ambiguity: handle((String) null).

Overloading with Primitive Widening

When you pass a primitive argument, the compiler considers widening conversions before boxing. This affects which overload gets selected.

public class Widening {
    public void print(long value) {
        System.out.println("long: " + value);
    }

    public void print(Integer value) {
        System.out.println("Integer: " + value);
    }
}

Calling print(42) with an int literal selects the long version because widening an int to long is preferred over boxing it to Integer. This ordering is defined by the Java Language Specification: widening takes precedence over boxing, which takes precedence over varargs.

Understanding this precedence helps prevent surprising behavior when you add overloads to existing code. Adding a print(Integer) overload to a class that already has print(long) will not change the behavior of existing print(42) calls.

Varargs and Overloading

Varargs parameters complicate overloading because a varargs method is applicable to a range of argument counts. The compiler treats varargs as the least preferred option.

public class VarargsExample {
    public void join(String separator, String... parts) {
        System.out.println(String.join(separator, parts));
    }

    public void join(String separator, String first, String second) {
        System.out.println(first + separator + second);
    }
}

Calling join("-", "a", "b") selects the fixed-arity method because it is more specific than the varargs version. Calling join("-", "a", "b", "c") falls back to the varargs method.

The risk with varargs overloading is ambiguity when a call could match multiple varargs signatures. For example, overloading a method with String... and Integer... creates an ambiguous call for method(null). In practice, avoid overloading varargs methods with other varargs methods.

Maintainability Considerations

Method overloading improves readability when the overloads represent genuinely different parameter shapes for the same logical operation. It becomes a maintenance problem when overloads accumulate without clear rules.

A common issue is overloading with both a general and a specialized parameter type. If you add an overload that accepts a supertype, existing calls may silently resolve to a different method than the author intended. The compiler picks the most specific method, but the resolution rules are not always obvious to every developer reading the code.

When designing overloads, keep the parameter types distinct enough that call sites are unambiguous. If two overloads accept types that share a common subtype, document the resolution behavior or consider using differently named methods instead.

Another practical concern is that overloading interacts poorly with null arguments. Every call that passes a literal null to an overloaded method forces the reader to trace the resolution rules. Prefer overloads that do not accept null, or use a single method with an explicit type check.

Overloading vs Overriding

Overloading is sometimes confused with overriding, but they are distinct mechanisms. Overriding occurs when a subclass redefines a method with the same signature as a method in its superclass. Overloading occurs within the same class and involves different signatures.

public class Base {
    public void execute(String input) {
        System.out.println("Base: " + input);
    }
}

public class Derived extends Base {
    @Override
    public void execute(String input) {
        System.out.println("Derived: " + input);
    }

    public void execute(int input) {
        System.out.println("Derived int: " + input);
    }
}

The @Override method in Derived overrides the base method. The execute(int) method overloads the execute(String) method within Derived. Both mechanisms can coexist, but they serve different purposes: overriding enables runtime polymorphism, while overloading is resolved at compile time.

When a subclass overloads a method from its superclass, calls through a superclass reference will not see the overload. If you hold a Base reference to a Derived instance and call execute(5), the compiler looks at Base's methods, finds no execute(int), and reports a compilation error. This is a common source of confusion when overloads are spread across a class hierarchy.