{"title":"Method Overloading","description":"","content":"Real code rarely has one perfect shape for a method. Adding a `Product` to a cart might need its full information, or just a name and price, or a quantity attached. Three different names like `addProductObject`, `addProductByName`, and `addProductWithQuantity` would force every call site to remember which spelling matches which situation. Java lets all three methods share the same name, as long as the compiler can tell them apart by their parameter list. That feature is called method overloading, and it's the focus of this lesson.\n\nThis lesson starts with the rules that govern when two methods are \"different enough\" to coexist, walks through how the compiler picks which one to call, and finishes with common patterns and pitfalls.\n\n---\n\n# What Overloading Means\n\nTwo methods are **overloaded** when they share the same name in the same class but have different parameter lists. Different in this case means a different number of parameters, different parameter types, or the same types in a different order. The compiler treats each overload as a distinct method. Which one runs at a given call site is decided at compile time, based on the types of the arguments passed.\n\nA small cart class with three overloads of `addItem`.\n\n\n```java\npublic class Cart {\n public static void addItem(String name) {\n System.out.println(\"Added: \" + name + \" (qty 1, no price)\");\n }\n\n public static void addItem(String name, int quantity) {\n System.out.println(\"Added: \" + name + \" x\" + quantity);\n }\n\n public static void addItem(String name, double price, int quantity) {\n double subtotal = price * quantity;\n System.out.println(\"Added: \" + name + \" x\" + quantity + \" = $\" + subtotal);\n }\n\n public static void main(String[] args) {\n addItem(\"Wireless Mouse\");\n addItem(\"USB Cable\", 2);\n addItem(\"Headphones\", 49.99, 3);\n }\n}\n```\n\n\nThree calls, three different methods, one name. From the caller's point of view, `addItem` is one operation with a flexible shape. From the compiler's point of view, there are three completely separate methods, and the argument list at the call site picks one.\n\nThe win is at the call site. There is no need to remember three names, and no need to pass placeholder values like `-1` for \"no price\" or `null` for \"no quantity\" just to match a single fixed signature. The method called matches the information available.\n\n\n> **INFO**\n>\n> **A quick note on overriding.** Overloading is not the same as overriding. Overloading means multiple methods with the same name in one class, distinguished by their parameters. Overriding means a subclass replacing an inherited method with its own version. The two should not be conflated.\n\n\n---\n\n# The Rules: What Makes an Overload Valid\n\nTwo methods with the same name are valid overloads only when their parameter lists differ in at least one of these ways:\n\n\n| Difference | Example |\n| --- | --- |\n| Different number of parameters | `addItem(String)` vs `addItem(String, int)` |\n| Different parameter types | `addItem(String)` vs `addItem(Product)` |\n| Same types in a different order | `applyDiscount(Product, double)` vs `applyDiscount(double, Product)` |\n\n\nThe method's **name** plus its **ordered list of parameter types** is called its signature. As long as two signatures differ, the methods can coexist.\n\nWhat does **not** count:\n\n- **The return type alone.** Two methods with the same name and parameter list, but different return types, are not overloads. They're a compile error.\n- **Parameter names.** `addItem(String name)` and `addItem(String productName)` have the same signature, because the compiler only looks at types.\n- **`final`, access modifiers, or `throws` clauses.** Marking a parameter `final` or changing whether the method is `public` or `private` doesn't create a new signature.\n\nA class showing one valid set of overloads and one combination that fails to compile.\n\n\n```java\npublic class Pricing {\n public static double calculatePrice(double base) {\n return base;\n }\n\n public static double calculatePrice(double base, double discountPercent) {\n return base * (1 - discountPercent / 100);\n }\n\n public static double calculatePrice(double base, int quantity) {\n return base * quantity;\n }\n\n // The following method would NOT compile if uncommented:\n // public static int calculatePrice(double base) { return (int) base; }\n // Reason: same name, same parameter list as the first method.\n // Return type alone is not enough to overload.\n\n public static void main(String[] args) {\n System.out.println(calculatePrice(49.99));\n System.out.println(calculatePrice(49.99, 10.0));\n System.out.println(calculatePrice(49.99, 3));\n }\n}\n```\n\n\nThe three working overloads have parameter lists `(double)`, `(double, double)`, and `(double, int)`. The commented-out version conflicts with the first overload because only its return type is different, and that's not a valid difference.\n\n---\n\n# Why Return Type Alone Doesn't Work\n\nThe compiler picks an overload based on the arguments at the call site. The return type isn't part of that decision, because in plenty of situations, the caller ignores the return value entirely.\n\n\n```java\npublic class IgnoredReturn {\n public static int addToCart(String item) {\n return 1;\n }\n\n // Imagine a second version with the same parameters but a different return type:\n // public static double addToCart(String item) { return 1.0; }\n\n public static void main(String[] args) {\n addToCart(\"Wireless Mouse\"); // return value thrown away\n }\n}\n```\n\n\nIf both versions existed, which one should the compiler call when the return value is discarded? Nothing in `addToCart(\"Wireless Mouse\")` tells the compiler whether the `int` version or the `double` version was intended. The argument list is identical. Java avoids the ambiguity by forbidding the situation outright: two methods with the same name and parameter list are not allowed, no matter what their return types are.\n\nThe same reasoning applies to assignments. Even when the return value is used, type inference doesn't always pin a single answer. Consider `int total = addToCart(\"Mouse\")`. Both the `int` and `double` versions could plausibly fit (with a narrowing cast for the `double`). Java avoids inventing rules to resolve that and instead disallows the overload pair.\n\nFor two methods that do \"the same thing\" but produce different types, give them different names. `priceAsCents()` returning `int` and `priceAsDollars()` returning `double` is a clearer design than trying to overload a single name.\n\n---\n\n# How the Compiler Picks an Overload\n\nFor a call like `addItem(\"Mouse\", 3)`, the compiler asks: which of the overloaded methods named `addItem` can accept these arguments, and which is the best match? The answer comes out of a three-phase search. Phase 1 looks for an exact or widening match without any boxing or varargs. Phase 2 reconsiders with autoboxing and unboxing turned on. Phase 3 reconsiders again, now allowing varargs. The first phase that finds a match wins, and if more than one method ties inside the same phase, the compiler picks the most specific one. If it can't pick one, the result is a compile error.\n\n\n```mermaid\nflowchart TD\n Call[Call site:
addItem name 3]:::cyan --> Phase1{Phase 1
Exact or widening
no boxing, no varargs}:::orange\n Phase1 -->|match found| Done1[Pick most specific match]:::green\n Phase1 -->|no match| Phase2{Phase 2
Allow autoboxing
and unboxing}:::orange\n Phase2 -->|match found| Done2[Pick most specific match]:::green\n Phase2 -->|no match| Phase3{Phase 3
Allow varargs}:::teal\n Phase3 -->|match found| Done3[Pick most specific match]:::green\n Phase3 -->|no match| Fail[Compile error:
no matching method]:::red\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe diagram captures the order. The intuition is: the compiler prefers an answer that doesn't have to do anything special with the arguments. Widening (`int` to `long`, `int` to `double`) is automatic and happens in Phase 1. Boxing (turning `int` into `Integer`) is more expensive and only happens if nothing in Phase 1 matched. Varargs are the last resort because they involve allocating an array.\n\n### Phase 1: Exact and Widening Matches\n\nIf an argument type exactly matches a parameter type, that's the easiest case. If it doesn't, the compiler tries a widening primitive conversion (`byte` to `short` to `int` to `long` to `float` to `double`) or a widening reference conversion (subclass to superclass).\n\n\n```java\npublic class ResolutionPhase1 {\n public static void log(int n) {\n System.out.println(\"int: \" + n);\n }\n\n public static void log(long n) {\n System.out.println(\"long: \" + n);\n }\n\n public static void log(double n) {\n System.out.println(\"double: \" + n);\n }\n\n public static void main(String[] args) {\n log(5); // exact match: int\n log(5L); // exact match: long\n log(5.0); // exact match: double\n short small = 5;\n log(small); // widens short to int\n }\n}\n```\n\n\nThe fourth call passes a `short`. There's no `log(short)` overload, but `short` widens to `int` (the most specific available match), so `log(int)` wins. Note that `short` also widens to `long` and `double`, but those would lose specificity. The compiler picks the closest fit.\n\n### Phase 1 Tie-Breaker: Most Specific Wins\n\nWhen two overloads in the same phase could both accept the arguments, the compiler picks the one whose parameter types are \"more specific\". For primitives, more specific means smaller-or-equal in the widening chain. For reference types, it means the more derived class.\n\n\n```java\npublic class MostSpecific {\n public static void price(double amount) {\n System.out.println(\"double overload: \" + amount);\n }\n\n public static void price(int amount) {\n System.out.println(\"int overload: \" + amount);\n }\n\n public static void main(String[] args) {\n price(50); // int literal\n price(50.0); // double literal\n }\n}\n```\n\n\nBoth overloads could accept `50` (the `int` directly, the `double` via widening), but `int` is more specific than `double`, so `price(int)` wins. The second call passes a `double` literal, which only matches the `double` overload.\n\n### Phase 2: Autoboxing and Unboxing\n\nIf Phase 1 found nothing, the compiler retries with boxing turned on. Now `int` can match an `Integer` parameter (boxing) and `Integer` can match an `int` parameter (unboxing).\n\n\n```java\npublic class ResolutionPhase2 {\n public static void track(int orderId) {\n System.out.println(\"int overload\");\n }\n\n public static void track(Integer orderId) {\n System.out.println(\"Integer overload\");\n }\n\n public static void main(String[] args) {\n int primitive = 42;\n Integer boxed = 42;\n\n track(primitive); // Phase 1 matches int directly\n track(boxed); // Phase 1 matches Integer directly\n }\n}\n```\n\n\nBoth calls find their match in Phase 1. Boxing isn't needed here because each overload directly matches one of the argument types.\n\nThe Phase 2 behavior shows up when only the boxed version exists.\n\n\n```java\npublic class BoxingOnly {\n public static void track(Integer orderId) {\n System.out.println(\"Tracking Integer order: \" + orderId);\n }\n\n public static void main(String[] args) {\n track(42); // int gets autoboxed to Integer\n }\n}\n```\n\n\nThe literal `42` is an `int`. There's no `track(int)`, so Phase 1 fails. Phase 2 retries with autoboxing, finds `track(Integer)`, and the call succeeds.\n\nAutoboxing creates a new `Integer` object (unless the value is cached, which Java does for small ints). In a tight loop, picking the boxed overload when a primitive one would do means extra allocations. When both `add(int)` and `add(Integer)` are available, prefer the primitive form for hot code.\n\n### Phase 3: Varargs\n\nIf Phases 1 and 2 both fail, the compiler tries varargs methods. Varargs (`String...`) are a way to accept any number of arguments of a given type. For now, the relevant point for overload resolution is that they get tried last.\n\n\n```java\npublic class VarargsLast {\n public static void log(int a, int b) {\n System.out.println(\"two-arg overload\");\n }\n\n public static void log(int... values) {\n System.out.println(\"varargs overload, count=\" + values.length);\n }\n\n public static void main(String[] args) {\n log(1, 2); // fixed-arity wins over varargs\n log(1, 2, 3); // only varargs can take 3 args\n }\n}\n```\n\n\nThe first call has a fixed-arity match in Phase 1, so the two-arg version wins even though the varargs version could also accept two values. The second call has no fixed match for three arguments, so Phase 3 picks the varargs.\n\n---\n\n# Ambiguous Calls and How to Fix Them\n\nThe compiler refuses to guess when two overloads tie in the same phase and neither is more specific than the other. That situation is called an **ambiguous method call**, and it shows up as a compile error.\n\n\n```java\npublic class AmbiguousExample {\n public static void price(int a, double b) {\n System.out.println(\"int, double\");\n }\n\n public static void price(double a, int b) {\n System.out.println(\"double, int\");\n }\n\n public static void main(String[] args) {\n price(5, 10); // ambiguous: both overloads need one widening\n }\n}\n```\n\n\nThe compiler error reads like this:\n\n\n```shell\nerror: reference to price is ambiguous\n price(5, 10);\n ^\n both method price(int,double) in AmbiguousExample and method price(double,int) in AmbiguousExample match\n```\n\n\nBoth arguments are `int` literals. To call `price(int, double)`, the second `int` widens to `double`. To call `price(double, int)`, the first `int` widens to `double`. Each overload needs exactly one widening, and neither is \"more specific\" than the other. Java won't flip a coin.\n\nThe fix is to make the intent explicit with a cast.\n\n\n```java\npublic class AmbiguousFixed {\n public static void price(int a, double b) {\n System.out.println(\"int, double\");\n }\n\n public static void price(double a, int b) {\n System.out.println(\"double, int\");\n }\n\n public static void main(String[] args) {\n price(5, (double) 10); // forces the int, double overload\n price((double) 5, 10); // forces the double, int overload\n }\n}\n```\n\n\nA cast on an argument tells the compiler the type before resolution even starts. Once one argument has a fixed type that only matches one overload, the ambiguity disappears.\n\nAmbiguity also shows up with `null` arguments when more than one reference-type overload could accept it.\n\n\n```java\npublic class NullAmbiguity {\n public static void search(String query) {\n System.out.println(\"String overload\");\n }\n\n public static void search(Integer code) {\n System.out.println(\"Integer overload\");\n }\n\n public static void main(String[] args) {\n // search(null); // ambiguous\n search((String) null); // forces the String overload\n search((Integer) null); // forces the Integer overload\n }\n}\n```\n\n\nA bare `null` could go to either overload, since `null` is assignable to any reference type. The cast picks one.\n\n---\n\n# Useful Overload Patterns\n\nMost overloads in production Java fall into one of a few patterns. Recognizing them helps decide when overloading is appropriate.\n\n### Pattern 1: Default Values via Delegation\n\nA common reason to overload is to provide convenient defaults for parameters the caller usually doesn't care about. The shorter overloads delegate to the fullest one so the actual logic lives in exactly one place.\n\n\n```java\npublic class CartWithDefaults {\n public static void addItem(String name) {\n addItem(name, 0.0, 1);\n }\n\n public static void addItem(String name, int quantity) {\n addItem(name, 0.0, quantity);\n }\n\n public static void addItem(String name, double price, int quantity) {\n double subtotal = price * quantity;\n System.out.println(\"Added \" + name + \" x\" + quantity + \" @ $\" + price + \" = $\" + subtotal);\n }\n\n public static void main(String[] args) {\n addItem(\"Free Sample\");\n addItem(\"USB Cable\", 2);\n addItem(\"Headphones\", 49.99, 3);\n }\n}\n```\n\n\nAll three calls funnel through the same three-argument method, so any future change (logging, validation, stock check) only needs to land in one place. The shorter overloads are pure pass-throughs. Spreading the logic across all three would require updating each one in lockstep.\n\n### Pattern 2: Same Action, Different Input Shape\n\nWhen the same conceptual action can take its input in more than one form, overloading lets the caller hand over whatever they happen to have.\n\n\n```java\npublic class Catalog {\n public static void addProduct(Product product) {\n System.out.println(\"Adding existing product: \" + product.name);\n }\n\n public static void addProduct(String name, double price) {\n Product fresh = new Product(name, price);\n addProduct(fresh);\n }\n\n public static void main(String[] args) {\n Product existing = new Product(\"Wireless Mouse\", 29.99);\n addProduct(existing);\n addProduct(\"USB Cable\", 9.99);\n }\n\n static class Product {\n String name;\n double price;\n\n Product(String name, double price) {\n this.name = name;\n this.price = price;\n }\n }\n}\n```\n\n\nThe two-argument overload builds a `Product` and forwards to the single-argument one, so the \"real\" work happens in one method. This is a typical pattern for builder-style APIs where the caller might have a complete object or only a couple of fields.\n\n### Pattern 3: Search Methods With Different Filters\n\nOverloads also fit when the same query can be narrowed in several ways. The method name describes the action; the parameter list describes the filter.\n\n\n```java\nimport java.util.List;\n\npublic class ProductSearch {\n public static void searchProducts(String keyword) {\n System.out.println(\"Searching by keyword: \" + keyword);\n }\n\n public static void searchProducts(String keyword, String category) {\n System.out.println(\"Searching for '\" + keyword + \"' in \" + category);\n }\n\n public static void searchProducts(String keyword, double minPrice, double maxPrice) {\n System.out.println(\"Searching for '\" + keyword + \"' between $\" + minPrice + \" and $\" + maxPrice);\n }\n\n public static void searchProducts(List categories) {\n System.out.println(\"Searching across categories: \" + categories);\n }\n\n public static void main(String[] args) {\n searchProducts(\"mouse\");\n searchProducts(\"mouse\", \"Electronics\");\n searchProducts(\"mouse\", 10.0, 50.0);\n searchProducts(List.of(\"Electronics\", \"Accessories\"));\n }\n}\n```\n\n\nEach overload represents a different way to ask the same question. Callers don't have to learn four method names; they call `searchProducts` and pass whichever filter is available.\n\n### Pattern 4: Overloaded Discount Application\n\nA common e-commerce variant: applying a discount can mean a percentage off, a flat dollar amount off, or a coupon code that resolves into a discount internally. Same name, three shapes.\n\n\n```java\npublic class DiscountService {\n public static double applyDiscount(double price, double percentOff) {\n return price * (1 - percentOff / 100);\n }\n\n public static double applyDiscount(double price, int dollarsOff) {\n return Math.max(0, price - dollarsOff);\n }\n\n public static double applyDiscount(double price, String couponCode) {\n if (couponCode.equals(\"WELCOME10\")) {\n return applyDiscount(price, 10.0);\n }\n if (couponCode.equals(\"SAVE5\")) {\n return applyDiscount(price, 5);\n }\n return price;\n }\n\n public static void main(String[] args) {\n System.out.println(\"Percent off: $\" + applyDiscount(49.99, 20.0));\n System.out.println(\"Flat off: $\" + applyDiscount(49.99, 5));\n System.out.println(\"Coupon: $\" + applyDiscount(49.99, \"WELCOME10\"));\n }\n}\n```\n\n\nThe second and first overloads differ only in whether their second parameter is `int` or `double`. That makes `applyDiscount(49.99, 5)` resolve to the `int` version (because `5` is an `int` literal) and `applyDiscount(49.99, 20.0)` resolve to the `double` version. Passing the wrong literal type selects the wrong overload, which is one of the small risks of overloading on closely related numeric types. When in doubt, be explicit at the call site, or use distinct method names like `applyPercentDiscount` and `applyDollarDiscount`.\n\n---\n\n# Overloading Constructors\n\nMethods aren't the only thing that can be overloaded. Constructors follow the same rules. A quick example here shows the same idea applies.\n\n\n```java\npublic class Order {\n private String customerName;\n private int itemCount;\n private double total;\n\n public Order(String customerName) {\n this(customerName, 0, 0.0);\n }\n\n public Order(String customerName, int itemCount) {\n this(customerName, itemCount, 0.0);\n }\n\n public Order(String customerName, int itemCount, double total) {\n this.customerName = customerName;\n this.itemCount = itemCount;\n this.total = total;\n }\n\n @Override\n public String toString() {\n return customerName + \": \" + itemCount + \" items, $\" + total;\n }\n\n public static void main(String[] args) {\n System.out.println(new Order(\"Alice\"));\n System.out.println(new Order(\"Bob\", 3));\n System.out.println(new Order(\"Carol\", 5, 149.95));\n }\n}\n```\n\n\nThe `this(...)` call inside a constructor invokes another constructor in the same class. It's the constructor equivalent of the delegation pattern shown with `addItem`. This is the conventional way to provide multiple ways to build the same object without duplicating field assignments.\n\n---\n\n# When Not to Overload\n\nOverloading reads cleanly when the methods do the same conceptual thing. It reads badly when the methods do different things and happen to share a name.\n\nConsider `process(Order order)` charging the customer and `process(Refund refund)` crediting the customer. Both are \"processing\", but a reader scanning the call site sees only `process(...)` and has to chase the parameter type to figure out which action is happening. Two different actions deserve two different names: `chargeOrder(order)` and `issueRefund(refund)`. The call site becomes self-documenting.\n\nA useful test: if a single sentence describing \"what `methodName` does\" fits every overload without weasel words like \"it depends\" or \"or\" in the middle, overloading fits. If not, give them different names.\n\nTwo other situations where overloading is the wrong tool:\n\n- **Overloads that take the same arguments but mean different things based on context.** If a caller could plausibly call the wrong overload by accident, the design is fragile. Be especially careful with overloads that differ only by `int` vs `double` or `int` vs `Integer`, because tiny changes in how a number is written can silently flip which overload runs.\n- **Overloads with very different numeric meanings.** `setRating(int stars)` and `setRating(double percent)` look like one method but mean completely different things. `setStarRating(int)` and `setPercentRating(double)` make the intent obvious and remove the chance of a numeric literal picking the wrong overload.","pageType":"java"}

Method Overloading

Get Premium