CON26-J. Do not publish partially initialized objects

During initialization of a shared object, the object must remain exclusive to the thread constructing it. However, once the object is initialized, it can be safely published. That is, it can be made visible to other threads. The [Java Memory Model (JMM)] allows multiple threads to observe the object after its initialization has begun, but before it has concluded. Consequently, it is important to ensure that a partially initialized object is not published.

This guideline is similar to [CON14-J. Do not let the "this" reference escape during object construction]. In this guideline, a reference to a partially initialized member object instance is published before initialization is over, instead of the this reference of the current object.

Noncompliant Code Example

This noncompliant code example uses an initialize() method to construct a Helper object inside class Foo, and initializes the helper field accordingly.

class Foo {
  private Helper helper;

  public Helper getHelper() {
    return helper;
  }

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

public class Helper {
  private int n;

  public Helper(int n) {
    this.n = n;
  }
  // ...
}

If a thread accesses helper using the getHelper() method, and initialize() has not been called yet, the thread will see the helper field as uninitialized. Later, if one thread calls initialize(), and another calls getHelper(), the second thread might see the helper reference as null, or it might observe a fully-initialized Helper object with the n field set to 42, or it might observe a partially-initialized Helper object with an n that has not been initialized yet, and which contains the default value 0.

In particular, the [JMM] permits compilers to allocate memory for the new Helper object and assign it to the helper field before initializing it. In other words, the compiler can reorder the write to the instance field helper with the write that initializes the object Helper (that is, this.n = n) such that the former occurs first. This introduces a race window during which other threads may see a partially-initialized Helper object instance.

There is another consideration in that if two threads call initialize(), then two Helper objects will be created, with one eventually being garbage-collected. This is a performance issue as opposed to a correctness issue, because n always contains the value 42.

Compliant Solution (synchronization)

The reference of a partially-constructed object can be prevented from being made visible by using method synchronization as shown below.

class Foo {
  private Helper helper;

  public synchronized Helper getHelper() {
    return helper;
  }

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

Synchronizing both methods guarantees that they will never run simultaneously in different threads. 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 (helper may contain 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.

class Foo {
  private final Helper helper;

  public Helper getHelper() {
    return helper;
  }

  public Foo() {
    helper = new Helper(42);
  }
}

However, now the compiler disallows setting the helper field to a new object using the initialize() method. Instead, a constructor is required to initialize helper.

According to the Java Language Specification, section 17.5.2 "Reading Final Fields During Construction" [[JLS 05]]:

A read of a final field of an object within the thread that constructs that object is ordered with respect to the initialization of that field within the constructor by the usual happens-before rules. If the read occurs after the field is set in the constructor, it sees the value the final field is assigned, otherwise it sees the default value.

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

Compliant Solution (final field and thread-safe composition)

Some collection classes provide thread-safety of accesses 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 encases 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 suitably initialized using the initialize() method. The initialize() method is synchronized, and provides a check to ensure that exactly one Helper object is added to the vector. The getHelper() method does not need any synchronization in the general case of returning the Helper, however, if it is invoked before initialize(), it ensures that the vector contains the Helper instance to avoid a null-pointer dereference. For this reason it invokes initialize() when it finds that the vector is empty.

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 strictly necessary, it is recommended that the field be declared final to sufficiently document the class's immutability property.

According to JSR-133 [[JSR-133 04]], 9.2.3 Static Final Fields:

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 the object will be fully initialized before a published object becomes visible [[Goetz 06]]. By making n final, we can render the Helper class [immutable]. Furthermore, if the helper field is declared volatile in compliance with [CON09-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.

class Foo {
  private volatile Helper helper;

  public Helper getHelper() {
    return helper;
  }

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

// Immutable Helper
public final class Helper {
  private final int n;

  public Helper(int n) {
    this.n = n;
  }
  // ...
}

Similarly, a public static factory method that returns a new instance of Helper can be provided in class Helper. The Helper instance is created using a private constructor.

This compliant solution requires that helper be declared as volatile and class Helper be immutable. If it were not immutable, the code would violate [CON11-J. Do not assume that declaring an object reference volatile guarantees visibility of its members] and additional synchronization would be required to fix it (see the next compliant solution). And if the helper field were not volatile, it would violate [CON09-J. Ensure visibility of shared references to immutable objects]. See that rule for more information on how safely publishing immutable objects.

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 state of the Helper object can be changed after its construction, locking is necessary to ensure that all threads see the most recent value of n after the initial publication. This is typically the case when a mutable member object is expected to continually publish its most recent state when its reference is declared volatile. Consequently, in this compliant solution, the setN() method needs to be synchronized. (See [CON11-J. Do not assume that declaring an object reference volatile guarantees visibility of its members] for more information.)

In the absence of proper synchronization in class Helper, the use of volatile in class Foo guarantees the visibility of only the initial publication of Helper and not of subsequent state changes. Consequently, volatile is not useful for publishing objects that are not thread-safe.

When helper in class Foo is not declared as volatile, the field n should be declared as volatile so that a happens-before relationship is established between the initialization of n and the write of Helper to the field helper. This is in compliance with [CON11-J. Do not assume that declaring an object reference volatile guarantees visibility of its members]. This is only required when the caller (class Foo) cannot be trusted to declare helper as volatile.

Note that the Helper class uses a private lock to handle synchronization, because the class is public. (See [CON04-J. Use private final lock objects to synchronize classes that may interact with untrusted code] for more information.)

Exceptions

EX1: This exception uses a volatile initialized flag, as recommended by [CON28-J. Prevent partially initialized objects from being used]. The corresponding Foo class is the same as the noncompliant code example.

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. This is because every method within Helper must check the flag to determine whether the initialization has finished. This approach is more useful when the caller (Foo) is untrusted and consequently, may not declare the helper field as volatile.

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]]
[[Bloch 01]] Item 48: "Synchronize access to shared mutable data"
[[Goetz 06]] Section 3.5.3 "Safe Publication Idioms"
[[Goetz 07]] Pattern #2: "one-time safe publication"
[[JPL 06]], 14.10.2. Final Fields and Security:
[[Pugh 04]]

[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_left.png!]      [!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_up.png!]      [!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_right.png!]