Page History

 must remain exclusive to the thread constructing it, However, once the object is initialized, it can be published, that is, made visible to other threads. 

The Java Memory Model permits a compiler to modify the order of execution instructions in such a way that a seemingly innocuous publication results in multiple threads observing the object after its initialization has begun, but before it has concluded.

This guideline is similar to [CON14-J. Do not let the "this" reference escape during object construction]. The difference is that in this guideline, a reference to a partially constructed object instance is published instead of the {{this}} reference of the current object.

h2. Noncompliant Code Example

This noncompliant code example initializes a {{Helper}} object inside class {{Foo}}.

{code:bgColor=#FFCCCC}
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;
  }

  // ...
}
{code}

Suppose two threads have access to the same {{Foo}} object through the use of the {{getHelper()}} method, and {{initialize()}} has not been called yet. Both threads will see the {{helper}} field as uninitialized. Subsequently, if one thread calls {{initialize()}}, and the other calls {{getHelper()}}, the second thread may either see the {{helper}} reference as {{null}}, observe a fully-initialized {{Helper}} object with the {{n}} field set to 42, or observe a partially-initialized {{Helper}} object with an uninitialized {{n}} (default value of {{n}} being {{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. This introduces a race window during which other threads may see a partially-initialized {{helper}} object.

h2. Compliant Solution ({{volatile}})

If the {{helper}} field is declared as {{volatile}}, it is guaranteed to be fully constructed (properly initialized) before the reference is made visible.

{code:bgColor=#CCCCFF}

class Foo {
  private volatile Helper helper;

  public synchronized Helper getHelper() {
    return helper;
  }

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

Objects of primitive types such as {{Integer}} can also be safely published using a {{java.util.concurrent.atomic.

AtomicReference<V>}} field.

h2. Compliant Solution ({{final}})

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

{code:bgColor=#CCCCFF}
class Foo {
  private final Helper helper;

  public Helper getHelper() {
    return helper;
  }

  public Foo() {
    // Point 1
    helper = new Helper(42);
    }
// Point 2
  }
{code}

class Foo now the compiler disallows setting the {{helper}} field to a new object using the {{initialize()}} method. Instead, a constructor must be used to initialize {{helper}}.

According to the Java Language Specification \[[JLS 05|AA. Java References#JLS 05]\], section 17.5.2 "Reading Final Fields During Construction":

{quote}
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.
{quote}

Consequently, the reference to the {{helper}} field should not be published before class {{Foo}}'s constructor has finished its initialization.

h2. Compliant Solution ({{immutable}})

If the {{Helper}} class is [immutable|BB. Definitions#immutable], it is guaranteed to be fully constructed before its reference is made visible. The {{Helper}} object must be truly immutable; it is not sufficient for the program to refrain from modifying the object.

{code:bgColor=#CCCCFF}
public class Helper {
  private final intVector<Helper> nhelper;

  public HelperFoo(int n) {
    this.nhelper = new nVector<Helper>();
  }

   // ...
}
{code}

For reasons cited in the previous compliant solution, it is critical to ensure that any fields present within class {{Helper}} are not prematurely published. This is an essential condition for constructing [immutable|BB. Definitions#immutable] objects. Additionally, the {{helper}} field in {{Foo}} must be declared as {{final}} and subject to the same safe publication requirement.

Note that if the {{Helper}} object was mutable, in addition to the problem of visibility of a reference to a partially-constructed object, another problem would ensue. The state of the object may be modified after its construction and publication, causing subtle thread-safety issues. For more information see [CON11-J. Do not assume that declaring an object volatile guarantees visibility of its members].


h2. Compliant Solution ({{synchronized}})

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

{code:bgColor=#CCCCFF}
public Helper getHelper() {
    if (helper.isEmpty()) {
      initialize();
    }
    return helper.elementAt(0);
  }

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

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

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

class Foo {
  private volatile Helper helper;

  public synchronized Helper getHelper() {
    return helper;
  }

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

Synchronizing both methods guarantees that they will never run simultaneously in different threads. If one thread were to call {{initialize()}} just before another thread calls {{getHelper()}}, the synchronized {{initialize()}} method will always finish first, fully initializing the {{Helper}} object on its way. This forbids {{getHelper()}} from retrieving a {{
// Immutable Helper
public final class Helper {
  private final int n;

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

Helper}} object that is partially initialized. 


h2. Compliant Solution (thread-safe composition)

Some collection classes provide thread-safety of accesses to contained elements. If the {{helper}} field is contained in such a collection, the {{Helper}} object is guaranteed to be fully constructed before its reference is made visible. This compliant solution encases the {{helper}} field in a {{Vector}}.

{code:bgColor=#CCCCFF}
class Foo {
  private Vector<Helper>volatile Helper helper;

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

  public void initialize() {
    helper = new Vector<Helper>();
    helper.add(new Helper(42));
  }
}
{code}


h2. Compliant Solution (static initialization)

In this compliant solution, the {{helper}} field is initialized in a {{static}} block. When initialized statically, any object is guaranteed to be fully constructed before its reference is made visible. {mc} cite JLS section here {mc}

{code:bgColor=#CCCCFF}
class Foo {
  private static Helper helper = new Helper(42);

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

This requires the {{helper}} field to be declared {{static}}.


h2. 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.

|| Rule || Severity || Likelihood || Remediation Cost || Priority || Level ||
| CON26-J | medium | probable | medium | {color:#cc9900}{*}P8{*}{color} | {color:#cc9900}{*}L2{*}{color} |

h3. Automated Detection

TODO

h3. Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the [CERT website|https://www.kb.cert.org/vulnotes/bymetric?searchview&query=FIELD+KEYWORDS+contains+CON26-J].

h2. 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"
\[[Pugh 04|AA. Java References#Pugh 04]\]

----
[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_left.png!|FIO36-J. Do not create multiple buffered wrappers on an InputStream]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_up.png!|09. Input Output (FIO)]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_right.png!|09. Input Output (FIO)]

// 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;
    }
  }
}

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");
    }
    // ...
  }
  // ...
}