According to the Java Language Specification \[[JLS 2005|AA. Bibliography#JLS 05]\], §15.8.3, {{this}}

{quote}
when used as a primary expression, the keyword {{this}} denotes a value that is a reference to the object for which the instance method was invoked (§15.12), or to the object being constructed. The type of {{this}} is the class {{C}} within which the keyword {{this}} occurs. At run time, the class of the actual object referred to may be the class {{C}} or any subclass of {{C}}.
{quote}

The {{this}} reference is said to have escaped when it is made available beyond its current scope. Common ways by which the {{this}} reference can escape include
* returning {{this}} from a non-private, overridable method that is invoked from the constructor of a class whose object is being constructed. (For more information, see rule [MET05-J. Ensure that constructors do not call overridable methods].) {mc} subclasses! {mc}
* returning {{this}} from a non-private method of a mutable class, which allows the caller to manipulate the object's state indirectly. This commonly occurs in method-chaining implementations; see rule [VNA04-J. Ensure that calls to chained methods are atomic] for more information.
* passing {{this}} as an argument to an [alien method|BB. Definitions#alien method] invoked from the constructor of a class whose object is being constructed.
* using inner classes. An inner class implicitly holds a reference to the instance of its outer class, unless the inner class is declared static.
* publishing by assigning {{this}} to a public static variable from the constructor of a class whose object is being constructed.
* overriding the finalizer of a non-final class and obtaining the {{this}} reference of a partially initialized instance, when the construction of the object ceases. (For more information, see rule [OBJ11-J. Be wary of letting constructors throw exceptions].) This can happen when the constructor throws an exception. Misuse is not limited to untrusted code; trusted code can also inadvertently add a finalizer and let {{this}} escape by violating rule [MET12-J. Do not use finalizers].
* passing internal object state to an [alien method|BB. Definitions#alien method]. This enables the method to retrieve the {{this}} reference of the internal member object.

This rule describes the potential consequences of allowing the {{this}} reference to escape during object construction, including race conditions and improper initialization. For example, declaring a field final ordinarily ensures that all threads see the field in a fully initialized state; however, allowing the {{this}} reference to escape during object construction can expose the field to other threads in an uninitialized or partially-initialized state. Rule [TSM03-J. Do not publish partially initialized objects], which describes the guarantees provided by various mechanisms for safe publication, relies on conformance to this rule. Consequently, programs must not allow the {{this}} reference to escape during object construction.

In general, it is important to detect cases where the {{this}} reference can leak out beyond the scope of the current context. In particular, {{public}} variables and methods should be carefully scrutinized.


h2. Noncompliant Code Example (Publish Before Initialization)

This noncompliant code example publishes the {{this}} reference before initialization has concluded, by storing it in a {{public static volatile}} class field.

{code:bgColor=#FFcccc}
final class Publisher {
  public static volatile Publisher published;
  int num;

  Publisher(int number) {
    published = this;
    // Initialization
    this.num = number;
    // ...
  }
}
{code}

Consequently, other threads can obtain a partially-initialized {{Publisher}} instance. Also, if the object initialization (and consequently, its construction) depends on a security check within the constructor, the security check can be bypassed when an untrusted caller obtains the partially initialized instance. For more information, see rule [OBJ11-J. Be wary of letting constructors throw exceptions].


h2. Noncompliant Code Example (Non-volatile Public Static Field)

This noncompliant code example publishes the {{this}} reference in the last statement of the constructor. It remains vulnerable because the {{published}} field has public accessibility and the programmer has failed to declare it as volatile.

{code:bgColor=#FFcccc}
final class Publisher {
  public static Publisher published;
  int num;

  Publisher(int number) {
    // Initialization
    this.num = number;
    // ...
    published = this;
  }
}
{code}

Because the field is non-volatile and non-final, the statements within the constructor can be reordered by the compiler in such a way that the {{this}} reference is published before the initialization statements have executed.

h2. Compliant Solution (Volatile Field and Publish after Initialization)

This compliant solution both declares the {{published}} field volatile and also reduces its accessibility to package-private so that callers outside the current package scope cannot obtain the {{this}} reference.

{code:bgColor=#ccccff}
final class Publisher {
  static volatile Publisher published;
  int num;

  Publisher(int number) {
    // Initialization
    this.num = number;
    // ...
    published = this;
  }
}
{code}

The constructor publishes the {{this}} reference after initialization has concluded. However, the caller that instantiates {{Publisher}} must ensure that it cannot see the default value of the {{num}} field before it is initialized; to do otherwise would violate rule [TSM03-J. Do not publish partially initialized objects]. Consequently, the field that holds the reference to {{Publisher}} might need to be declared volatile in the caller.

Initialization statements may be reordered when the {{published}} field is not declared volatile. The Java compiler, however, does forbids declaring fields as both {{volatile}} and {{final}}.

The class {{Publisher}} must also be {{final}}; otherwise, a subclass can call its constructor and publish the {{this}} reference before the subclass's initialization has concluded.


h2. Compliant Solution (Public Static Factory Method)

This compliant solution eliminates the internal member field and provides a {{newInstance()}} factory method that creates and returns a {{Publisher}} instance.

{code:bgColor=#ccccff}
final class Publisher {
  final int num;

  private Publisher(int number) {
    // Initialization
    this.num = number;
  }

  public static Publisher newInstance(int number) {
    Publisher published = new Publisher(number);
    return published;
  }
}
{code}

This approach ensures that threads cannot see an inconsistent {{Publisher}} instance. The {{num}} field is also declared {{final}}, making the class immutable and consequently eliminating the possibility of obtaining a partially initialized object.

h2. Noncompliant Code Example (Handlers)

This noncompliant code example defines the {{ExceptionReporter}} interface:

{code}
public interface ExceptionReporter {
  public void setExceptionReporter(ExceptionReporter er);
  public void report(Throwable exception);
}
{code}

This interface is implemented by the {{DefaultExceptionReporter}} class, which reports exceptions after filtering out any sensitive information. See rule [ERR00-J. Do not suppress or ignore checked exceptions] for more information.

The {{DefaultExceptionReporter}} constructor prematurely publishes the {{this}} reference before construction of the object has concluded. This occurs in the last statement of the constructor  ({{er.setExceptionReporter(this)}}), which sets the exception reporter. Because it is the last statement of the constructor, this may be misconstrued as benign.

{code:bgColor=#FFcccc}
// Class DefaultExceptionReporter
public class DefaultExceptionReporter implements ExceptionReporter {
  public DefaultExceptionReporter(ExceptionReporter er) {
    // Carry out initialization
    // Incorrectly publishes the "this" reference
    er.setExceptionReporter(this);
  }

  // Implementation of setExceptionReporter() and report()
}
{code}

The {{MyExceptionReporter}} class subclasses {{DefaultExceptionReporter}} with the intent of adding a logging mechanism that logs critical messages before reporting an exception.

{code:bgColor=#FFcccc}
// Class MyExceptionReporter derives from DefaultExceptionReporter
public class MyExceptionReporter extends DefaultExceptionReporter {
  private final Logger logger;

  public MyExceptionReporter(ExceptionReporter er) {
    super(er); // Calls superclass's constructor
    logger = Logger.getLogger("com.organization.Log"); // Obtain the default logger
  }

  public void report(Throwable t) {
    logger.log(Level.FINEST,"Loggable exception occurred", t);
  }
}
{code}

Its constructor invokes the {{DefaultExceptionReporter}} superclass's constructor (a mandatory first step), which publishes the exception reporter before the initialization of the subclass has concluded. Note that the subclass initialization consists of obtaining an instance of the default logger. Publishing the exception reporter is equivalent to setting it to receive and handle exceptions from that point on.

Logging will fail when an exception occurs before the call to {{Logger.getLogger()}} in the {{MyExceptionReporter}} subclass because dereferencing the uninitialized {{logger}} field generates a {{NullPointerException}}, which could itself be consumed by the reporting mechanism without being logged.

This erroneous behavior results from the race condition between an oncoming exception and the initialization of {{MyExceptionReporter}}. When the exception comes too soon, it will find the {{MyExceptionReporter}} object in an inconsistent state. This behavior is especially counterintuitive because {{logger}} has been declared {{final}}, so observing an uninitialized value would be unexpected.

Premature publication of an event listener causes a similar problem; the listener can receive event notifications before the subclass's initialization has finished.


h2. Compliant Solution

This compliant solution adds a {{publishExceptionReporter()}} method to {{DefaultExceptionReporter}} to permit setting the exception reporter, rather than publishing the {{this}} reference from the {{DefaultExceptionReporter}} constructor. This method can be invoked on a subclass instance after the subclass's initialization has concluded.

{code:bgColor=#ccccff}
public class DefaultExceptionReporter implements ExceptionReporter {
  public DefaultExceptionReporter(ExceptionReporter er) {
    // ...
  }

  // Should be called after subclass's initialization is over
  public void publishExceptionReporter() {
    setExceptionReporter(this); // Registers this exception reporter
  }

  // Implementation of setExceptionReporter() and report()
}
{code}

The {{MyExceptionReporter}} subclass inherits the {{publishExceptionReporter()}} method. Callers who instantiate {{MyExceptionReporter}} can use the resulting instance to set the exception reporter after initialization is complete.

{code:bgColor=#ccccff}
// Class MyExceptionReporter derives from DefaultExceptionReporter
public class MyExceptionReporter extends DefaultExceptionReporter {
  private final Logger logger;

  public MyExceptionReporter(ExceptionReporter er) {
    super(er); // Calls superclass's constructor
    logger = Logger.getLogger("com.organization.Log");
  }
  // Implementations of publishExceptionReporter(), setExceptionReporter() and 
  //report() are inherited
}
{code}

This approach ensures that the reporter cannot be set before the constructor has fully initialized the subclass and enabled logging.


h2. Noncompliant Code Example (Inner Class)

Inner classes maintain a copy of the {{this}} reference of the outer object. Consequently, the {{this}} reference could leak outside the scope \[[Goetz 2002|AA. Bibliography#Goetz 02]\]. This noncompliant code example uses a different implementation of the {{DefaultExceptionReporter}} class. The constructor uses an anonymous inner class to publish a {{filter()}} method.

{code:bgColor=#FFcccc}
public class DefaultExceptionReporter implements ExceptionReporter {
  public DefaultExceptionReporter(ExceptionReporter er) {
    er.setExceptionReporter(new DefaultExceptionReporter(er) {
      public void report(Throwable t) {
        filter(t);
      }
    });
  }
  // Default implementations of setExceptionReporter() and report()
}
{code}

Other threads can see the {{this}} reference of the outer class because it is published by the inner class. Furthermore, the issue described in the noncompliant code example for handlers will resurface if the class is subclassed.


h2. Compliant Solution

Use a {{private}} constructor and a public static factory method to safely publish the {{filter()}} method from within the constructor \[[Goetz 2006|AA. Bibliography#Goetz 06]\].

{code:bgColor=#ccccff}
public class DefaultExceptionReporter implements ExceptionReporter {
  private final DefaultExceptionReporter defaultER;

  private DefaultExceptionReporter(ExceptionReporter excr) {
    defaultER = new DefaultExceptionReporter(excr) {
      public void report(Throwable t) {
        filter(t);
      }
    };
  }

  public static DefaultExceptionReporter newInstance(ExceptionReporter excr) {
    DefaultExceptionReporter der = new DefaultExceptionReporter(excr);
    excr.setExceptionReporter(der.defaultER);
    return der;
  }
  // Default implementations of setExceptionReporter() and report()
}
{code}

Because the constructor is {{private}}, untrusted code cannot create instances of the class; consequently, the {{this}} reference cannot escape. Using a {{public static}} factory method to create new instances also protects against untrusted manipulation of internal object state and publication of partially initialized objects. See rule [TSM03-J. Do not publish partially initialized objects] for additional information.


h2. Noncompliant Code Example (Thread)

This noncompliant code example starts a thread inside the constructor.

{code:bgColor=#FFcccc}
final class ThreadStarter implements Runnable {
  public ThreadStarter() {
    Thread thread = new Thread(this);
    thread.start();
  }

  @Override public void run() {
    // ...
  }
}
{code}

The new thread can access the {{this}} reference of the current object \[[Goetz 2002|AA. Bibliography#Goetz 02]\], \[[Goetz 2006|AA. Bibliography#Goetz 06]\]. Notably, the {{Thread()}} constructor is [alien|BB. Definitions#alien method] to the {{ThreadStarter}} class.


h2. Compliant Solution (Thread)

This compliant solution creates and starts the thread in a method rather than in the constructor.

{code:bgColor=#ccccff}
final class ThreadStarter implements Runnable {
  public ThreadStarter() {
    // ...
  }

  public void startThread() {
    Thread thread = new Thread(this);
    thread.start();
  }

  @Override public void run() {
    // ...
  }
}
{code}


h2. Exceptions

*TSM01-EX0*: It is safe to create a thread in the constructor, provided the thread is not started until _after_ object construction is complete, because a calls to {{start()}} on a thread happen-before any actions in the started thread \[[JLS 2005|AA. Bibliography#JLS 05]\].

Even though this code example creates a thread that reference {{this}} in the constructor, the thread is started only when its {{start()}} method is called from the {{startThread()}} method \[[Goetz 2002|AA. Bibliography#Goetz 02]\], \[[Goetz 2006|AA. Bibliography#Goetz 06]\].

{code:bgColor=#ccccff}
final class ThreadStarter implements Runnable {
  Thread thread;

  public ThreadStarter() {
    thread = new Thread(this);
  }

  public void startThread() {
    thread.start();
  }

  @Override public void run() {
    // ...
  }
}
{code}

*TSM01-EX1*: Use of the {{ObjectPreserver}} pattern \[[Grand 2002|AA. Bibliography#Grand 02]\] described in rule [TSM02-J. Do not use background threads during class initialization] is also safe and is permitted.

h2. Risk Assessment

Allowing the {{this}} reference to escape could result in improper initialization and runtime exceptions.

|| Rule || Severity || Likelihood || Remediation Cost || Priority || Level ||
| TSM01-J | medium | probable | high | {color:green}{*}P4{*}{color} | {color:green}{*}L3{*}{color} |

h2. Bibliography

| \[[JLS 2005|AA. Bibliography#JLS 05]\] | Keyword "this" |
| \[[Goetz 2002|AA. Bibliography#Goetz 02]\] | |
| \[[Goetz 2006|AA. Bibliography#Goetz 06]\] | Section 3.2, "Publication and Escape" |
| \[[Grand 2002|AA. Bibliography#Grand 02]\] | Chapter 5, "Creational Patterns, Singleton" |


h2. Issue Tracking

{tasklist:Review List}
||Completed||Priority||Locked||CreatedDate||CompletedDate||Assignee||Name||
|T|M|F|1270219843973|1270221864972|svoboda|"*Inner classes* implicitly hold a reference to the instance of the outer class, unless the inner class is declared as static." => Change inner classes to "An inner class implicitly holds ... "|
|T|M|F|1270220129871|1270755934790|rcs|"Note that this code also violates CON32-J. Protect accessible mutable static fields from untrusted code" => Not sure if I agree because the class is package-private and inaccessible to untrusted code|
|T|M|F|1270733657099|1271021912028|rcs_mgr|"A Runnable object's constructor may construct a Thread object around itself, as long as the thread is not actually started in the Runnable object's constructor." => I still think this info is redundant.|
{tasklist}

----
[!The CERT Oracle Secure Coding Standard for Java^button_arrow_left.png!|TSM00-J. Do not override thread-safe methods with methods that are not thread-safe]      [!The CERT Oracle Secure Coding Standard for Java^button_arrow_up.png!|11. Thread-Safety Miscellaneous (TSM)]      [!The CERT Oracle Secure Coding Standard for Java^button_arrow_right.png!|TSM02-J. Do not use background threads during class initialization]