/*

  * Copyright (c) 1997, 2007, 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

  * under the terms of the GNU General Public License version 2 only, as

  * published by the Free Software Foundation.  Oracle designates this

  * particular file as subject to the "Classpath" exception as provided

  * by Oracle in the LICENSE file that accompanied this code.

  *

  * This code is distributed in the hope that it will be useful, but WITHOUT

  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

  * version 2 for more details (a copy is included in the LICENSE file that

  * accompanied this code).

  *

  * You should have received a copy of the GNU General Public License version

  * 2 along with this work; if not, write to the Free Software Foundation,

  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

  *

  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

  * or visit www.oracle.com if you need additional information or have any

  * questions.

  */

 package java.lang;

 /**

  * This class provides thread-local variables.  These variables differ from

  * their normal counterparts in that each thread that accesses one (via its

  * <tt>get</tt> or <tt>set</tt> method) has its own, independently initialized

  * copy of the variable.  <tt>ThreadLocal</tt> instances are typically private

  * static fields in classes that wish to associate state with a thread (e.g.,

  * a user ID or Transaction ID).

  *

  * <p>For example, the class below generates unique identifiers local to each

  * thread.

  * A thread's id is assigned the first time it invokes <tt>ThreadId.get()</tt>

  * and remains unchanged on subsequent calls.

  * <pre>

  * import java.util.concurrent.atomic.AtomicInteger;

  *

  * public class ThreadId {

  *     // Atomic integer containing the next thread ID to be assigned

  *     private static final AtomicInteger nextId = new AtomicInteger(0);

  *

  *     // Thread local variable containing each thread's ID

  *     private static final ThreadLocal<Integer> threadId =

  *         new ThreadLocal<Integer>() {

  *             @Override protected Integer initialValue() {

  *                 return nextId.getAndIncrement();

  *         }

  *     };

  *

  *     // Returns the current thread's unique ID, assigning it if necessary

  *     public static int get() {

  *         return threadId.get();

  *     }

  * }

  * </pre>

  * <p>Each thread holds an implicit reference to its copy of a thread-local

  * variable as long as the thread is alive and the <tt>ThreadLocal</tt>

  * instance is accessible; after a thread goes away, all of its copies of

  * thread-local instances are subject to garbage collection (unless other

  * references to these copies exist).

  *

  * @author  Josh Bloch and Doug Lea

  * @since   1.2

  */

 public class ThreadLocal<T> {

     private static final Object NONE = new Object();

     private Object value = NONE;

     /**

      * Returns the current thread's "initial value" for this

      * thread-local variable.  This method will be invoked the first

      * time a thread accesses the variable with the {@link #get}

      * method, unless the thread previously invoked the {@link #set}

      * method, in which case the <tt>initialValue</tt> method will not

      * be invoked for the thread.  Normally, this method is invoked at

      * 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 <tt>null</tt>; if the

      * programmer desires thread-local variables to have an initial

      * value other than <tt>null</tt>, <tt>ThreadLocal</tt> must be

      * subclassed, and this method overridden.  Typically, an

      * anonymous inner class will be used.

      *

      * @return the initial value for this thread-local

      */

     protected T initialValue() {

         return null;

     }

     /**

      * Creates a thread local variable.

      */

     public ThreadLocal() {

     }

     /**

      * Returns the value in the current thread's copy of this

      * thread-local variable.  If the variable has no value for the

      * current thread, it is first initialized to the value returned

      * by an invocation of the {@link #initialValue} method.

      *

      * @return the current thread's value of this thread-local

      */

     public T get() {

         if (value == NONE) {

             return setInitialValue();

         } else {

             return (T)value;

         }

     }

     /**

      * Variant of set() to establish initialValue. Used instead

      * of set() in case user has overridden the set() method.

      *

      * @return the initial value

      */

     private T setInitialValue() {

         T v = initialValue();

         this.value = v;

         return v;

     }

     /**

      * Sets the current thread's copy of this thread-local variable

      * to the specified value.  Most subclasses will have no need to

      * override this method, relying solely on the {@link #initialValue}

      * method to set the values of thread-locals.

      *

      * @param value the value to be stored in the current thread's copy of

      *        this thread-local.

      */

     public void set(T value) {

         this.value = value;

     }

     /**

      * Removes the current thread's value for this thread-local

      * variable.  If this thread-local variable is subsequently

      * {@linkplain #get read} by the current thread, its value will be

      * reinitialized by invoking its {@link #initialValue} method,

      * unless its value is {@linkplain #set set} by the current thread

      * in the interim.  This may result in multiple invocations of the

      * <tt>initialValue</tt> method in the current thread.

      *

      * @since 1.5

      */

      public void remove() {

          this.value = NONE;

      }

 }