Summary

Update the method level javadoc of initialValue() and get() methods of java.lang.ThreadLocal.

Problem

• The current javadoc of initialValue() method of ThreadLocal class states:

   * ... if the programmer desires thread-local variables to have an initial
   * value other than {@code null}, {@code ThreadLocal} must be
   * subclassed, and this method overridden.  Typically, an
   * anonymous inner class will be used.

Starting Java 8 a new static method withInitial() is available on the ThreadLocal class which allows ThreadLocals to be created with an initial value. However, the current javadoc of initialValue() method doesn't mention this (more convenient) alternative way of providing initial value to the ThreadLocal instance.

• The current javadoc of get() method of ThreadLocal current states:

   * If the current thread does not support thread locals then
   * this method returns its {@link #initialValue} (or {@code null}
   * if the {@code initialValue} method is not overridden).

The latter part of this javadoc isn't true and it may not return null even if the initialValue method isn't overridden. If the current Thread doesn't support thread locals then the get() method will return whatever the call to intialValue() will return and than can be non-null even if ThreadLocal isn't subclassed and instance was created using ThreadLocal.withInitialValue().

Solution

The method level javadoc of initialValue() method will be updated to mention the alternative way of setting initial value for a ThreadLocal. The method level javadoc of get() will be updated to clarify that when the current thread doesn't support thread locals then it will return whatever intialValue() returns.

Specification

--- a/src/java.base/share/classes/java/lang/ThreadLocal.java
+++ b/src/java.base/share/classes/java/lang/ThreadLocal.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -120,13 +120,16 @@ private static int nextHashCode() {
      * most once per thread, but it may be invoked again in case of
      * subsequent invocations of {@link #remove} followed by {@link #get}.
      *
-     * <p>This implementation simply returns {@code null}; if the
+     * @implSpec
+     * This implementation simply returns {@code null}; if the
      * programmer desires thread-local variables to have an initial
-     * value other than {@code null}, {@code ThreadLocal} must be
-     * subclassed, and this method overridden.  Typically, an
-     * anonymous inner class will be used.
+     * value other than {@code null}, then either {@code ThreadLocal}
+     * can be subclassed and this method overridden or the method
+     * {@link ThreadLocal#withInitial(Supplier)} can be used to
+     * construct a {@code ThreadLocal}.
      *
      * @return the initial value for this thread-local
+     * @see #withInitial(java.util.function.Supplier)
      */
     protected T initialValue() {
         return null;
@@ -159,8 +162,7 @@ public ThreadLocal() {
      * current thread, it is first initialized to the value returned
      * by an invocation of the {@link #initialValue} method.
      * If the current thread does not support thread locals then
-     * this method returns its {@link #initialValue} (or {@code null}
-     * if the {@code initialValue} method is not overridden).
+     * this method returns its {@link #initialValue}.
      *
      * @return the current thread's value of this thread-local
      * @see Thread.Builder#allowSetThreadLocals(boolean)