3.6 Methods: Passing and Returning References of an Object

1. Passing an object: the reference is copied

Java passes arguments by value (the AP® term is call by value): the parameter is initialized with a copy of the value stored in the argument. For an object, the variable stores a reference, so the parameter gets a copy of that reference. It does not create a new, independent copy of the object 3.6.A.1. The parameter and the argument now refer to the same object. Two references to one object are called aliases.

If the object is mutable, the method can use its reference to change the object’s state 3.6.A.1.

This class is used on the whole page:

public class BankAccount
{
    private String owner;
    private int balance;

    public BankAccount(String name, int start)
    {
        owner = name;
        balance = start;
    }

    public String getOwner()
    {
        return owner;
    }

    public int getBalance()
    {
        return balance;
    }

    public void deposit(int amount)
    {
        balance += amount;
    }

    /** Returns true if this account has a larger balance than other */
    public boolean hasMoreThan(BankAccount other)
    {
        return balance > other.balance;
    }

    /** Moves amount from this account to other */
    public void transferTo(BankAccount other, int amount)
    {
        balance -= amount;
        other.balance += amount;
    }

    public String toString()
    {
        return owner + ": " + balance;
    }
}

A method in another class receives an account and adds 10 percent interest:

public class Bank
{
    public static void addInterest(BankAccount acct)
    {
        acct.deposit(acct.getBalance() / 10);
    }
}

BankAccount mine = new BankAccount("Rosa", 200);
Bank.addInterest(mine);
System.out.println(mine);

Output:

Rosa: 220

During the call, memory looks like this:

mine (caller)    [ ref ] ---+
                            +---> BankAccount object: owner "Rosa", balance 200 -> 220
acct (parameter) [ ref ] ---+

Only one BankAccount object exists (println shows it through its toString method; writing toString is background, not tested on the AP® exam). acct.deposit(...) changed it, and mine sees the change.

2. Reassigning the parameter does not change the caller

Because the reference was copied, giving the parameter a new object only changes the method’s copy. The caller’s variable still refers to the original object.

public class Bank
{
    public static void replace(BankAccount acct)
    {
        acct = new BankAccount("Temp", 0);
        acct.deposit(5);
    }
}

BankAccount mine = new BankAccount("Rosa", 200);
Bank.replace(mine);
System.out.println(mine);

Output:

Rosa: 200

mine (caller)    [ ref ] ---> BankAccount: owner "Rosa", balance 200   (untouched)
acct (parameter) [ ref ] ---> BankAccount: owner "Temp", balance 5     (gone after the call)

Inside the method	Does the caller see a change?
acct.deposit(5); (call a mutator through the parameter)	Yes: same object
acct = new BankAccount("Temp", 0); (reassign the parameter)	No: only the copy of the reference moved

Watch out: a String parameter is a reference too, but String objects are immutable. No method can change the caller’s string; methods like substring return a new string instead.

3. Do not change parameters unless the specification says so

It is good programming practice not to modify mutable objects that are passed as parameters, unless the specification requires it 3.6.A.1. The caller does not expect a method that only “calculates” something to change their object.

This method counts how many monthly deposits it takes to reach a goal. The first version is wrong: it deposits into the caller’s real account while it counts.

public class Planner
{
    // BAD: changes the account it was given
    public static int monthsToGoal(BankAccount acct, int goal, int monthly)
    {
        int months = 0;
        while (acct.getBalance() < goal)
        {
            acct.deposit(monthly);
            months++;
        }
        return months;
    }
}

BankAccount savings = new BankAccount("Rosa", 100);
System.out.println(Planner.monthsToGoal(savings, 250, 50));
System.out.println(savings);

Output:

3
Rosa: 250

The good version copies the balance into a local int and leaves the object alone:

public class Planner
{
    // GOOD: reads the account but does not change it
    public static int monthsToGoal(BankAccount acct, int goal, int monthly)
    {
        int balance = acct.getBalance();
        int months = 0;
        while (balance < goal)
        {
            balance += monthly;
            months++;
        }
        return months;
    }
}

BankAccount savings = new BankAccount("Rosa", 100);
System.out.println(Planner.monthsToGoal(savings, 250, 50));
System.out.println(savings);

Output:

3
Rosa: 100

4. Returning a reference

When the return expression evaluates to an object reference, the reference is returned, not a reference to a new copy of the object 3.6.A.2. The caller then holds an alias to the object stored inside the class.

public class Club
{
    private String name;
    private BankAccount treasury;

    public Club(String clubName, int startMoney)
    {
        name = clubName;
        treasury = new BankAccount(clubName, startMoney);
    }

    /** Returns the club's own account (an alias) */
    public BankAccount getTreasury()
    {
        return treasury;
    }

    /** Returns a new account with the same values (a copy) */
    public BankAccount getTreasuryCopy()
    {
        return new BankAccount(treasury.getOwner(), treasury.getBalance());
    }

    public int funds()
    {
        return treasury.getBalance();
    }
}

Club chess = new Club("Chess", 500);
BankAccount a = chess.getTreasury();
a.deposit(100);
System.out.println(chess.funds());
BankAccount b = chess.getTreasuryCopy();
b.deposit(1000);
System.out.println(chess.funds());

Output:

600
600

a refers to the club’s real account, so the deposit through a changed the club. b refers to a new object, so the deposit through b did not.

5. Private access through a parameter of the same class

Methods cannot access the private data and private methods of a parameter that refers to an object, unless the parameter is the same type as the method’s enclosing class 3.6.A.3.

That is why hasMoreThan and transferTo in BankAccount can use other.balance directly: other is a BankAccount, and the code is inside BankAccount.

BankAccount x = new BankAccount("Rosa", 300);
BankAccount y = new BankAccount("Theo", 120);
x.transferTo(y, 50);
System.out.println(x + ", " + y);
System.out.println(x.hasMoreThan(y));

Output:

Rosa: 250, Theo: 170
true

The same expression in a different class does not compile:

public class Auditor
{
    public static boolean isNegative(BankAccount acct)
    {
        return acct.balance < 0;
    }
}

Compiler says:

error: balance has private access in BankAccount

The fix is to use the public accessor: return acct.getBalance() < 0;.

Watch out: transferTo changes its parameter other on purpose. That is fine because moving money into the other account is exactly what the method’s specification says it does 3.6.A.1.