add(int, int) and add(double, double) can coexist because the argument types differ, so the compiler knows which one you meant. The value is that callers do not have to remember three different names for what is conceptually one operation. The rule that catches almost everyone is the one thing you cannot vary. Two methods that differ only in return type are a compile error. This is not Java being fussy; it is a direct consequence of how the compiler picks. Java decides which method to call from the arguments alone, because that is all the call site has at that point. If two candidates were identical in parameters but differed in return type, there would be no way to choose, and the code would be ambiguous. Note the contrast with return types themselves, which are entirely free in an overload. Resolution happens at compile time in three passes. An exact match wins outright. Failing that, Java applies widening conversions, which are safe, such as promoting an int to a double. Only if neither works does it try unboxing or boxing. That ordering is why add(1, 2) picks the int version rather than the Integer one, and it is the ordering you need to remember to predict any given call.The compiler identifies a method by its name and its parameter types. Everything else in the declaration is decoration as far as overloading is concerned.
// SAME NAME, DIFFERENT PARAMETER LISTS: all legal overloads
public static int add(int a, int b) {
...
}public static double add(double a, double b) {
...
}public static int add(int a, int b, int c) {
...
}public static int add(int[] values) {
...
}
Return type cannot be the only difference. This fails to compile:
public static int getValue() {
return 1;
}public static double getValue() {
return 1.5;
}// COMPILE ERROR: getValue() is already definedThe reason is worth understanding rather than memorising. At the call site, the compiler has only the arguments to work from. If two methods matched every argument equally well, there would be no tie-breaker, and the code would be genuinely ambiguous. Even with a variable involved, it does not help:
double result = getValue();
// still ambiguous, the return type
// is not used to select the methodIt is a compile error, not a warning. If you want two versions that differ only by result type, give them different names: getIntValue() and getDoubleValue(), or return a type that holds both.
| Difference between the two methods | Valid overload? |
|---|---|
| Parameter types | Yes, this is overloading |
| Number of parameters | Yes |
| Return type only | No, compile error |
| Parameter names only | No, names are not part of the identity |
| Access modifier | Allowed to differ, but does not make it a valid overload on its own |
static versus instance | No, the two would clash |
throws clause | Allowed to differ, but does not make it a valid overload on its own |
The same rules apply to constructors, and this is where overloading is used most. A class can have as many constructors as it needs as long as their parameter lists differ.
public class Point {
private final int x;
private final int y;
public Point() {
// origin
this(ORIGIN, ORIGIN);
} public Point(int x) {
// one axis set
this(x, ORIGIN);
} public Point(int x, int y) {
// both axes
this.x = x;
this.y = y;
}
}Note the this(...) calls. Rather than duplicating the assignment logic, each shorter constructor delegates to the fullest one. That is the pattern to follow: one constructor does the work, the others forward to it, so there is a single place where the fields are set.
Resolution happens at compile time, in three passes, and the order matters.
| Pass | What it allows | Example |
|---|---|---|
| Pass one, exact match | Identical types, no conversion | add(int, int) for two int arguments |
| Pass two, widening | Safe primitive promotion, in order | byte to int to long to float to double |
| Pass three, boxing | Primitive to wrapper and back | int to Integer, or an Integer to int |
This ordering is not arbitrary. Widening never loses information, so Java prefers it over boxing, which allocates an object. The practical effect is that a call with primitives picks a primitive overload in preference to a wrapper one.
public static String show(int value) {
return "int";
}public static String show(Integer value) {
return "Integer";
}show(PRIMITIVE);
// "int", the exact match wins
show(BOXED);
// "Integer", exact match againWidening only ever goes one way, following the order above. A long will not silently become an int, because that could discard digits. If you need that, the conversion must be explicit.
Ambiguity happens when no single method is more specific than the others. The compiler refuses rather than guessing, which is one of the safer corners of the language.
public static int add(int a, long b) {
...
}public static int add(long a, int b) {
...
}add(ONE, TWO);
// COMPILE ERROR: both match equally wellThe classic triggers are worth memorising because they all produce the same confusing error.
| Situation | Why it fails |
|---|---|
| Widening versus boxing | Neither is a subtype of the other, so neither wins |
| Two reference types with no inheritance link | Neither is more specific |
null passed to two unrelated types | null matches every reference type |
| An argument needing a narrowing conversion | No overload accepts it |
int versus long versus Integer together | Widening and boxing compete with no clear winner |
The fix is usually to cast at the call site so the intent is explicit, or to remove one of the competing overloads. Adding a third overload to a two-way ambiguity rarely helps.
Because Type... name is really Type[] name, a varargs method and an array method cannot coexist. They are the same signature.
public static int sum(int... values) {
...
}// public static int sum(int[] values) { ... }
// COMPILE ERROR: these are the same signature
sum(ONE);
// zero or more ints, wrapped into an array
sum(ONE, TWO, THREE);What you can do is pair varargs with a fixed-arity version. The fixed one is preferred for the exact argument count, and the varargs one takes everything else.
public static String join(String a, String b) {
return a + "-" + b;
// chosen for exactly two
}public static String join(String... parts) {
return String.join("-", parts);
// chosen for any other count
}Be aware that a no-argument call is ambiguous between join() and the varargs version if you also define a zero-argument join(), so avoid that shape.
Overloading earns its place in two situations. The first is the same concept, different input types, like println accepting anything printable. The second is optional arguments without the complexity, where a shorter overload forwards to the fuller one.
It becomes a liability when the overloads are not conceptually related. Two methods sharing a name but doing different jobs means a reader has to check the parameter types to know which is which, and the name stops carrying information.
Two habits keep it readable. First, make the shortest overload delegate to the longest, so the logic exists once. Second, keep the count modest; more than three or four variants of one name becomes hard to hold in mind, and a small enum or a parameter object often reads better.
| Mistake | Symptom | Fix |
|---|---|---|
| Differing only by return type | Compile error, already defined | Change the parameters or rename the method. |
| Differing only by parameter names | Compile error, already defined | Names are not part of a signature. |
| varargs plus an array version | Compile error, same signature | Keep just the varargs form. |
Passing null to unrelated types | Ambiguous method call | Cast to the type you mean. |
| Two equally specific candidates | Ambiguous method call | Cast at the call site, or drop one. |
| Assuming a wrapper overload is chosen | The primitive version runs instead | Exact and widening passes come first. |
| Copy-pasted body in every overload | Bug fixed in one copy only | Have the short ones delegate to the long one. |
| Overloading unrelated operations | The name no longer describes the work | Give them separate names. |
Giving several methods the same name while making them distinguishable by their parameter lists, so the compiler can pick the right one from the argument types. add(int, int) and add(double, double) can coexist, and callers use the same name for what is conceptually one operation.
No. It is a compile error. The compiler must select a method using the arguments alone, because the return type is not available at the point where the call is made. Two candidates that matched every argument equally would be genuinely ambiguous.
In three passes at compile time. An exact match wins first. Failing that, Java tries widening primitive conversions, which are lossless. Only if neither succeeds does it consider boxing or unboxing, since allocating an object is the most expensive option.
Two or more overloads matching the arguments equally well, with neither being more specific. Common triggers are widening competing with boxing, unrelated reference types with no inheritance link, and passing null to several unrelated types. Casting at the call site resolves it.
No. Since Type... is compiled as Type[], the two are the same signature and declaring both is a compile error. You can pair varargs with a fixed-arity version, and the fixed one is preferred when the argument count matches exactly.
Overloading is resolved within a single class. A subclass method with the same name but different parameters is technically a new method rather than an overload, since the compiler picks between them using the reference type, not at runtime. Same-signature methods across a hierarchy must be overrides, which is a separate mechanism.
It is good when the overloads represent one concept with different inputs, such as println accepting anything printable. It hurts when unrelated operations share a name, because a reader must check the parameter types to know which method runs, and the name stops carrying information.
No. Two methods differing only in parameter names are a compile error, because callers pass positionally and never mention the names. Only the number of parameters and their types form the identity the compiler uses.
// Demonstrates method overloading rules, resolution, and ambiguity.
public class OverloadingDemo {
private static final int ORIGIN = 0;
private static final int TEN = 10;
private static final int TWENTY = 20;
private static final int THIRTY = 30;
private static final int ONE = 1;
private static final int TWO = 2;
private static final int THREE = 3;
private static final double TEN_POINT_FIVE = 10.5;
private static final double TWENTY_POINT_FIVE = 20.5;
private static final Integer BOXED_TEN = Integer.valueOf(TEN);
// 1) SAME NAME, DIFFERENT PARAMETER LISTS
public static int add(int a, int b) {
return a + b;
} public static double add(double a, double b) {
return a + b;
} public static int add(int a, int b, int c) {
return a + b + c;
} public static int add(int[] values) {
int total = 0;
for (int value : values) {
total = total + value;
} return total;
} // 2) SHOWS WHICH OVERLOAD WON
public static String show(int value) {
return "int";
} public static String show(Integer value) {
return "Integer";
} // 3) THE SHORT OVERLOAD DELEGATES TO THE LONG ONE
public static String join(String a, String b) {
return a + "-" + b;
} public static String join(String... parts) {
return String.join("-", parts);
} // 4) CONSTRUCTOR OVERLOADING, EACH ONE DELEGATING
Point() {
this(ORIGIN, ORIGIN);
} Point(int x) {
this(x, ORIGIN);
} Point(int x, int y) {
System.out.println(" Point(" + x + ", " + y + ")");
} public static void main(String[] args) {
// 1) THE COMPILER PICKS FROM THE ARGUMENT TYPES
System.out.println("add(10, 20) = " + add(TEN, TWENTY));
System.out.println("add(10.5, 20.5) = " + add(TEN_POINT_FIVE, TWENTY_POINT_FIVE));
System.out.println("add(10, 20, 30) = " + add(TEN, TWENTY, THIRTY));
System.out.println("add(new int[]{1,2,3}) = " + add(new int[] {
ONE, TWO, THREE
}));
// 2) EXACT MATCH WINS OVER THE WRAPPER VERSION
System.out.println("show(10) = " + show(TEN));
System.out.println("show(Integer.valueOf(10)) = " + show(BOXED_TEN));
// 3) FIXED ARITY IS PREFERRED FOR THE EXACT COUNT
System.out.println("join(\"a\", \"b\") = " + join("a", "b"));
System.out.println("join(\"a\", \"b\", \"c\") = " + join("a", "b", "c"));
// 4) CONSTRUCTOR OVERLOADING
System.out.println("constructors:");
new Point();
new Point(TEN);
new Point(TEN, TWENTY);
// THE TWO BELOW DO NOT COMPILE, AND ARE SHOWN AS COMMENTS
//
// 5) DIFFERING ONLY BY RETURN TYPE: compile error
// public static int getValue() { return 1; }
// public static double getValue() { return 1.5; }
//
// 6) VARARGS PLUS AN ARRAY VERSION: compile error, same signature
// public static int sum(int... values) { return 0; }
// public static int sum(int[] values) { return 0; }
//
// 7) TWO EQUALLY SPECIFIC CANDIDATES: ambiguous method call
// public static int widen(int a, long b) { return 0; }
// public static int widen(long a, int b) { return 0; }
// widen(1, 2); // both match, neither wins
}
}/*
ACTUAL OUTPUT:
add(10, 20) = 30
add(10.5, 20.5) = 31.0
add(10, 20, 30) = 60
add(new int[]{1,2,3}) = 6
show(10) = int
show(Integer.valueOf(10)) = Integer
join("a", "b") = a-b
join("a", "b", "c") = a-b-c
constructors:
Point(0, 0)
Point(10, 0)
Point(10, 20)
THE SIX THINGS TO REMEMBER
1) A SIGNATURE IS THE NAME PLUS THE PARAMETER TYPES. Nothing else
counts, so return type, parameter names, access modifiers, and
throws clauses can never make a valid overload.
2) YOU CANNOT OVERLOAD ON RETURN TYPE. The compiler chooses using
the arguments alone, so two candidates would be ambiguous.
3) RESOLUTION RUNS IN THREE PASSES: exact match, then widening,
then boxing. Widening is lossless, so it beats boxing, which
has to allocate an object.
4) WIDENING ONLY GOES ONE WAY, following byte, short, int, long,
float, double. Narrowing needs an explicit cast.
5) VARARGS IS AN ARRAY, SO IT CANNOT OVERLOAD AN ARRAY VERSION.
6) HAVE THE SHORT OVERLOAD DELEGATE TO THE LONG ONE with this(...)
in a constructor or a plain call in a method, so the logic is
written once and fixed once.
*/