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 must create copies of the particular class instance ; (see rules OBJ06-J. Defensively copy mutable inputs and mutable internal components and OBJ05-J. Defensively copy Do not return references to private mutable class members before returning their references for additional details).

Mutable classes must provide either a copy constructor or a public static factory method that returns a copy of an instance. Alternatively, final classes may advertise their copy functionality by overriding the clone() method of java.lang.Object. Use of the clone() method is secure only for final classes; nonfinal classes must not take this approach.

...

This compliant solution uses a copy constructor that initializes a MutableClass instance when an argument of the same type (or subtype) is passed to it.:

public final class MutableClass { // Copy Constructorconstructor
  private final Date date;

  public MutableClass(MutableClass mc)  {
    this.date = new Date(mc.date.getTime());
  }

  public MutableClass(Date d) {
    this.date = new Date(d.getTime());  // Make defensive copy
  }

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

This approach is useful when the instance fields are declared final. Callers request a copy by invoking the copy constructor with an existing MutableClass instance as its argument.

...

This compliant solution exports a public static factory method getInstance() that creates and returns a copy of a given MutableClass object instance.:

class MutableClass {
  private final Date date;

  private MutableClass(Date d) { // Noninstantiable and nonsubclassable
    this.date = new Date(d.getTime());  // Make defensive copy
  }

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

  public static MutableClass getInstance(MutableClass mc)  {
    return new MutableClass(mc.getDate());
  }
}

This approach is useful when the instance fields are declared final.

Compliant Solution (clone())

This compliant solution provides the needed copy functionality by declaring MutableClass to be final, 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());
  }

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

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

  public Object clone() throws CloneNotSupportedException {
    final MutableClass cloned = (MutableClass) super.clone();
    cloned.date = (Date) date.clone();  // manuallyManually copy mutable Date object
    return cloned;
  }
}

...

Mutable classes that define a clone() method must be declared final. This ensures that to ensure that untrusted code cannot declare a subclass that overrides the clone() method to create a spurious instance. The clone() method should copy all internal mutable state as necessary — in necessary—in this compliant example, the Date object.

When untrusted code can call accessor methods passing mutable arguments, create defensive copies of the arguments before they are stored in any instance fields . See rule (see OBJ06-J. Defensively copy mutable inputs and mutable internal components for additional information). When retrieving internal mutable state, make a defensive copy of that state before returning it to untrusted code . See rule (see OBJ05-J. Defensively copy Do not return references to private mutable class members before returning their references for additional information).

Defensive copies would be unnecessary if untrusted code always invoked an object's clone() method on mutable state received from mutable classes and 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 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 (clone() with

...

Final 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-Copy in
  }

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

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

...

Mutable classes that define a clone() method must be declared final.

Compliant Solution (Unmodifiable Date Wrapper)

...

OBJ04-EX0: Sensitive classes should not be cloneable, per rule OBJ07-J. Sensitive classes must not let themselves be copied.

...

Creating a mutable class without providing copy functionality can result in the data of its instance becoming corrupted when the instance is passed to untrusted code.

Automated Detection

Sound automated detection is infeasible in the general case. Heuristic approaches could be useful.

Related Guidelines

...

...