Page History

Programmers sometimes misconstrue that declaring a variable final makes the referenced object immutable. When the variable is a primitive type, declaring it final means that its value cannot be changed after initialization (other than through the use of the unsupported sun.misc.Unsafe class).

However, when the variable refers to a mutable object, the object's members that appear to be immutable, may in fact be mutable. Similarly, a final method parameter obtains a an immutable copy of the object reference through pass-by-value but the referenced data remains mutable.

According to the Java Language Specification \[[JLS 2005|AA. Bibliography#JLS 05]\], section 4.12.4 "{{final}} Variables"

...

. 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 even after their initialization despite because the final clause applies only to the reference to the point instance being declared as finaland 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();

    // changeChange 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 as final. However, this requires the elimination of the setter method 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 final class Point and does not require 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 {
    final 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 and that reflects its latest statethe state of the original object at the moment of cloning. This new object can be freely used without exposing the original object. Using . 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 guideline OBJ10OBJ04-J. Provide mutable classes with copy functionality to safely allow passing instances to untrusted code safely.)

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. This compliant solution complies with guideline OBJ10-J. Provide mutable classes with copy functionality to allow passing instances to untrusted code safely.

Noncompliant Code Example (Arrays)

This noncompliant code example uses a public static final array, items.

public static final String[] items = { ... };

Clients can trivially modify the contents of the array, though they are unable to change the array reference because it is final.

Compliant Solution (Clone the Array)

This compliant solution defines a private array and a public method that returns a copy of the array.

private static final String[] items = { ... };

public static final String[] somethings() {
  return items.clone();
}

Consequently, the original array values cannot be modified by a client. Note that a manual deep copy may be required when dealing with arrays of objects. This generally happens when the objects do not export a clone() method. Refer to guideline FIO00-J. Defensively copy mutable inputs and mutable internal components for more information.

Compliant Solution (Unmodifiable Wrappers)

This compliant solution declares a private array from which a public immutable list is constructed.

private static final String[] items = { ... };

public static final List<String> itemsList =
Collections.unmodifiableList(Arrays.asList(items));

Neither the original array values nor the public list can be modified by a client. For more details about unmodifiable wrappers, refer to SEC14-J. Provide sensitive mutable classes with unmodifiable wrappers.

Risk Assessment

Using final to declare the reference to a mutable object is potentially misleading because the contents of the object can still be changed.

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this guideline on the CERT website.

Bibliography

\[[JLS 2005|AA. Bibliography#JLS 05]\] Sections 4.12.4 "final Variables" and 6.6, "Access Control"
\[[Bloch 2008|AA. Bibliography#Bloch 08]\] Item 13: Minimize the accessibility of classes and members
\[[Core Java 2004|AA. Bibliography#Core Java 04]\] Chapter 6
\[[MITRE 2009|AA. Bibliography#MITRE 09]\] [CWE ID 607|http://cwe.mitre.org/data/definitions/607.html] "Public Static Final Field References Mutable 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

...

Image Added Image Added Image AddedOBJ00-J. Declare data members as private and provide accessible wrapper methods      08. Object Orientation (OBJ)      OBJ02-J. Do not ignore return values of methods that operate on immutable objects