ThreadLocal (Java 2 Platform SE v1.4.1_"07")

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.lang
Class ThreadLocal

    java.lang.Object
      |
      +--java.lang.ThreadLocal

Direct Known Subclasses:
  InheritableThreadLocal

public class ThreadLocal
extends Object

This class provides thread-local variables. These variables differ from their normal counterparts in that each thread that accesses one (via its `get` or `set` method) has its own, independently initialized copy of the variable. `ThreadLocal` instances are typically private static fields in classes that wish to associate state with a thread (e.g., a user ID or Transaction ID).

For example, in the class below, the private static `ThreadLocal` instance (`serialNum`) maintains a "serial number" for each thread that invokes the class's static `SerialNum.get()` method, which returns the current thread's serial number. (A thread's serial number is assigned the first time it invokes `SerialNum.get()`, and remains unchanged on subsequent calls.)

     public class SerialNum {
         // The next serial number to be assigned
         private static int nextSerialNum = 0;

         private static ThreadLocal serialNum = new ThreadLocal() {
             protected synchronized Object initialValue() {
                 return new Integer(nextSerialNum++);
             }
         };

         public static int get() {
             return ((Integer) (serialNum.get())).intValue();
         }
     }

Each thread holds an implicit reference to its copy of a thread-local variable as long as the thread is alive and the `ThreadLocal` 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).

Since:
  1.2

Constructor Summary
`ThreadLocal()`

Method Summary
`Object` | `get()` Returns the value in the current thread's copy of this thread-local variable.
`protected Object` | `initialValue()` Returns the current thread's initial value for this thread-local variable.
`void` | `set(Object value)` Sets the current thread's copy of this thread-local variable to the specified value.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### ThreadLocal

    public ThreadLocal()

Method Detail

### initialValue

    protected Object initialValue()

  Returns the current thread's initial value for this thread-local variable. This method will be called once per accessing thread for each thread-local, the first time each thread accesses the variable with the `get()` or `set(Object)` method. If the programmer desires thread-local variables to be initialized to some value other than `null`, `ThreadLocal` must be subclassed, and this method overridden. Typically, an anonymous inner class will be used. Typical implementations of `initialValue` will call an appropriate constructor and return the newly constructed object.

  Returns:
    the initial value for this thread-local

### get

    public Object get()

  Returns the value in the current thread's copy of this thread-local variable. Creates and initializes the copy if this is the first time the thread has called this method.

  Returns:
    the current thread's value of this thread-local

### set

    public void set(Object value)

  Sets the current thread's copy of this thread-local variable to the specified value. This is only used to change the value from the one assigned by the `initialValue` method, and many applications will have no need for this functionality.

  Parameters:
    `value` - the value to be stored in the current threads' copy of this thread-local.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.