Page History

Mutable classes allow code external to the class to alter their instance or class fields. It is important to provide Provide means for creating copies of mutable classes to allow passing their respective class objects 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 ; 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 classes should 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 The copying mechanism can be advertised by overriding java.lang.Object's clone() method. Use of the clone() method is secure only secure for final classes. Nonfinal classes must either provide a copy constructor or a public static factory method that returns a copy of the instance.; non-final classes are forbidden to use this approach.

Trusted callers can be trusted to make defensive copies by use the provided copy functionality 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 On its own, providing copy functionality does not obviate the need of creating defensive copies of input received from untrusted code, and of output that is returned to the same. Only a trusted caller can be expected to responsibly use the copy functionality of the class before passing the object instance to untrusted code.

Noncompliant Code Example

In this noncompliant code example, MutableClass uses a mutable field date of type Date. The instance member Class Date is also a mutable class.

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;	
  }
}

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

Compliant Solution (Nonfinal Instance Members)

This compliant solution implements provides the needed copy functionality by declaring MutableClass to be final, and by implementing the Cloneable interface and overrides the providing an Object.clone() method to create 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. WhenHowever, when the fields contain data such as unique identifiers or object creation times, the new values of the fields must be calculated and assigned manually in the {{clone()}} method{{clone()}} method must calculate and assign appropriate new values for such fields \[[Bloch 2008|AA. Bibliography#Bloch 08]\].

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

Also, if When untrusted code can call accessor methods and can pass mutable arguments, it is advisable to copy make defensive copies of the arguments before they are stored in any instance fields. ( See guideline FIO00-J. Defensively copy mutable inputs and mutable internal components for additional information. ) When retrieving internal mutable state, make a defensive copy of the members must be created that state before returning their references it to untrusted code. ( See guideline OBJ11-J. Defensively copy private mutable class members before returning their references for additional information. )

This These defensive copies would be unnecessary if untrusted code were to call always invoked object's clone() method to operate on mutable state received from mutable classes and then operated only on the cloned copy. Unfortunately, however, 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 (Instance Members Declared Final)

Sometimes, When a mutable class's instance fields are declared final with no and lack accessible copy methods. In this case, provide a clone() method should be provided as shown in this compliant solution.

...

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

Compliant Solution (Public Static Factory Method)

...

\[[API 2006|AA. Bibliography#API 06]\] [method clone()|http://java.sun.com/javase/6/docs/api/java/lang/Object.html#clone()]
\[[Security 2006|AA. Bibliography#Security 06]\]
\[[SCG 2007|AA. Bibliography#SCG 07]\] Guideline 2-2 Support copy functionality for a mutable class
\[[SCG 2009|AA. Bibliography#SCG 09]\] Guideline 2-3 Support copy functionality for a mutable class
\[[Bloch 2008|AA. Bibliography#Bloch 08]\] Item 39: Make defensive copies when needed and Item 11: Override clone judiciously
\[[MITRE 2009|AA. Bibliography#MITRE 09]\] [CWE ID 374|http://cwe.mitre.org/data/definitions/374.html] "Mutable Objects Passed by Reference", [CWE ID 375|http://cwe.mitre.org/data/definitions/375.html] "Passing Mutable Objects to an Untrusted Method"\[[Security 2006|AA. Bibliography#Security 06]\]
\[[SCG 2007|AA. Bibliography#SCG 07]\] Guideline 2-2 Support copy functionality for a mutable class
\[[SCG 2009|AA. Bibliography#SCG 09]\] Guideline 2-3 Support copy functionality for a mutable class

...

OBJ09-J. Immutable classes must prohibit extension      08. Object Orientation (OBJ)      OBJ11-J. Defensively copy private mutable class members before returning their references