Page History

Mutable classes allow code external to the class to alter their instance or class fields. It is important to provide means for creating copies of mutable classes to allow passing their respective class objects 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.).

The copying mechanism can be advertised by overriding java.lang.Object's clone() method. Use of the clone() method is 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.

...

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

Compliant Solution (

...

Nonfinal Instance Members)

This compliant solution implements the Cloneable interface and overrides the Object.clone() method to create a deep copy of the object.

...

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

This would be unnecessary if untrusted code were to call object's clone() method to operate on the copy, however, untrusted code has little incentive to do so. 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 (

...

Instance Members Declared Final)

Sometimes, a mutable class's instance fields are declared final with no accessible copy methods. In this case, a clone() method should be provided 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. Java References#SCG 07]\]. 

Compliant Solution (copy constructor)

...

This approach is useful when the instance fields are declared final. A copy is requested by invoking the copy constructor with an existing MutableClass instance as 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.

...

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

Exceptions

OBJ10-EX1: Sensitive classes should not be made cloneable. (See guideline MSC05-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.

...