Page History

Mutable classes allow code external to the class to alter their instance or class fields. Provide means for creating copies of mutable classes so that 'disposable' instances of such classes can be passed to untrusted code. This functionality is useful when methods in other classes need to create copies of the particular class instance; see guidelines FIO00-J. Defensively copy mutable inputs and mutable internal components and OBJ11-J. Defensively copy private mutable class members before returning their references for additional details.

Non-final Mutable classes should must provide either a copy constructor or a public static factory method that returns a copy of an instance. Final classes can use either of the aforementioned approaches. Alternatively, final classes may advertise their copy functionality by overriding java.lang.Object's clone() method. Use of the clone() method is secure only for final classes; non-final classes are forbidden to use this approach.

Trusted callers can be trusted to make defensive copies by use the provided copy functionality to make defensive copies before passing object instances to untrusted code. Untrusted callers cannot be trusted to make such defensive copies. Consequently, providing copy functionality is insufficient to obviate the need for making defensive copies either of inputs received from, or of outputs that are returned to untrusted code.

...

In this noncompliant code example, MutableClass uses a mutable field date of type Date. Class Date is also a mutable class. The example is not compliant because MutableClass objects provide no means of copying themselves.

public final class MutableClass {
  private Date date;
	
  public MutableClass(Date d) {
    this.date = d;
  }

  public void setDate(Date d) {
    this.date = d;
  }
	
  public Date getDate() {
    return date;	
  }
}

When a trusted caller passes an instance of MutableClass to untrusted code, and the untrusted code modifies that instance (perhaps by incrementing the month or changing the timezone), the state of the object may no longer remain consistent with its previous state. Similar problem can arise in the presence of multiple threads, even in the absence of untrusted code.

Compliant Solution (

...

Non-final Instance Members)

This compliant solution provides the needed copy functionality by declaring MutableClass to be final, and by implementing the Cloneable interface and providing an Object.clone() method that performs a deep copy of the object.

public final class MutableClass implements Cloneable {
  private Date date;
	
  public MutableClass(Date d) {
    this.date = new Date(d.getTime());  //copy-in 
  }
	
  public Date getDate() {
    return (Date)date.clone(); //copy and return
  }

  public void setDate(Date d) {
    this.date = d.clone();
  }
	
  public Object clone() throws CloneNotSupportedException {
    final MutableClass cloned = (MutableClass)super.clone();
    cloned.date = (Date)date.clone();  // manually copy mutable Date object manually
    return cloned;
  }
}

Note that the {{clone()}} method must manually clone the {{Date}} object. This step is usually unnecessary when the object contains only primitive fields or fields that refer to immutable objects. However, when the fields contain data such as unique identifiers or object creation times, the {{clone()}} method must calculate and assign appropriate new values for such fields \[[Bloch 2008|AA. Bibliography#Bloch 08]\].

...

These defensive copies would be unnecessary if untrusted code always invoked object's clone() method on mutable state received from mutable classes and then operated only on the cloned copy. Unfortunately, untrusted code has little incentive to do so, and malicious code has every incentive to misbehave. This compliant solution both provides a clone() method to trusted code and also guarantees that the state of the object cannot be compromised when the accessor methods are called directly from untrusted code.

Compliant Solution (Final Instance Members

...

)

When a mutable class's instance fields are declared final and lack accessible copy methods, provide a clone() method as shown in this compliant solution.

public final class MutableClass implements Cloneable {
  private final Date date; // final field 
	
  public MutableClass(Date d) {
    this.date = new Date(d.getTime());  //copy-in 
  }

  public Date getDate() {
    return (Date)date.clone(); //copy and return
  }

  public Object clone() throws CloneNotSupportedException {
    Date d = new Date();
    d = (Date)date.clone();
    MutableClass cloned = new MutableClass(d);
    return cloned;
  }
} 

...