OBJ50-J. Never confuse the immutability of a reference with that of the referenced object

Similarly, a final method parameter obtains an immutable copy of the object reference. Again, this has no effect on the mutability of the referenced data.

Noncompliant Code Example (Mutable Class, final Reference)

In this noncompliant code example, the programmer has declared the reference to the point instance to be final under the incorrect assumption that doing so prevents modification of the values of the instance fields x and y. The values of the instance fields can be changed after their initialization because the final clause applies only to the reference to the point instance and not to the referenced object.

class Point {
  private int x;
  private int y;

  Point(int x, int y) {
    this.x = x;
    this.y = y;
  }
  void set_xy(int x, int y) {
    this.x = x;
    this.y = y;
  }
  void print_xy() {
    System.out.println("the value x is: " + this.x);
    System.out.println("the value y is: " + this.y);
  }
}

public class PointCaller {
  public static void main(String[] args) {
    final Point point = new Point(1, 2);
    point.print_xy();

    // Change the value of x, y
    point.set_xy(5, 6);
    point.print_xy();
  }
}

Compliant Solution (final Fields)

When the values of the x and y instance variables must remain immutable after their initialization, they should be declared final. However, this invalidates a set_xy() method because it can no longer change the values of x and y:

class Point {
  private final int x;
  private final int y;

  Point(int x, int y) {
    this.x = x;
    this.y = y;
  }
  void print_xy() {
    System.out.println("the value x is: " + this.x);
    System.out.println("the value y is: " + this.y);
  }

  // set_xy(int x, int y) no longer possible
}

With this modification, the values of the instance variables become immutable and consequently match the programmer's intended usage model.

Compliant Solution (Provide Copy Functionality)

If the class must remain mutable, another compliant solution is to provide copy functionality. This compliant solution provides a clone() method in the class Point, avoiding the elimination of the setter method:

final public class Point implements Cloneable {
  private int x;
  private int y;

  Point(int x, int y) {
    this.x = x;
    this.y = y;
  }
  void set_xy(int x, int y) {
    this.x = x;
    this.y = y;
  }
  void print_xy() {
    System.out.println("the value x is: "+ this.x);
    System.out.println("the value y is: "+ this.y);
  }
  public Point clone() throws CloneNotSupportedException{
    Point cloned = (Point) super.clone();
    // No need to clone x and y as they are primitives
    return cloned;
  }
}

public class PointCaller {
  public static void main(String[] args) 
      throws CloneNotSupportedException {
    Point point = new Point(1, 2);    // Is not changed in main()
    point.print_xy();
    
    // Get the copy of original object
    Point pointCopy = point.clone();
    // pointCopy now holds a unique reference to the 
    // newly cloned Point instance

    // Change the value of x,y of the copy.
    pointCopy.set_xy(5, 6);

    // Original value remains unchanged
    point.print_xy();
  }
}

The clone() method returns a copy of the original object that reflects the state of the original object at the moment of cloning. This new object can be used without exposing the original object. Because the caller holds the only reference to the newly cloned instance, the instance fields cannot be changed without the caller's cooperation. This use of the clone() method allows the class to remain securely mutable. (See OBJ04-J. Provide mutable classes with copy functionality to safely allow passing instances to untrusted code.)

The Point class is declared final to prevent subclasses from overriding the clone() method. This enables the class to be suitably used without any inadvertent modifications of the original object.

Applicability

Incorrectly assuming that final references cause the contents of the referenced object to remain mutable can result in an attacker modifying an object believed to be immutable.

Bibliography