Effective JavaEffective cloning

• By Steve Ball
• January 18, 2000

Unfortunately, the magic that wrought clone and Cloneable into existence was spelled imperfectly and the method and interface it created have numerous defects.Ý

I'll show you how the clone method is implemented within the Java virtual machine (JVM) and highlight its special relationship with the Cloneable interface. I'll also draw your attention to the problems that typically arise when attempting to make effective use of the cloning services and how these difficulties may be overcome when writing your own clone methods.

Maxim 18: Clone Objects Passed Between Classes to Protect Encapsulation
It is Java's shallow copy semantics that make cloning-the process of instantiating a new object that is a duplicate of another-of such importance in Java. When an object is passed as a method argument, both the called and the calling methods share references to the same actual instance.1

class GraphPoint {
  GraphPoint(Point c, int t) {
    center = c;
    type = t;
  }

  static final int CROSSHAIR = 0;
  static final int DIAMOND = 1;

  private Point center;
  private int type;
}

void plot_line(GraphPoint[] line, int m, int c) {
  Point next = new Point(0, c);

  while (next.x < line.length)="" {="" line[next.x]="new" graphpoint(="" next,="" graphpoint.crosshair);="" next.x="" +="1;" next.y="" +="m;" }="">

For some classes, it is meaningful for an object to remain associated with the specific instances it had passed to its constructors; where it is not, either the caller is required to pass only distinct instances as arguments:

line[next.x] = new GraphPoint(new Point(
	next), GraphPoint.CROSSHAIR);

GraphPoint(Point c, int r) {
  center = new Point(c);
  radius = r;
}

void setCenter(Point c) {
  center = new Point(c);
}

Maxim 19: Prefer the clone Method To Other Interfaces for Providing Cloning Support
The Point class is one of a small number of classes in the Java API that provides cloning support in the form of a constructor that takes a single argument of its own type (String and java.awt.Rectangle are two others). The disadvantage of this approach, compared to the clone method, is that it may not be accessed polymorphically and is usually less efficient. Some classes, such as java.util.Date, require even weirder syntax to clone their instances:

Date clone = new Date(birthdate.getTime());

line[next.x] = new GraphPoint((
	Point) next.clone(), GraphPoint.CROSSHAIR);

public class BankAccount {
  public Currency getBalance() {
    return balance;
  }

  public boolean deposit(Currency amount) {
    //...
  }

  private Currency balance;
}

BankAccount sxb = bank.getAccount("Steve Ball");
sxb.getBalance().setValue(1e9, "USD");

public Currency getBalance() {
  return (Currency) balance.clone();
}

With simple classes such as these, the need for cloning is readily apparent, but not all occurrences of this type of entanglement are as easy to identify; inexplicable bugs in far-off parts of the program are more often the symptom that necessary cloning was overlooked. Furthermore, providing deep copy cloning for container classes is predicated on the elements of the container providing cloning support themselves, via the clone method.

The clone method, then, is an important part of a class's interface to the rest of the system. Fortunately, much of the work required to write a fully-functioning clone method has already been supplied in the form of the Object.clone method. Adding cloning support to a class merely involves overriding and augmenting this method.

One Size Fits All
The clone method of the Object class is necessarily declared as a native method, its implementation residing within the JVM:

protected native Object clone() throws 
	CloneNotSupportedException;

If this object implements the Cloneable interface
  Construct a new object of the same runtime type.
  Copy the in-memory image of this object into the new one.
else, if this object is an array
  Construct a new array of the same type and size.
  Copy the in-memory image of this array into the new one.
else
  Construct and throw a new CloneNotSupportedException object.

public interface Cloneable {
}

But why would you want to prevent a class's objects from being cloned? After all, it sounds like a useful ability. The answer is that the default operation of the Object.clone method may produce too shallow a copy for some classes.|| Such classes need special handling to make a more distinct separation between the original and cloned objects for the cloning operation to produce valid clones. Once this special handling has been implemented, cloning may be safely enabled by implementation of the Cloneable interface.

Booby Trapped Clones
This scenario can be demonstrated with a simple (non-clonable) stack class.

public class Stack {
  public Stack() { this(32); }

  public Stack(int sz) {
    data = new Object[maxSize = sz];
  }

  public void push(Object o) {
    if (size < maxsize)="" data[size++]="o;" }="">

  public Object pop() {
    return size == 0 ? null : data[-size];
  }

  private int maxSize, size = 0;
  private Object[] data;
}

public class Stack implements Cloneable {

public Object clone() {
  try {
    return super.clone();
  } catch (CloneNotSupportedException e) {
    throw new InternalError(e.toString());
  }
}

If this method is adding nothing to the functionality of the method it inherited from its superclass, why bother to override it at all? The clone method declared in the Object class has protected accessibility; to allow methods of classes other than Stack and its subclasses to clone Stack instances, the method must be promoted to public accessibility. The Stack class must also implement the Cloneable interface to enable the Object.clone method to proceed with the cloning.

Calling a stack's clone method produces a new stack identical to the first:

Stack crockery = new Stack();
crockery.push(new Cup());
Stack clone = (Stack) crockery.clone();
// both stacks contain one Cup object

// both stacks contain one Cup object
crockery.push(new Plate());
clone.push(new Saucer());
// both stacks contain one Cup and one Saucer!

In the case of the Stack class, the problem occurred because the array (data) within the Stack object was duplicated by field assignment-both stacks share the same storage for their elements (but independent counts of the number of elements within it). Pushing a Saucer object onto the cloned stack pushed the Plate object on the original off the stack and into thin air!

Maxim 20: Ensure That Your Clone Methods Perform a Deep Enough Copy
To produce more distinct cloned objects, the array instance containing the stack's elements must also be cloned. To do this, the class must augment the clone method it inherits from its superclass with some special handling for this particular instance member.

public Object clone() {
  try {
    Stack clone = (Stack) super.clone();
    clone.data = (Object[]) clone.data.clone();
    return clone;
  } catch (CloneNotSupportedException e) {
    throw new InternalError(e.toString());
  }
}

Because the array instances are now distinct, elements may be pushed and popped onto either of the two stacks without the operations affecting the other. By performing a deeper copy than the default one performed by the Object class's clone method, the clone has been given enough separation from the original to eliminate the bug:

// both stacks contain one Cup object
crockery.push(new Plate());
// one Cup and one Plate
clone.push(new Saucer());
// one Cup and one Saucer

Popping a Cup object off one stack and modifying some aspect of its appearance also modifies the Cup object still on the other stack. This may be what the designer of the Stack class intended, but often this behavior comes as an initial surprise to users of Java's container classes. The deep copy cloning of generic Object-based container classes presents some challenges because the clone method of a class-even when overridden as a public method in its runtime type-is inaccessible through an Object reference where its static type (Object) declares it as protected:

public Object clone() {
  try {
    Stack clone = (Stack) super.clone();
    clone.data = (Object[]) clone.data.clone();
    for (int i = 0; i < clone.data.length;="" ++i)="" next="" line="" will="" not="" compile="" clone.data[i]="clone.data[i].clone();" return="" clone;="" }="" catch="" (clonenotsupportedexception="" e)="" {="" throw="" new="" internalerror(e.tostring());="" }="">

The crockery-stacking example is one where a method possesses a reference to an object (the crockery stack object) and wishes to clone it. However, there is another situation where this is not the case, but nonetheless, it is imperative that classes provide suitable cloning support; even if the clone method is not publicly accessible!

Maxim 21: Remember That Subclasses Depend On a Class's Clone Method Too
Subclasses wishing to support cloning rely on their superclasses emitting valid clones from their clone methods. Consequently, classes that do not provide a publicly accessible clone method or implement the Cloneable interface must still provide a reliable implementation of clone if field-by-field assignment would be incorrect!

If defined in such a class, the clone method is provided solely for the benefit of subclasses. To prevent other classes from gaining access to the method, the overriding clone method may be declared protected. The class should still implement the Cloneable interface though, as the interface is an integral part of the implementation of the class's clone method: Without it, clone will fail.

public class Stack implements Cloneable {
  // may only be cloned by subclasses
  protected Object clone() {
    // as before...
  }
}

public class PrintQueue extends Stack {
  // may be cloned by any class
  public Object clone() {
    return super.clone();
  }
  // other methods...
}

public class GlobalConfigSettings {
  // may not be cloned at all
  final protected Object clone() throws
      CloneNotSupportedException {
    throw new CloneNotSupportedException();
  }
}

Java API Example
When designing a new class, it is easy to forget to provide a reliable clone method if you do not intend to allow the class to be directly clonable, forgetting that subclasses depend on their superclasses for cloning support too. It is also easy for this mistake to go unnoticed in testing, as the impact will not become apparent until the class is extended.

A case in point is the java.util.Observable class from the Java API. The nature of the Observable class means that it must always be extended to be of any use. However, it has no subclasses within the Java API itself, so it was not until Java developers tried cloning subclasses of Observable that its failure to provide a reliable clone method highlighted the lack of subclasses.

A class that extends Observable can declare an overridden public clone method that contains any required special handling for the fields of the subclass. However, Observable does not define a clone method itself, so the imbedded Observable object will be booby-trapped. This cannot be made to work:

public class Stack extends Observable implements Cloneable {
  // as before...

  public Object clone() {
    try {
      Stack clone = (Stack) super.clone();
      // clone already corrupt
      // as before...
    }
}

This is a problem that could easily have been avoided and is now very difficult to remedy. In a class designed to be extended, an overriding clone method is an obvious omission. Because it would hardly be useful to clone an Observable object that has not been subclassed, this problem did not present itself until the Java API was released to developers as a defined part of the language.

Maxim 22: Provide Cloning Support for Every Class
Those classes that depend on some class X supporting cloning include:

1. Any class that wants to accept an X as an argument to a constructor or mutator method and wishes to retain a private (unique) copy.
2. Any class that wants to return an X from an accessor method without allowing callers direct access to the public methods of the instance referred to by its own member field.
3. Any class which subclasses X and wishes to provide cloning support itself.

In small systems, it is often feasible to know in advance all the uses that a new class will be put to. This is rarely the case with large systems development. For large-scale development of robust systems, it makes more sense to supply cloning support when the class is initially developed.

There are so few cases where the time spent providing cloning support would not be justified, that it is easier to list the conditions where an overridden clone method is not necessary than to list the ones where it is:

1. Where a class contains no member fields that require special handling and either inherits a public clone method or inherits a protected clone method and should only be clonable by classes that extend it.
2. Where a class is final (i.e., cannot be subclassed) and has inherited a clone method with protected accessibility.

The first situation often crops up when a class is being subclassed to add a simple ability but no additional state information:

public SortableVector extends Vector implements Sortable {
  public void sort() {
    Algorithms.quicksort(elementData, elementCount);
    ++modCount;  // invalidate iterators
  }
}