Practical Java Praxis 64: Use clone for Immutable Objects When Passing or Receiving Object References to Mutable Objects

Like this article? We recommend 

When an immutable class is implemented, mutable objects passed to or returned from an immutable object must be properly cloned. The first article in this series defined an object as immutable when it and any object it refers to do not change. If cloning is not done, then the immutability of your object is not guaranteed. Other code can retain a reference to an object in the immutable object and make changes to it, thereby breaking immutability constraints.

Consider the following class declarations: a DiskDriveInfo class and a User class. The DiskDriveInfo is intended to be immutable. The User encapsulates which user has shared access to the disk drive. The User object with shared access is stored as part of the DiskDriveInfo object. In the following example, the designer of the class was careful to make the class final and all fields private, and to provide only getter methods. Is the DiskDriveInfo class immutable? If not, what needs to be done to make it so?

class User
{
  private String userName;
  private String userID;
  private int userNode;

  User(String name, int node)
  {
    userName = name;
    userNode = node;
  }
  public void setUserName(String name)
  {
    userName = name;
  }
  public void setUserID(String userid)
  {
    userID = userid;
  }
  public void setUserNode(int node)
  {
    userNode = node;
  }
  public String userName()
  {
    return userName;
  }
}

final class DiskDriveInfo
{
  private int driveSize;
  private String volumeLabel;
  private User driveShare;

  DiskDriveInfo(int size, String volLabel, User share)
  {
    driveSize = size;
    volumeLabel = volLabel;
    driveShare = share;
  }
  public int size()
  {
    return driveSize;
  }
  public String label()
  {
    return volumeLabel;
  }
  public User share()
  {
    return driveShare;
  }
}

The DiskDriveInfo class is not immutable. Objects of this class can be changed. Consider the following code that creates a DiskDriveInfo object and tests its immutability:

class Test
{
  private static final int sizeInMeg = 200;
  public static void main(String args[])
  {
    User share1 = new User("Duke", 10);                       //1
    DiskDriveInfo dd = new DiskDriveInfo(sizeInMeg, "myDrive",
                                         share1);             //2
    User share = dd.share();
    System.out.println("User with shared access is " +
                       share.userName());

    share1.setUserName("Fred");                               //3
    System.out.println("User with shared access is " +
                       share.userName());
  }
}

The output of this code is as follows:

User with shared access is Duke
User with shared access is Fred

What went wrong? This code creates a User object, share1, at //1, with the user name Duke. A supposedly immutable DiskDriveInfo object is created at //2 and is passed a reference to the User object. The DiskDriveInfo object is queried, and the shared owner, Duke, is printed. The User object, share1, changes its name to Fred at //3. When the DiskDriveInfo object is queried again for the user name, it discovers that the name changed from Duke to Fred.

The problem is that the DiskDriveInfo constructor receives a reference to the User object and does not make a copy, or clone, of this object. Therefore, the DiskDriveInfo constructor receives a copy of the reference to the User object. Now the DiskDriveInfo object's driveShare field and the local variable, share1, in main of class Test, reference the same object. Therefore, any changes made through either reference affect the same object. Figure 1 shows the object layout after the code at //1 is executed.

Figure 1

Object layout after execution of //1

After the code at //2 is executed, the object layout looks as shown in Figure 2.

Figure 2

Object layout after execution of //2

Notice that because the reference to the User object is not cloned, both the share1 and driveShare references share the same User object. After the code at //3 is executed, the object layout as shown in Figure 3.

Figure 3

Object layout after execution of //3

Shallow Cloning

To correct this problem, you can use a technique called shallow cloning. A shallow clone is a bitwise copy of an object. If the object being cloned contains object references, then the new object contains exact copies of the object references from the cloned object. Therefore, the new object and the cloned object still share data.

The DiskDriveInfo class must clone any mutable object to which it receives a reference. It then has a reference to its own copy of the object that cannot be changed by other code.

The modified DiskDriveInfo class that supports cloning looks like this:

final class DiskDriveInfo
{
  //As before...
  DiskDriveInfo(int size, String volLabel, User share)
  {
    driveSize = size;
    volumeLabel = volLabel;
    driveShare = (User)share.clone();
  }
  public User share()
  {
    return (User)driveShare.clone();
  }
}

Because you are cloning the User object, its definition must change as well. If you cannot change the User class to add the clone behavior, you must resort to other means. One solution is to modify the DiskDriveInfo class so that it does not use the User object. Instead, the DiskDriveInfo class can store the String that represents the user name and the int that represents the user node.

Assuming that you have access to the User object, you must modify it to support cloning. To support a default shallow clone, you need only to implement the Cloneable interface and to provide a clone method. (For more on cloning and why super.clone is called, see the fourth article in this series.) The modified User class looks like this:

class User implements Cloneable
{
  //As before...
  public Object clone()
  {
    try {
      return super.clone();
    }
    catch (CloneNotSupportedException e) {
      //This should not happen, since this class is Cloneable.
      throw new InternalError();
    }
  }
}

With these changes to the User object, running the previous test code produces the correct output:

User share1 = new User("Duke", 10);
DiskDriveInfo dd = new DiskDriveInfo(sizeInMeg, "myDrive",
                                     share1);
User share = dd.share();
System.out.println("User with shared access is " +
                   share.userName());

share1.setUserName("Fred");                                   //1
System.out.println("User with shared access is " +
                   share.userName());

This code produces the following lines:

User with shared access is Duke
User with shared access is Duke

Because the User object is cloned on the constructor call, the code that subsequently changes the User object at //1 has no effect on the DiskDriveInfo object. The implementation of the immutable DiskDriveInfo class is now correct. The object layout looks as shown in Figure 4.

Figure 4

Correct object layout after cloning

Returning a reference to a mutable object that is referred to in an immutable object presents the same problem. That is, code could gain access to your internal data and change it. Thus, you must clone any mutable objects for which a reference is returned.

For example, a reference to the User object driveShare is returned by the share method of the DiskDriveInfo class. The driveShare object needs to be cloned before it is returned from this method. It is not enough only to define a class without setter methods. You must be careful about how you receive and return object references.

You might wonder about the String and int parameters. They do not need to be cloned. Because the String class as well as all primitives are immutable, they cannot be changed by other code. Therefore, they do not present a problem.

Vector and Cloning

What happens if the implementation of the DiskDriveInfo class is changed to store a Vector of User objects that have shared access to the drive? Recall that the current implementation supports only one User object that has shared access. The DiskDriveInfo class now looks like this:

final class DiskDriveInfo
{
  //As before...
  private Vector driveShare;

  DiskDriveInfo(int size, String volLabel, Vector share)
  {
    //As before...
    driveShare = (Vector)share.clone();
  }
  //As before...
  public Vector share()
  {
    return (Vector)driveShare.clone();
  }
}

The test program is then modified to support the Vector. When this program is run, the results might be surprising. The modified test program looks like this:

import java.util.*;
class Test
{
  private static final int sizeInMeg = 200;
  public static void main(String args[])
  {
    User share1 = new User("Duke", 10);
    User share2 = new User("Duke2", 11);
    Vector shareVec = new Vector(2);
    shareVec.add(share1);  //Store 2 shared users in the vector.
    shareVec.add(share2);
    DiskDriveInfo dd = new DiskDriveInfo(sizeInMeg, "myDrive",
                                         shareVec);           //1



    Vector share = dd.share();
    System.out.println("Users with shared access are " +
                  ((User)(share.get(0))).userName() + ", " +
                  ((User)(share.get(1))).userName());

    share1.setUserName("Fred");
    System.out.println("Users with shared access are " +
                  ((User)(share.get(0))).userName() + ", " +
                  ((User)(share.get(1))).userName());
  }
}

This code produces the following output:

Users with shared access are Duke, Duke2
Users with shared access are Fred, Duke2

This is not the expected result. What happened? The only change made to this DiskDriveInfo class was to add a Vector to store multiple User objects that have shared access.

The problem is in the cloning of the Vector of User objects. By default, the clone method of the Vector class performs a shallow clone. The fields of a Vector are object references. Thus, in the previous code, when the Vector is cloned, a new copy of it is made. However, the contents of the Vector, which are object references, are not cloned. Figure 5 shows the object layout after the code at //1 is executed.

Figure 5

Object layout after a shallow clone

Deep Cloning

Because the default implementation of the clone method of the Vector class is a shallow clone, you must provide your own deep clone code. A deep clone ensures that the elementData field of the Vector in the DiskDriveInfo object references its own copies of the User objects instead of the User objects referenced by the shareVec variable. This ensures that the DiskDriveInfo object remains immutable.

One way to solve this problem is to subclass Vector, override its clone method, and provide your own implementation that performs a deep clone. The following code shows the deep clone implementation of the clone method of the subclassed Vector:

class ShareVector extends Vector
{
  ShareVector(int size)
  {
    super(size);
  }

  public Object clone()
  {
    ShareVector v = (ShareVector)super.clone();
    int size = size();                      //Create a new Vector.
    for (int i=0; i<size; i++)              //Replace each element
    {                                       //in the Vector with a
      User u = (User)(this.get(i));         //clone of that
      v.setElementAt((User)(u.clone()), i); //element.
    }
    return v;
  }
}

Notice that this code clones each object referenced by each element in the Vector. Changing the DiskDriveInfo class and the test code to use the ShareVector implementation produces the correct results. After the deep clone is performed, the object's representation looks as shown in Figure 6.

Figure 6

Object layout after a deep clone

Now, changes made through the shareVec object reference will not affect the immutable DiskDriveInfo object.

This solution produces the desired results, but it has a few drawbacks. It requires the definition of a new class that is useful only to change the clone behavior of an existing class. In addition, it requires code that uses the DiskDriveInfo class to change. This code must now use the new ShareVector class instead of the Vector class.

An alternative solution is for the DiskDriveInfo class to individually clone the User objects itself. This is done in a private method to eliminate any code duplication. The modified DiskDriveInfo class looks like this:

final class DiskDriveInfo
{
  private int driveSize;
  private String volumeLabel;
  private Vector driveShare;

  DiskDriveInfo(int size, String volLabel, Vector share)
  {
    driveSize = size;
    volumeLabel = volLabel;
    driveShare = cloneVector(share);
  }
  public int size()
  {
    return driveSize;
  }
  public String label()
  {
    return volumeLabel;
  }
  public Vector share()
  {
    return cloneVector(driveShare);
  }
  private Vector cloneVector(Vector v)
  {
    int size = v.size();
    Vector newVector = new Vector(size);      //Create new Vector.
    for (int i=0; i<size; i++)                //For each element
      newVector.add(((User)v.get(i)).clone());//in the old Vector,
    return newVector;                         //add its clone to
  }                                           //the new Vector.
}

This solution produces the desired results. It also has the added benefit that the code that uses the DiskDriveInfo class does not have to change.

In summary, follow these rules when implementing an immutable class:

• Declare the class final.

• Declare all data private.

• Provide only getter methods and no setter methods.

• Set all instance data in the constructor.

• Clone mutable objects for which a reference to them is returned.

• Clone mutable objects for which a reference to them is received.

• Implement a deep clone if the default shallow clone is not correct for a properly behaved immutable object. For more on cloning, see the fourth article in this series.