Page History

...

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 (

...

Copy Constructor)

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 Constructor 
  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());  // Copy-in 
  }

  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.

Compliant Solution (Public Static Factory Method)

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());  // Copy-in   
  }
 
  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, and by implementing the Cloneable interface and providing an Object.clone() method that performs a deep copy of the object.

...

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]\].

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

...

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

...

((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.

...

Callers can use the {{clone()}} method to obtain an instance of such a mutable class. The {{clone()}} method must create a new instance of the {{final}} member class and copy the original state to it. The new instance is necessary because no accessible copy method may be available in the member class. If the member class evolves in the future, it is critical to include the new state in the manual copy. Finally, the {{clone()}} method must create and return a new instance of the enclosing class ({{MutableClass}}) using the newly created member instance ({{d}}) \[[SCG 2007|AA. Bibliography#SCG 07]\]. 

Compliant Solution (Copy Constructor)

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 Constructor 
  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());  // Copy-in 
  }

  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.

Compliant Solution (Public Static Factory Method)

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());  // Copy-in   
  }
 
  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 Mutable classes that define a clone() method must be declared final.

Exceptions

OBJ10-EX1EX0: Sensitive classes should not be cloneable. (See , as per guideline OBJ02-J. Make sensitive classes noncloneable. )

Risk Assessment

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

...