Page History

...

This guideline prohibits publishing a reference to a partially initialized member object instance before initialization completes while TSM01-J. Do not let the (this) reference escape during object construction prohibits the this reference of the current object from escaping.

Noncompliant Code Example

This noncompliant code example constructs a Helper object in the initialize() method of class Foo. The helper field is initialized by Helper's constructor.

...

There is a separate issue in that, if two threads call initialize(), then two Helper objects are created. This is a performance issue and not a correctness issue because n will be properly initialized and the unused Helper objects will be garbage-collected.

Compliant Solution (Synchronization)

Publishing partially-constructed object reference can be prevented by using method synchronization, as shown by this compliant solution.

...

Synchronizing both methods guarantees that they will not execute concurrently. If one thread calls initialize() just before another thread calls getHelper(), the synchronized initialize() method will always finish first. The synchronized keywords establish a happens-before relationship between the two threads. This guarantees that the thread calling getHelper() sees the fully initialized Helper object or none at all (that is, helper contains a null reference). This approach guarantees proper publication for both immutable and mutable members.

Compliant Solution (Final Field)

If the helper field is declared as final, it is guaranteed to be fully constructed before its reference is made visible.

...

Consequently, the reference to the helper field should not be published before class Foo's constructor has finished its initialization (see TSM01-J. Do not let the (this) reference escape during object construction).

Compliant Solution (Final Field and Thread-safe Composition)

Some collection classes provide thread-safe access to contained elements. If the Helper object is inserted into such a collection, it is guaranteed to be fully initialized before its reference is made visible. This compliant solution encapsulates the helper field in a Vector<Helper>.

class Foo {
  private final Vector<Helper> helper;

  public Foo() {
    helper = new Vector<Helper>();  
  }

  public Helper getHelper() {
    if (helper.isEmpty()) {
      initialize();
    }
    return helper.elementAt(0);
  }

  public synchronized void initialize() {
    if (helper.isEmpty()) {
      helper.add(new Helper(42));
    }
  }
}

The helper field is declared as final to guarantee that the vector is created before any accesses take place. It can be safely initialized by the initialize() method, which is synchronized and checks that only one Helper object is ever added to the vector. If getHelper() is invoked before initialize(), it calls initialize() to avoid the possibility of a null-pointer dereference by the client. The getHelper() method does not require synchronization to simply return Helper, and because the synchronized initialize() method also checks to make sure helper is empty before adding a new Helper object, there is no possibility of exploiting a race condition to add a second object to the vector.

Compliant Solution (Static Initialization)

In this compliant solution, the helper field is initialized in a static block. When initialized statically, an object is guaranteed to be fully initialized before its reference is made visible.

// Immutable Foo
final class Foo {
  private static final Helper helper = new Helper(42);

  public static Helper getHelper() {
    return helper;
  } 
}

This requires the helper field to be declared static. Although not a requirement, it is recommended that the field be declared final to document the class's immutability.

...

The rules for class initialization ensure that any thread that reads a static field will be synchronized with the static initialization of that class, which is the only place where static final fields can be set. Thus, no special rules in the JMM are needed for static final fields.

Compliant Solution (Immutable object - Final fields, Volatile Reference)

The Java memory model guarantees that any final fields of an object are fully initialized before a published object becomes visible \[[Goetz 06|AA. Java References#Goetz 06]\]. By declaring {{n}} as final, the {{Helper}} class is made [immutable|BB. Definitions#immutable]. Furthermore, if the {{helper}} field is declared {{volatile}} in compliance with [VNA01-J. Ensure visibility of shared references to immutable objects|VNA01-J. Ensure visibility of shared references to immutable objects], {{Helper}}'s reference is guaranteed to be made visible to any thread that calls {{getHelper()}} after {{Helper}} has been fully initialized.

...

Similarly, a public static factory method that returns a new instance of Helper can be provided in class Helper. This approach allows the Helper instance to be created in a private constructor.

Compliant Solution (Mutable Thread-safe Object, Volatile Reference)

If Helper is mutable, but thread-safe, it can be safely published by declaring the helper field in class Foo as volatile.

class Foo {
  private volatile Helper helper;

  public Helper getHelper() {
    return helper;
  }

  public void initialize() {
    helper = new Helper(42);
  }
}

// Mutable but thread-safe Helper
public class Helper {
  private volatile int n;
  private final Object lock = new Object();

  public Helper(int n) {
    this.n = n;
  }
  
  public void setN(int value) {
    synchronized (lock) {
      n = value;
    }
  }
}

...

Because the the Helper class is declared as public, it uses a private lock to handle synchronization in conformance with LCK00-J. Use private final lock objects to synchronize classes that may interact with untrusted code.

Exceptions

CON28-EX1: Classes that prevent partially initialized objects from being used may publish partially initialized objects. This may be implemented, for example, by setting a volatile boolean flag in the last statement of the initializing code and then ensuring this flag was set before allowing the execution of any class methods.

...

public class Helper {
  private int n;
  private volatile boolean initialized; // Defaults to false

  public Helper(int n) {
    this.n = n;
    this.initialized = true;
  }
  
  public void doSomething() {
    if (!initialized) {
      throw new SecurityException("Cannot use partially initialized instance");
    }
    // ... 
  }
  // ...
}

This ensures that even if the reference to the Helper object instance is published before its initialization is over, the instance is unusable. The instance is unusable because every method within Helper must check the flag to determine whether the initialization has finished.

Risk Assessment

Failing to synchronize access to shared mutable data can cause different threads to observe different states of the object or a partially initialized object.

Automated Detection

TODO

Related Vulnerabilities

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

References

\[[API 06|AA. Java References#API 06]\] 
\[[Bloch 01|AA. Java References#Bloch 01]\] Item 48: "Synchronize access to shared mutable data"
\[[Goetz 06|AA. Java References#Goetz 06]\] Section 3.5.3 "Safe Publication Idioms"
\[[Goetz 07|AA. Java References#Goetz 07]\] Pattern #2: "one-time safe publication"
\[[JPL 06|AA. Java References#JPL 06]\] 14.10.2. "Final Fields and Security"
\[[Pugh 04|AA. Java References#Pugh 04]\]

...