get() and set() methods)
* only affects the state of the object as seen by the currently
* executing Thread.
*
* The first time a ThreadLocal object is accessed on a particular
* Thread (and no state is associated with that Thread yet)
* the state for that Thread is set by executing the method
* initialValue().
*
* An example how you can use this: *
* class Connection {
* private static ThreadLocal owner = new ThreadLocal() {
* public Object initialValue() {
* return("nobody");
* }
* };
* ...
* }
*
* Now all instances of connection can see who the owner of the currently
* executing Thread is by calling owner.get(). By default any
* Thread would be associated with 'nobody'. But the Connection object could
* offer a method that changes the owner associated with the Thread on
* which the method was called by calling owner.put("somebody").
* (Such an owner changing method should then be guarded by security checks.)
*
* When a Thread is garbage collected all references to values of
* the ThreadLocal objects associated with that Thread are removed.
*
* @since 1.2
* @author Mark Wielaard (mark@klomp.org)
*/
public class ThreadLocal {
/**
* Trivial container to wrap the stored values.
* Needed to see if the value is null or not yet set.
* If it is not yet set we must call intialValue() once.
* Package local so InheritableThreadLocal can see it.
*/
final static class Value {
final Object value;
Value(Object value) {
this.value = value;
}
Object getValue() {
return value;
}
}
/**
* Maps Threads to Values. Uses a WeakHashMap so if a Thread is garbage
* collected the reference to the Value will disappear. Only the
* set(Thread, Value) and get(Thread) methods
* access it. Since this can happen from multiple Threads simultaniously
* those methods are synchronized.
*/
private final Map valueMap = new WeakHashMap();
/**
* Creates a ThreadLocal object without associating any value to it
* yet.
*/
public ThreadLocal() {
}
/**
* Gets the value associated with the ThreadLocal object for the
* currently executing Thread. If there is no value is associated
* with this Thread yet then the valued returned by the
* initialValue() method is assosiated with this Thread
* and returned.
*/
public Object get() {
Thread currentThread = Thread.currentThread();
Value v = get(currentThread);
if (v == null) {
v = new Value(initialValue());
set(currentThread, v);
}
return v.getValue();
}
/**
* Gets the Value of this ThreadLocal for a particular Thread.
* It is synchronized so the set(Thread, Value) method cannot
* simultaniously modify the valueMap from another thread.
* Package local so InheritableThreadLocal can access it when a new child
* Thread inherits values from its parent Thread.
*/
synchronized final Value get(Thread thread) {
return (Value)valueMap.get(thread);
}
/**
* Sets the value associated with the ThreadLocal object for the
* currently executing Thread. This overrides any existing value
* associated with the current Thread and does not call the
* initialValue() method, even if this is the first
* time this Thread accesses this ThreadLocal.
*/
public void set(Object value) {
Thread currentThread = Thread.currentThread();
Value v = new Value(value);
set(currentThread, v);
}
/**
* Sets the Value for this ThreadLocal for a particular Thread.
* It is synchronized so the get(Thread) method cannot
* simultaniously read the valueMap from another thread.
* Package local so InheritableThreadLocal can access it when a new child
* Thread inherits values from its parent Thread.
*/
synchronized final void set(Thread thread, Value value) {
valueMap.put(thread, value);
}
/**
* Called when get() is called and no state is associated
* with the currently executing Thread yet.
*
* The default implementation returns null.
*/
protected Object initialValue() {
return null;
}
}