During initialization of a shared object, the object must only be accessible to the thread constructing it. However, the object can be safely published (that is, made visible to other threads) once it is initialized. The [Java Memory Model (JMM)|BB. Definitions#Java Memory Model] 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 differs from other guidelines in that it prohibits publishing a reference to a partially initialized member object instance before initialization completes while [CON14-J. Do not let the "this" reference escape during object construction] refers to the {{this}} reference of the current object.
h2. 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.
{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}
If a thread accesses {{helper}} using the {{getHelper()}} method before {{initialize()}} has been called, the thread will observe an uninitialized {{helper}} field. Later, if one thread calls {{initialize()}}, and another calls {{getHelper()}}, the second thread might observe 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 uninitialized {{n}} which contains the default value {{0}}.
In particular, the [JMM|BB. Definitions#memory model] 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 {{helper}} instance field with the write that initializes the {{Helper}} object (that is, {{this.n = n}}) such that the former occurs first. This exposes a race window during which other threads may observe a partially-initialized {{Helper}} object instance.
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.
h2. Compliant Solution (Synchronization)
Publishing partially-constructed object reference can be prevented by using method synchronization, as shown by this compliant solution.
{code:bgColor=#CCCCFF}
class Foo {
private Helper helper;
public synchronized Helper getHelper() {
return helper;
}
public synchronized void initialize() {
helper = new Helper(42);
}
}
{code}
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|BB. Definitions#happens-before order] 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.
h2. 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.
{code:bgColor=#CCCCFF}
class Foo {
private final Helper helper;
public Helper getHelper() {
return helper;
}
public Foo() {
helper = new Helper(42);
}
}
{code}
However, this solution requires that the {{helper}} field is assigned to a new object during construction. According to the Java Language Specification, Section 17.5.2, "Reading Final Fields During Construction" \[[JLS 05|AA. Java References#JLS 05]\]:
{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 (see [CON14-J. Do not let the "this" reference escape during object construction]).
h2. 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>}}.
{code:bgColor=#CCCCFF}
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));
}
}
}
{code}
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.
h2. 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.
{code:bgColor=#CCCCFF}
// Immutable Foo
final class Foo {
private static final Helper helper = new Helper(42);
public static Helper getHelper() {
return helper;
}
}
{code}
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.
According to JSR-133, Section 9.2.3, "Static Final Fields" \[[JSR-133 04|AA. Java References#JSR-133 04]\]:
{quote}
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.
{quote}
h2. 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 [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.
{code:bgColor=#CCCCFF}
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;
}
// ...
}
{code}
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 necessary (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].
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.
h2. 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}}.
{code:bgColor=#CCCCFF}
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;
}
}
}
{code}
Because the {{Helper}} object can change state after its construction, lockingsynchronization is necessary to ensure the visibility of {{n}} mutable members 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, Consequently, the {{setN()}} method is synchronized to provide visibility of {{n}} in this compliant solution, the {{setN()}} method needs to be synchronized. (See(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 its members]).
If the {{Helper}}, the use of class is not properly synchronized, declaring {{helper} as volatile}} in class {{Foo}} only guarantees the visibility of only the initial publication of {{Helper}} and not of subsequent state changes. Consequently, {{volatile}} references isalone notare usefulinadequate 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}}. {mc} please double check this para {mc}
Note that the {{Helper}} class uses a private lock to handle synchronization, because the class is public. (See in conformance with [CON04-J. Use private final lock objects to synchronize classes that may interact with untrusted code] for more information.)
h2. Exceptions
*CON26-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.
{mc} not a good idea to call this class thread-safe, bad for maintainability because someone might forget to use the flag in a new method if you call it thread-safe and even other wise, the flag only guarantees proper initializatininitialization, not thread-safety {mc}
{code:bgColor=#CCCCFF}
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");
}
// ...
}
// ...
}
{code}
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 usefulapplicable when the caller ({{Foo}}) is untrusted and consequently, may not declare the {{helper}} field as {{volatile}}.
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"
\[[JPL 06|AA. Java References#JPL 06]\] 14.10.2. "Final Fields and Security"
\[[Pugh 04|AA. Java References#Pugh 04]\]
----
[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_left.png!|CON25-J. Ensure atomicity when reading and writing 64-bit values] [!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_up.png!|11. Concurrency (CON)] [!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_right.png!|CON27-J. Do not execute classes that use ThreadLocal objects in a thread pool]
|
