2362N/A * Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * <p><b>Warning: The interface of this class is subject to change. 0N/A * Use at your own risk.</b></p> 0N/A * <p>This class associates a context with each thread that 0N/A * references it. The context is a set of mappings between Strings 0N/A * and Objects. It is managed as a stack, typically with code like 0N/A * ThreadContext oldContext = ThreadContext.push(myKey, myObject); 0N/A * // plus possibly further calls to ThreadContext.push... 0N/A * doSomeOperation(); 0N/A * ThreadContext.restore(oldContext); 0N/A * <p>The <code>try</code>...<code>finally</code> block ensures that 0N/A * the <code>restore</code> is done even if 0N/A * <code>doSomeOperation</code> terminates abnormally (with an 0N/A * <p>A thread can consult its own context using 0N/A * <code>ThreadContext.get(myKey)</code>. The result is the 0N/A * value that was most recently pushed with the given key.</p> 0N/A * <p>A thread cannot read or modify the context of another thread.</p> 0N/A * <p><b>This API is a Sun Microsystems internal API and is subject 0N/A * to change without notice.</b></p> 0N/A /* The context of a thread is stored as a linked list. At the 0N/A head of the list is the value returned by localContext.get(). 0N/A At the tail of the list is a sentinel ThreadContext value with 0N/A "previous" and "key" both null. There is a different sentinel 0N/A object for each thread. 0N/A Because a null key indicates the sentinel, we reject attempts to 0N/A push context entries with a null key. 0N/A The reason for using a sentinel rather than just terminating 0N/A the list with a null reference is to protect against incorrect 0N/A or even malicious code. If you have a reference to the 0N/A sentinel value, you can erase the context stack. Only the 0N/A caller of the first "push" that put something on the stack can 0N/A get such a reference, so if that caller does not give this 0N/A reference away, no one else can erase the stack. 0N/A If the restore method took a null reference to mean an empty 0N/A stack, anyone could erase the stack, since anyone can make a 0N/A When the stack is empty, we discard the sentinel object and 0N/A have localContext.get() return null. Then we recreate the 0N/A sentinel object on the first subsequent push. 0N/A ThreadContext objects are immutable. As a consequence, you can 0N/A give a ThreadContext object to setInitialContext that is no 0N/A longer current. But the interface says this can be rejected, 0N/A in case we remove immutability later. */ 0N/A /* We have to comment out "final" here because of a bug in the JDK1.1 0N/A compiler. Uncomment it when we discard 1.1 compatibility. */ 0N/A * <p>Get the Object that was most recently pushed with the given key.</p> 0N/A * @param key the key of interest. 0N/A * @return the last Object that was pushed (using 0N/A * <code>push</code>) with that key and not subsequently canceled 0N/A * by a <code>restore</code>; or null if there is no such object. 0N/A * A null return value may also indicate that the last Object 0N/A * pushed was the value <code>null</code>. Use the 0N/A * <code>contains</code> method to distinguish this case from the 0N/A * case where there is no Object. 0N/A * @exception IllegalArgumentException if <code>key</code> is null. 0N/A * <p>Check whether a value with the given key exists in the stack. 0N/A * This means that the <code>push</code> method was called with 0N/A * this key and it was not cancelled by a subsequent 0N/A * <code>restore</code>. This method is useful when the 0N/A * <code>get</code> method returns null, to distinguish between 0N/A * the case where the key exists in the stack but is associated 0N/A * with a null value, and the case where the key does not exist in 0N/A * @return true if the key exists in the stack. 0N/A * @exception IllegalArgumentException if <code>key</code> is null. 0N/A * <p>Find the ThreadContext in the stack that contains the given key, 0N/A * or return null if there is none.</p> 0N/A * @exception IllegalArgumentException if <code>key</code> is null. 0N/A /* Note that "context.key" may be null if "context" is the 0N/A sentinel, so don't write "if (context.key.equals(key))"! */ 0N/A// * Change the value that was most recently associated with the given key 0N/A// * in a <code>push</code> operation not cancelled by a subsequent 0N/A// * <code>restore</code>. If there is no such association, nothing happens 0N/A// * and the return value is null. 0N/A// * @param key the key of interest. 0N/A// * @param value the new value to associate with that key. 0N/A// * @return the value that was previously associated with the key, or null 0N/A// * if the key does not exist in the stack. 0N/A// * @exception IllegalArgumentException if <code>key</code> is null. 0N/A// public static Object set(String key, Object value) 0N/A// throws IllegalArgumentException { 0N/A// ThreadContext context = contextContaining(key); 0N/A// if (context == null) 0N/A// Object old = context.value; 0N/A// context.value = value; 0N/A * <p>Push an object on the context stack with the given key. 0N/A * This operation can subsequently be undone by calling 0N/A * <code>restore</code> with the ThreadContext value returned 0N/A * @param key the key that will be used to find the object while it is 0N/A * @param value the value to be associated with that key. It may be null. 0N/A * @return a ThreadContext that can be given to <code>restore</code> to 0N/A * restore the stack to its state before the <code>push</code>. 0N/A * @exception IllegalArgumentException if <code>key</code> is null. 0N/A * <p>Return an object that can later be supplied to <code>restore</code> 0N/A * to restore the context stack to its current state. The object can 0N/A * also be given to <code>setInitialContext</code>.</p> 0N/A * @return a ThreadContext that represents the current context stack. 0N/A * <p>Restore the context stack to an earlier state. This typically 0N/A * undoes the effect of one or more <code>push</code> calls.</p> 0N/A * @param oldContext the state to return. This is usually the return 0N/A * value of an earlier <code>push</code> operation. 0N/A * @exception NullPointerException if <code>oldContext</code> is null. 0N/A * @exception IllegalArgumentException if <code>oldContext</code> 0N/A * does not represent a context from this thread, or if that 0N/A * context was undone by an earlier <code>restore</code>. 0N/A /* The following test is not strictly necessary in the code as it 0N/A stands today, since the reference to "oldContext.key" would 0N/A generate a NullPointerException anyway. But if someone 0N/A didn't notice that during subsequent changes, they could 0N/A accidentally permit restore(null) with the semantics of 0N/A trashing the context stack. */ 0N/A /* Check that the restored context is in the stack. */ 0N/A "contained in current " +
0N/A /* Discard the sentinel if the stack is empty. This means that it 0N/A is an error to call "restore" a second time with the 0N/A ThreadContext value that means an empty stack. That's why we 0N/A don't say that it is all right to restore the stack to the 0N/A state it was already in. */ 0N/A * <p>Set the initial context of the calling thread to a context obtained 0N/A * from another thread. After this call, the calling thread will see 0N/A * the same results from the <code>get</code> method as the thread 0N/A * from which the <code>context</code> argument was obtained, at the 0N/A * time it was obtained.</p> 0N/A * <p>The <code>context</code> argument must be the result of an earlier 0N/A * <code>push</code> or <code>getThreadContext</code> call. It is an 0N/A * error (which may or may not be detected) if this context has been 0N/A * undone by a <code>restore</code>.</p> 0N/A * <p>The context stack of the calling thread must be empty before this 0N/A * call, i.e., there must not have been a <code>push</code> not undone 0N/A * by a subsequent <code>restore</code>.</p> 0N/A * @exception IllegalArgumentException if the context stack was 0N/A * not empty before the call. An implementation may also throw this 0N/A * exception if <code>context</code> is no longer current in the 0N/A * thread from which it was obtained. 0N/A /* We rely on the fact that ThreadContext objects are immutable. 0N/A This means that we don't have to check that the "context" 0N/A argument is valid. It necessarily represents the head of a 0N/A valid chain of ThreadContext objects, even if the thread from 0N/A which it was obtained has subsequently been set to a point 0N/A later in that chain using "restore". */ 0N/A /* The following test assumes that we discard sentinels when the