Warning: The interface of this class is subject to change. - * Use at your own risk.
- * - *This class associates a context with each thread that - * references it. The context is a set of mappings between Strings - * and Objects. It is managed as a stack, typically with code like - * this:
- * - *
- * ThreadContext oldContext = ThreadContext.push(myKey, myObject);
- * // plus possibly further calls to ThreadContext.push...
- * try {
- * doSomeOperation();
- * } finally {
- * ThreadContext.restore(oldContext);
- * }
- *
- *
- * The try...finally block ensures that
- * the restore is done even if
- * doSomeOperation terminates abnormally (with an
- * exception).
A thread can consult its own context using
- * ThreadContext.get(myKey). The result is the
- * value that was most recently pushed with the given key.
A thread cannot read or modify the context of another thread.
- * - *This API is a Sun Microsystems internal API and is subject - * to change without notice.
- */ -public class ThreadContext implements Cloneable { - - /* The context of a thread is stored as a linked list. At the - head of the list is the value returned by localContext.get(). - At the tail of the list is a sentinel ThreadContext value with - "previous" and "key" both null. There is a different sentinel - object for each thread. - - Because a null key indicates the sentinel, we reject attempts to - push context entries with a null key. - - The reason for using a sentinel rather than just terminating - the list with a null reference is to protect against incorrect - or even malicious code. If you have a reference to the - sentinel value, you can erase the context stack. Only the - caller of the first "push" that put something on the stack can - get such a reference, so if that caller does not give this - reference away, no one else can erase the stack. - - If the restore method took a null reference to mean an empty - stack, anyone could erase the stack, since anyone can make a - null reference. - - When the stack is empty, we discard the sentinel object and - have localContext.get() return null. Then we recreate the - sentinel object on the first subsequent push. - - ThreadContext objects are immutable. As a consequence, you can - give a ThreadContext object to setInitialContext that is no - longer current. But the interface says this can be rejected, - in case we remove immutability later. */ - - /* We have to comment out "final" here because of a bug in the JDK1.1 - compiler. Uncomment it when we discard 1.1 compatibility. */ - private /*final*/ ThreadContext previous; - private /*final*/ String key; - private /*final*/ Object value; - - private ThreadContext(ThreadContext previous, String key, Object value) { - this.previous = previous; - this.key = key; - this.value = value; - } - - /** - *Get the Object that was most recently pushed with the given key.
- * - * @param key the key of interest. - * - * @return the last Object that was pushed (using - *push) with that key and not subsequently canceled
- * by a restore; or null if there is no such object.
- * A null return value may also indicate that the last Object
- * pushed was the value null. Use the
- * contains method to distinguish this case from the
- * case where there is no Object.
- *
- * @exception IllegalArgumentException if key is null.
- */
- public static Object get(String key) throws IllegalArgumentException {
- ThreadContext context = contextContaining(key);
- if (context == null)
- return null;
- else
- return context.value;
- }
-
- /**
- * Check whether a value with the given key exists in the stack.
- * This means that the push method was called with
- * this key and it was not cancelled by a subsequent
- * restore. This method is useful when the
- * get method returns null, to distinguish between
- * the case where the key exists in the stack but is associated
- * with a null value, and the case where the key does not exist in
- * the stack.
key is null.
- */
- public static boolean contains(String key)
- throws IllegalArgumentException {
- return (contextContaining(key) != null);
- }
-
- /**
- * Find the ThreadContext in the stack that contains the given key, - * or return null if there is none.
- * - * @exception IllegalArgumentException ifkey is null.
- */
- private static ThreadContext contextContaining(String key)
- throws IllegalArgumentException {
- if (key == null)
- throw new IllegalArgumentException("null key");
- for (ThreadContext context = getContext();
- context != null;
- context = context.previous) {
- if (key.equals(context.key))
- return context;
- /* Note that "context.key" may be null if "context" is the
- sentinel, so don't write "if (context.key.equals(key))"! */
- }
- return null;
- }
-
-// /**
-// * Change the value that was most recently associated with the given key
-// * in a push operation not cancelled by a subsequent
-// * restore. If there is no such association, nothing happens
-// * and the return value is null.
-// *
-// * @param key the key of interest.
-// * @param value the new value to associate with that key.
-// *
-// * @return the value that was previously associated with the key, or null
-// * if the key does not exist in the stack.
-// *
-// * @exception IllegalArgumentException if key is null.
-// */
-// public static Object set(String key, Object value)
-// throws IllegalArgumentException {
-// ThreadContext context = contextContaining(key);
-// if (context == null)
-// return null;
-// Object old = context.value;
-// context.value = value;
-// return old;
-// }
-
- /**
- * Push an object on the context stack with the given key.
- * This operation can subsequently be undone by calling
- * restore with the ThreadContext value returned
- * here.
restore to
- * restore the stack to its state before the push.
- *
- * @exception IllegalArgumentException if key is null.
- */
- public static ThreadContext push(String key, Object value)
- throws IllegalArgumentException {
- if (key == null)
- throw new IllegalArgumentException("null key");
-
- ThreadContext oldContext = getContext();
- if (oldContext == null)
- oldContext = new ThreadContext(null, null, null); // make sentinel
- ThreadContext newContext = new ThreadContext(oldContext, key, value);
- setContext(newContext);
- return oldContext;
- }
-
- /**
- * Return an object that can later be supplied to restore
- * to restore the context stack to its current state. The object can
- * also be given to setInitialContext.
Restore the context stack to an earlier state. This typically
- * undoes the effect of one or more push calls.
push operation.
- *
- * @exception NullPointerException if oldContext is null.
- * @exception IllegalArgumentException if oldContext
- * does not represent a context from this thread, or if that
- * context was undone by an earlier restore.
- */
- public static void restore(ThreadContext oldContext)
- throws NullPointerException, IllegalArgumentException {
- /* The following test is not strictly necessary in the code as it
- stands today, since the reference to "oldContext.key" would
- generate a NullPointerException anyway. But if someone
- didn't notice that during subsequent changes, they could
- accidentally permit restore(null) with the semantics of
- trashing the context stack. */
- if (oldContext == null)
- throw new NullPointerException();
-
- /* Check that the restored context is in the stack. */
- for (ThreadContext context = getContext();
- context != oldContext;
- context = context.previous) {
- if (context == null) {
- throw new IllegalArgumentException("Restored context is not " +
- "contained in current " +
- "context");
- }
- }
-
- /* Discard the sentinel if the stack is empty. This means that it
- is an error to call "restore" a second time with the
- ThreadContext value that means an empty stack. That's why we
- don't say that it is all right to restore the stack to the
- state it was already in. */
- if (oldContext.key == null)
- oldContext = null;
-
- setContext(oldContext);
- }
-
- /**
- * Set the initial context of the calling thread to a context obtained
- * from another thread. After this call, the calling thread will see
- * the same results from the get method as the thread
- * from which the context argument was obtained, at the
- * time it was obtained.
The context argument must be the result of an earlier
- * push or getThreadContext call. It is an
- * error (which may or may not be detected) if this context has been
- * undone by a restore.
The context stack of the calling thread must be empty before this
- * call, i.e., there must not have been a push not undone
- * by a subsequent restore.
context is no longer current in the
- * thread from which it was obtained.
- */
- /* We rely on the fact that ThreadContext objects are immutable.
- This means that we don't have to check that the "context"
- argument is valid. It necessarily represents the head of a
- valid chain of ThreadContext objects, even if the thread from
- which it was obtained has subsequently been set to a point
- later in that chain using "restore". */
- public void setInitialContext(ThreadContext context)
- throws IllegalArgumentException {
- /* The following test assumes that we discard sentinels when the
- stack is empty. */
- if (getContext() != null)
- throw new IllegalArgumentException("previous context not empty");
- setContext(context);
- }
-
- private static ThreadContext getContext() {
- return localContext.get();
- }
-
- private static void setContext(ThreadContext context) {
- localContext.set(context);
- }
-
- private static ThreadLocal