Methods: Passing and Returning References of an Object

A game app keeps a Player object for each player, with a name and a point total. A Scorekeeper object awards bonuses. Its method needs to receive a whole player, not just a number, and the bonus has to stick: after the method finishes, the player in main should have the extra points. In Topic 3.5 every parameter you wrote was a primitive, such as an int, and changing an int parameter never changed anything outside the method. So what happens when the argument is an object?

Start from two things you already know. First, from Topic 3.5: a parameter is initialized with a copy of its argument. Second, from Topic 1.13: a variable such as Player star does not hold the player object itself. It holds a reference, the address of where the object lives in memory.

Put those together and the answer follows. When the argument is a reference variable, what gets copied into the parameter is the reference, the address. The object is not copied. There is still exactly one Player object, and now two variables lead to it: the caller’s variable and the method’s parameter. In the words of Topic 2.6, the parameter becomes an alias of the caller’s object for as long as the method runs.

Think of handing a friend a slip of paper with your home address copied onto it. Your friend has their own slip, but there is still only one house. If they go there and paint the front door, you will see the new color when you come home. (The analogy stops at the slip itself: if your friend scribbles a different address on their slip, your slip is unchanged. That case is the subject of 3.6.2.)

Because the method can reach the real object, it can call that object’s mutators and change its state. An object whose state can be changed after it is created, such as a Player with an addPoints mutator, is called a mutable object. A String is not mutable, as you saw in Topic 1.15.

Most programs in this chapter use a Player class like the one in the next example: private name and points, a constructor, two accessors, and the mutator addPoints. In your own projects each class is public and goes in its own file. To keep each example runnable as a single file, the extra classes here leave off public, because Java allows only one public class per file. Once you have read Player here, you can skip it at the bottom of later examples.

public class BonusByReference
{
    public static void main(String[] args)
    {
        Player star = new Player("Ada", 10);
        Scorekeeper keeper = new Scorekeeper();
        keeper.awardBonus(star);
        System.out.println("Back in main: " + star.getPoints());
    }
}

class Scorekeeper
{
    public void awardBonus(Player p)
    {
        p.addPoints(5);
        System.out.println("Inside awardBonus: " + p.getPoints());
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

Inside awardBonus: 15
Back in main: 15

Now change one thing: pass a primitive instead of an object. This version gives awardBonus an int parameter and adds 5 to it.

public class BonusByValue
{
    public static void main(String[] args)
    {
        int adaScore = 10;
        Scorekeeper keeper = new Scorekeeper();
        keeper.awardBonus(adaScore);
        System.out.println("Back in main: " + adaScore);
    }
}

class Scorekeeper
{
    public void awardBonus(int score)
    {
        score = score + 5;
        System.out.println("Inside awardBonus: " + score);
    }
}

Inside awardBonus: 15
Back in main: 10

Line 7 copies the value 10 into score. Line 16 changes score to 15, but score is a separate box from adaScore, and there is no object behind either one. adaScore is still 10. Side by side:

In both cases Java copies what the argument variable holds. The difference is what it holds: a number in one case, an address in the other.

public class DoubleUp
{
    public static void main(String[] args)
    {
        Player grace = new Player("Grace", 4);
        Coach coach = new Coach();
        coach.doubleUp(grace);
        coach.doubleUp(grace);
        System.out.println(grace.getPoints());
    }
}

class Coach
{
    public void doubleUp(Player p)
    {
        p.addPoints(p.getPoints());
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

16

If a method can change the caller’s object, can it also make the caller’s variable refer to a different object? Suppose a reset method tries to replace a player with a brand-new rookie. Does the caller end up with the rookie?

The address slip from 3.6.1 answers it. The parameter is the method’s own slip. Following the slip to the house and painting the door changes the house everyone shares. Erasing the slip and writing a new address on it changes only that slip. The caller’s slip still has the old address.

In Java terms, there are two very different things a method can do with an object parameter:

The dot in p.addPoints means “go to the object and act on it.” An assignment p = … means “put a different address in p.” Only the first one reaches the shared object.

public class ReplaceParameter
{
    public static void main(String[] args)
    {
        Player star = new Player("Ada", 10);
        Scorekeeper keeper = new Scorekeeper();
        keeper.reset(star);
        System.out.println("Back in main: " + star.getName() + " " + star.getPoints());
    }
}

class Scorekeeper
{
    public void reset(Player p)
    {
        p = new Player("Rookie", 0);
        System.out.println("Inside reset: " + p.getName() + " " + p.getPoints());
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

Inside reset: Rookie 0
Back in main: Ada 10

The same rule explains what happens with a String parameter. A String is immutable (Topic 1.15): it has no mutators, so a method cannot change the text of the object it receives. All it can do is build a new string and store that in its parameter.

public class CheerString
{
    public static void main(String[] args)
    {
        String cheer = "Go team";
        Announcer announcer = new Announcer();
        announcer.shout(cheer);
        System.out.println("Back in main: " + cheer);
    }
}

class Announcer
{
    public void shout(String text)
    {
        text = text + "!!!";
        System.out.println("Inside shout: " + text);
    }
}

Inside shout: Go team!!!
Back in main: Go team

Line 16 builds a new String, "Go team!!!", and moves text to it. That is an assignment to the parameter, like line 16 of ReplaceParameter, so cheer in main still refers to the original "Go team". A method can change the state of a mutable object passed to it, but it can never change a String argument.

public class SwapPlayersWrong
{
    public static void main(String[] args)
    {
        Player first = new Player("Ada", 10);
        Player second = new Player("Grace", 20);
        Scorekeeper keeper = new Scorekeeper();
        keeper.swap(first, second);
        System.out.println("first: " + first.getName());
        System.out.println("second: " + second.getName());
    }
}

class Scorekeeper
{
    public void swap(Player a, Player b)
    {
        Player temp = a;
        a = b;
        b = temp;
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

first: Ada
second: Grace

public class MixedUpdate
{
    public static void main(String[] args)
    {
        Player kai = new Player("Kai", 10);
        Scorekeeper keeper = new Scorekeeper();
        keeper.update(kai);
        System.out.println(kai.getName() + " " + kai.getPoints());
    }
}

class Scorekeeper
{
    public void update(Player p)
    {
        p.addPoints(3);
        p = new Player("Temp", 100);
        p.addPoints(3);
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

Kai 13

Being able to change a caller’s object is powerful, and it is also a trap. Someone who calls a method named previewBonus expects to see a number, not to have their player’s score changed. If a method quietly changes an object passed to it, the caller has no hint from the call itself, and the bug shows up later somewhere else.

A method’s specification is the description of what it is supposed to do, often written as a comment just above its header. Callers rely on the specification instead of reading the method’s code. Recall from Topic 3.5 that accessors report information while mutators change it. The good-practice rule follows: a method or constructor should not modify a mutable object passed as a parameter unless its specification says to. If the job is to report, compute, or record something, the method should read the object through its accessors and leave it alone. If the job is to change the object, as with awardBonus, changing it is exactly right.

A changed parameter object that the caller did not ask for is called a side effect. It is legal Java, so the compiler never complains. Only careful reading of the specification catches it.

public class PreviewChanges
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 10);
        Scorekeeper keeper = new Scorekeeper();
        System.out.println(keeper.previewBonus(ada, 5));
        System.out.println(keeper.previewBonus(ada, 5));
        System.out.println(ada.getPoints());
    }
}

class Scorekeeper
{
    // Returns what p's total would be if p earned bonus more points.
    public int previewBonus(Player p, int bonus)
    {
        p.addPoints(bonus);
        return p.getPoints();
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

15
20
20

return p.getPoints() + bonus;

Constructors follow the same rule, because a constructor’s parameters are initialized the same way. This Team constructor is specified only to record the captain’s name, but line 19 also changes the Player it was given:

public class WelcomeBonus
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 10);
        Team robots = new Team(ada);
        System.out.println(robots.getCaptainName() + " has " + ada.getPoints());
    }
}

class Team
{
    private String captainName;

    // Records the name of the team's captain.
    public Team(Player captain)
    {
        captainName = captain.getName();
        captain.addPoints(10);
    }

    public String getCaptainName()
    {
        return captainName;
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

Ada has 20

Line 6 passes ada’s reference to the constructor, so captain and ada refer to the same object. Line 18 reads the name with an accessor, which is fine. Line 19 calls a mutator on the shared object, so Ada’s points jump from 10 to 20 just because a team was created. Deleting line 19 makes the constructor match its specification, and the program would print Ada has 10.

public class CombinedBug
{
    public static void main(String[] args)
    {
        Player lee = new Player("Lee", 8);
        Player mia = new Player("Mia", 6);
        Scorekeeper keeper = new Scorekeeper();
        System.out.println(keeper.combinedPoints(lee, mia));
        System.out.println(lee.getPoints());
    }
}

class Scorekeeper
{
    // Returns the total points of players a and b.
    public int combinedPoints(Player a, Player b)
    {
        a.addPoints(b.getPoints());
        return a.getPoints();
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

return a.getPoints() + b.getPoints();

Sometimes a method’s answer is an object: “which of these two players is ahead?” In Topic 3.5, a non-void method evaluated its return expression and handed back a copy of the value, so returning an int gave the caller a number of its own. What does the caller get when the return type is a class, such as Player?

The same thing happens as with parameters. The return expression evaluates to a reference, and that reference is what gets copied back to the caller. The object itself is not copied. If the method returns a reference to an object that already exists, the caller’s variable becomes another alias of that object.

public class LeaderReturn
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 12);
        Player grace = new Player("Grace", 9);
        Scorekeeper keeper = new Scorekeeper();
        Player top = keeper.leader(ada, grace);
        top.addPoints(1);
        System.out.println(top.getName() + " " + top.getPoints());
        System.out.println(ada.getName() + " " + ada.getPoints());
        System.out.println(top == ada);
    }
}

class Scorekeeper
{
    // Returns whichever player has more points (a if they are tied).
    public Player leader(Player a, Player b)
    {
        if (b.getPoints() > a.getPoints())
        {
            return b;
        }
        return a;
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

Ada 13
Ada 13
true

Now vary it: the method returns an instance variable instead of a parameter. This Team builds its own private Player in its constructor, and getCaptain returns it.

public class CaptainLeak
{
    public static void main(String[] args)
    {
        Team robots = new Team("Ada");
        Player c = robots.getCaptain();
        c.addPoints(50);
        System.out.println("Team says: " + robots.getCaptainPoints());
    }
}

class Team
{
    private Player captain;

    public Team(String captainName)
    {
        captain = new Player(captainName, 0);
    }

    public Player getCaptain()
    {
        return captain;
    }

    public int getCaptainPoints()
    {
        return captain.getPoints();
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

Team says: 50

Line 23 returns the reference stored in the private instance variable captain. Line 6 stores that reference in c, so c and the team’s captain are aliases. Line 7 adds 50 points through c, and the team’s own captain object changes, even though Team has no method for changing its captain’s points. Making captain private kept other classes from writing robots.captain, but it did not protect the object once a reference to it was handed out.

If the class designer does not want outside code to change the team’s captain, getCaptain can build and return a new object with the same data:

return new Player(captain.getName(), captain.getPoints());

With that line as the body of getCaptain, line 7 changes only the copy, and the program prints Team says: 0. This is the return-side partner of the Topic 3.4 advice to store a copy of a mutable object that a constructor receives.

public class LeaderTie
{
    public static void main(String[] args)
    {
        Player lee = new Player("Lee", 7);
        Player mia = new Player("Mia", 7);
        Scorekeeper keeper = new Scorekeeper();
        Player top = keeper.leader(lee, mia);
        top.addPoints(2);
        Player next = keeper.leader(mia, lee);
        next.addPoints(1);
        System.out.println(lee.getPoints() + " " + mia.getPoints());
        System.out.println(top == next);
    }
}

class Scorekeeper
{
    // Returns whichever player has more points (a if they are tied).
    public Player leader(Player a, Player b)
    {
        if (b.getPoints() > a.getPoints())
        {
            return b;
        }
        return a;
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

10 7
true

Suppose Player needs a method that answers “is this player ahead of that one?” The method receives another Player as a parameter. Inside Player, can it read other.points directly, or must it call other.getPoints()? And what about a Scorekeeper method that receives a Player?

From Topic 3.3, private restricts access to the declaring class. The key word is class, not object. Code written inside the Player class may use the private instance variables and private methods of any Player object it has a reference to, not only the object it was called on. Code in any other class may not, even when it holds a perfectly good reference to a Player.

Why draw the line at the class? private exists to hide how a class works from code written outside it (encapsulation). Code inside Player is already part of that hidden design: whoever writes Player knows what points means and keeps it correct for every Player object. Code in Scorekeeper is outside, so it must go through the public methods.

public class AheadOf
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 12);
        Player grace = new Player("Grace", 9);
        System.out.println(ada.isAheadOf(grace));
        System.out.println(grace.isAheadOf(ada));
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public boolean isAheadOf(Player other)
    {
        return points > other.points;
    }
}

true
false

The rule covers private methods too. Here hasScored is private, and bothScored, also inside Player, calls it on itself and on the parameter:

public class BothScored
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 12);
        Player kai = new Player("Kai", 0);
        System.out.println(ada.bothScored(kai));
        System.out.println(ada.bothScored(ada));
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public boolean bothScored(Player other)
    {
        return hasScored() && other.hasScored();
    }

    private boolean hasScored()
    {
        return points > 0;
    }
}

false
true

Line 7: Ada has 12 points but Kai has 0, so other.hasScored() is false and the result is false. Line 8 passes ada as the argument to her own method, so both calls check the same object, and the result is true.

public class PrivateFromOutside
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 12);
        Scorekeeper keeper = new Scorekeeper();
        System.out.println(keeper.pointsOf(ada));
    }
}

class Scorekeeper
{
    public int pointsOf(Player p)
    {
        return p.points;
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public int getPoints()
    {
        return points;
    }
}

PrivateFromOutside.java:15: error: points has private access in Player

public class SameScoreAccess
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 12);
        Player kai = new Player("Kai", 12);
        Coach coach = new Coach();
        System.out.println(ada.sameScore(kai));
        System.out.println(coach.sameName(ada, kai));
    }
}

class Coach
{
    public boolean sameName(Player p, Player q)
    {
        return p.name.equals(q.name);
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public boolean sameScore(Player other)
    {
        return points == other.points;
    }
}

This program uses every idea in the chapter. trade changes both of its parameters (its specification says to) and returns a reference. resetToZero tries to replace its parameter. isAheadOf reads a parameter’s private data from inside Player.

public class TradeDay
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 20);
        Player grace = new Player("Grace", 12);
        Scorekeeper keeper = new Scorekeeper();
        Player leader = keeper.trade(ada, grace, 5);
        leader.addPoints(2);
        keeper.resetToZero(ada);
        System.out.println("Ada: " + ada.getPoints());
        System.out.println("Grace: " + grace.getPoints());
        System.out.println(leader == grace);
        System.out.println(grace.isAheadOf(ada));
    }
}

class Scorekeeper
{
    // Moves amount points from giver to receiver.
    // Returns whichever player is ahead afterward (giver if tied).
    public Player trade(Player giver, Player receiver, int amount)
    {
        giver.addPoints(-amount);
        receiver.addPoints(amount);
        if (receiver.getPoints() > giver.getPoints())
        {
            return receiver;
        }
        return giver;
    }

    // Meant to set p's points to 0 (it does not work).
    public void resetToZero(Player p)
    {
        p = new Player(p.getName(), 0);
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }

    public boolean isAheadOf(Player other)
    {
        return points > other.points;
    }
}

Ada’s object is at address A and Grace’s at address B.

Ada: 15
Grace: 19
true
true

Notice the two methods that receive Ada. trade used a mutator through its parameter, and the change stuck. resetToZero assigned to its parameter, and nothing changed for the caller. To actually reset a player, Player would need a mutator that sets points to 0, and resetToZero would call it.

• When the argument is an object, the parameter gets a copy of the reference. No new object is made, so the parameter and the caller’s variable refer to the same object.
• Calling a mutator through the parameter changes the shared object, and the caller sees the change. Assigning a new reference to the parameter changes only the parameter, and the caller sees nothing. A String argument can never be changed, because strings are immutable.
• A method or constructor should not change a mutable object it receives unless its specification calls for that change; otherwise it should only read the object with accessors.
• Returning an object returns a reference to it, not a copy. Returning a private instance variable’s reference lets outside code change that object; returning a new object built with new prevents this.
• Code may use the private variables and private methods of a parameter only when the parameter’s type is the class the code is written in.

public class StoredReference
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 10);
        Team robots = new Team(ada);
        ada.addPoints(5);
        System.out.println(robots.getCaptainPoints());
    }
}

class Team
{
    private Player captain;

    public Team(Player firstCaptain)
    {
        captain = firstCaptain;
    }

    public int getCaptainPoints()
    {
        return captain.getPoints();
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

public class PickTrace
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 5);
        Player bo = new Player("Bo", 5);
        Scorekeeper keeper = new Scorekeeper();
        Player result = keeper.pick(ada, bo);
        result.addPoints(100);
        System.out.println(ada.getPoints());
        System.out.println(bo.getPoints());
        System.out.println(result == bo);
    }
}

class Scorekeeper
{
    public Player pick(Player p, Player q)
    {
        p.addPoints(1);
        p = q;
        p.addPoints(10);
        return p;
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

6
115
true

public class ShopRefund
{
    public static void main(String[] args)
    {
        Wallet mine = new Wallet(20);
        Shop shop = new Shop();
        shop.refund(mine, 5);
        System.out.println(mine.getDollars());
    }
}

class Shop
{
    // Gives amount dollars back to the customer's wallet.
    public void refund(Wallet w, int amount)
    {
        w.dollars = w.dollars + amount;
    }
}

class Wallet
{
    private int dollars;

    public Wallet(int startDollars)
    {
        dollars = startDollars;
    }

    public int getDollars()
    {
        return dollars;
    }

    public void addDollars(int amount)
    {
        dollars = dollars + amount;
    }
}

w.addDollars(amount);

public class FakeCopy
{
    public static void main(String[] args)
    {
        Player ada = new Player("Ada", 10);
        Scorekeeper keeper = new Scorekeeper();
        Player backup = keeper.makeCopy(ada);
        backup.addPoints(5);
        System.out.println(ada.getPoints());
    }
}

class Scorekeeper
{
    public Player makeCopy(Player p)
    {
        Player result = p;
        return result;
    }
}

class Player
{
    private String name;
    private int points;

    public Player(String playerName, int startPoints)
    {
        name = playerName;
        points = startPoints;
    }

    public String getName()
    {
        return name;
    }

    public int getPoints()
    {
        return points;
    }

    public void addPoints(int amount)
    {
        points = points + amount;
    }
}

• I can explain what a parameter holds when the argument is an object, and why no new object is made. Reread
• I can predict whether a change made inside a method shows up for the caller. Reread
• I can spot a method or constructor that changes a parameter object its specification does not mention. Reread
• I can trace a method that returns an object and explain why the caller gets the same object, not a copy. Reread
• I can decide whether a method may use the private data of an object passed to it. Reread