Method Overloading in Java Explained — How, Why and When to Use It

package io.thecodeforge.shipping;

public class ShippingCostCalculator {

    // Version 1: Calculate cost using just the weight in kilograms
    // Java picks this when you pass a single double argument
    public static double calculateCost(double weightKg) {
        double baseRate = 2.50; // flat rate per kg
        return weightKg * baseRate;
    }

    // Version 2: Calculate cost using weight AND distance in km
    // Java picks this when you pass two double arguments
    public static double calculateCost(double weightKg, double distanceKm) {
        double baseRate    = 2.50;
        double distanceRate = 0.10; // extra cost per km
        return (weightKg * baseRate) + (distanceKm * distanceRate);
    }

    // Version 3: Calculate cost for a named service tier
    // Java picks this when you pass a double and a String
    public static double calculateCost(double weightKg, String serviceType) {
        double baseCost = calculateCost(weightKg); // reuse Version 1
        if ("express".equals(serviceType)) {
            return baseCost + 15.00; // express surcharge
        }
        return baseCost;
    }

    public static void main(String[] args) {
        // The compiler matches each call to the right version at compile time
        double standardCost = calculateCost(3.5);               // → Version 1
        double distanceCost = calculateCost(3.5, 120.0);        // → Version 2
        double expressCost  = calculateCost(3.5, "express");    // → Version 3

        System.out.println("Standard shipping (3.5 kg):          $" + standardCost);
        System.out.println("Distance shipping (3.5 kg, 120 km):  $" + distanceCost);
        System.out.println("Express shipping (3.5 kg):           $" + expressCost);
    }
}

package io.thecodeforge.thermodynamics;

public class TemperatureConverter {

    // Accepts an int temperature — exact match for int arguments
    public static void displayTemperature(int tempCelsius) {
        System.out.println("[int version]    " + tempCelsius + "°C = "
                + (tempCelsius * 9 / 5 + 32) + "°F");
    }

    // Accepts a double temperature — more precise, exact match for double arguments
    public static void displayTemperature(double tempCelsius) {
        System.out.println("[double version] " + tempCelsius + "°C = "
                + (tempCelsius * 9.0 / 5.0 + 32.0) + "°F");
    }

    // Accepts a long temperature — exact match for long arguments
    public static void displayTemperature(long tempCelsius) {
        System.out.println("[long version]   " + tempCelsius + "°C  (long type)");
    }

    public static void main(String[] args) {
        int   boilingPoint = 100;    // exact int  → Java calls int version directly
        double bodyTemp    = 37.5;   // exact double → Java calls double version directly
        byte  freezingByte = 0;      // no byte overload exists
                                     // Java promotes: byte → short → int
                                     // finds the int version → calls it
        float warmDay      = 25.0f;  // no float overload exists
                                     // Java promotes: float → double
                                     // finds the double version → calls it
                                     // IMPORTANT: this is exactly how the
                                     // billing incident happened in production

        System.out.println("--- Exact matches ---");
        displayTemperature(boilingPoint);  // → int version
        displayTemperature(bodyTemp);      // → double version

        System.out.println();
        System.out.println("--- Type promotion at work ---");
        displayTemperature(freezingByte);  // byte promoted to int → int version
        displayTemperature(warmDay);       // float promoted to double → double version
    }
}

package io.thecodeforge.notification;

// ─────────────────────────────────────────────────────────────────
// OVERLOADING: Same class, same name, different parameter lists
// Resolved at compile time — the compiler picks the version
// ─────────────────────────────────────────────────────────────────
class NotificationService {

    // Send a plain text notification
    public void sendNotification(String message) {
        System.out.println("[Text]  Sending: " + message);
    }

    // Send a notification to a specific user
    // Overloaded — extra parameter makes this a different signature
    public void sendNotification(String message, String username) {
        System.out.println("[Text]  Sending to " + username + ": " + message);
    }

    // Send a notification with a priority level
    // Overloaded — different type in second position (int vs String)
    public void sendNotification(String message, int priorityLevel) {
        System.out.println("[Priority " + priorityLevel + "] Sending: " + message);
    }
}


// ─────────────────────────────────────────────────────────────────
// OVERRIDING: Child class replaces a parent class's behaviour
// Resolved at runtime — the JVM picks the version based on actual object type
// ─────────────────────────────────────────────────────────────────
class EmailNotificationService extends NotificationService {

    // @Override tells the compiler: this must match a parent method signature exactly
    // Same name, SAME parameter list — this is overriding, not overloading
    // At runtime, the JVM calls THIS version even when the reference type is NotificationService
    @Override
    public void sendNotification(String message) {
        System.out.println("[Email] Sending via email: " + message);
    }
}


public class OverloadingVsOverridingDemo {
    public static void main(String[] args) {

        System.out.println("--- Overloading: compiler picks version at compile time ---");
        NotificationService generic = new NotificationService();
        generic.sendNotification("Server is down");            // → overloaded v1
        generic.sendNotification("Server is down", "alice");  // → overloaded v2
        generic.sendNotification("Server is down", 1);        // → overloaded v3

        System.out.println();
        System.out.println("--- Overriding: JVM picks version at runtime ---");

        // The reference type is NotificationService, but the actual object is EmailNotificationService
        // The JVM resolves this at runtime via the vtable — calls the Email version
        NotificationService ref = new EmailNotificationService();
        ref.sendNotification("Server is down");           // → overridden! calls Email version
        ref.sendNotification("Server is down", "alice"); // → inherited overload v2, not overridden
    }
}