0N/A/*
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 *
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 *
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 *
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.
0N/A *
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
2362N/A * questions.
0N/A */
0N/A
0N/A
0N/Apackage com.sun.jmx.snmp;
0N/A
0N/Aimport java.util.Stack;
0N/Aimport java.util.EmptyStackException;
0N/A
0N/A/**
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 *
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 * this:</p>
0N/A *
0N/A * <pre>
0N/A * ThreadContext oldContext = ThreadContext.push(myKey, myObject);
0N/A * // plus possibly further calls to ThreadContext.push...
0N/A * try {
0N/A * doSomeOperation();
0N/A * } finally {
0N/A * ThreadContext.restore(oldContext);
0N/A * }
0N/A * </pre>
0N/A *
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 * exception).</p>
0N/A *
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 *
0N/A * <p>A thread cannot read or modify the context of another thread.</p>
0N/A *
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 */
0N/Apublic class ThreadContext implements Cloneable {
0N/A
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
0N/A Because a null key indicates the sentinel, we reject attempts to
0N/A push context entries with a null key.
0N/A
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
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 null reference.
0N/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
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
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 private /*final*/ ThreadContext previous;
0N/A private /*final*/ String key;
0N/A private /*final*/ Object value;
0N/A
0N/A private ThreadContext(ThreadContext previous, String key, Object value) {
0N/A this.previous = previous;
0N/A this.key = key;
0N/A this.value = value;
0N/A }
0N/A
0N/A /**
0N/A * <p>Get the Object that was most recently pushed with the given key.</p>
0N/A *
0N/A * @param key the key of interest.
0N/A *
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 *
0N/A * @exception IllegalArgumentException if <code>key</code> is null.
0N/A */
0N/A public static Object get(String key) throws IllegalArgumentException {
0N/A ThreadContext context = contextContaining(key);
0N/A if (context == null)
0N/A return null;
0N/A else
0N/A return context.value;
0N/A }
0N/A
0N/A /**
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 * the stack.</p>
0N/A *
0N/A * @return true if the key exists in the stack.
0N/A *
0N/A * @exception IllegalArgumentException if <code>key</code> is null.
0N/A */
0N/A public static boolean contains(String key)
0N/A throws IllegalArgumentException {
0N/A return (contextContaining(key) != null);
0N/A }
0N/A
0N/A /**
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 *
0N/A * @exception IllegalArgumentException if <code>key</code> is null.
0N/A */
0N/A private static ThreadContext contextContaining(String key)
0N/A throws IllegalArgumentException {
0N/A if (key == null)
0N/A throw new IllegalArgumentException("null key");
0N/A for (ThreadContext context = getContext();
0N/A context != null;
0N/A context = context.previous) {
0N/A if (key.equals(context.key))
0N/A return context;
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 }
0N/A return null;
0N/A }
0N/A
0N/A// /**
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// *
0N/A// * @param key the key of interest.
0N/A// * @param value the new value to associate with that key.
0N/A// *
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// *
0N/A// * @exception IllegalArgumentException if <code>key</code> is null.
0N/A// */
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// return null;
0N/A// Object old = context.value;
0N/A// context.value = value;
0N/A// return old;
0N/A// }
0N/A
0N/A /**
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 * here.</p>
0N/A *
0N/A * @param key the key that will be used to find the object while it is
0N/A * on the stack.
0N/A * @param value the value to be associated with that key. It may be null.
0N/A *
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 *
0N/A * @exception IllegalArgumentException if <code>key</code> is null.
0N/A */
0N/A public static ThreadContext push(String key, Object value)
0N/A throws IllegalArgumentException {
0N/A if (key == null)
0N/A throw new IllegalArgumentException("null key");
0N/A
0N/A ThreadContext oldContext = getContext();
0N/A if (oldContext == null)
0N/A oldContext = new ThreadContext(null, null, null); // make sentinel
0N/A ThreadContext newContext = new ThreadContext(oldContext, key, value);
0N/A setContext(newContext);
0N/A return oldContext;
0N/A }
0N/A
0N/A /**
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 *
0N/A * @return a ThreadContext that represents the current context stack.
0N/A */
0N/A public static ThreadContext getThreadContext() {
0N/A return getContext();
0N/A }
0N/A
0N/A /**
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 *
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 *
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 */
0N/A public static void restore(ThreadContext oldContext)
0N/A throws NullPointerException, IllegalArgumentException {
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 if (oldContext == null)
0N/A throw new NullPointerException();
0N/A
0N/A /* Check that the restored context is in the stack. */
0N/A for (ThreadContext context = getContext();
0N/A context != oldContext;
0N/A context = context.previous) {
0N/A if (context == null) {
0N/A throw new IllegalArgumentException("Restored context is not " +
0N/A "contained in current " +
0N/A "context");
0N/A }
0N/A }
0N/A
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 if (oldContext.key == null)
0N/A oldContext = null;
0N/A
0N/A setContext(oldContext);
0N/A }
0N/A
0N/A /**
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 *
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 *
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 *
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 */
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 public void setInitialContext(ThreadContext context)
0N/A throws IllegalArgumentException {
0N/A /* The following test assumes that we discard sentinels when the
0N/A stack is empty. */
0N/A if (getContext() != null)
0N/A throw new IllegalArgumentException("previous context not empty");
0N/A setContext(context);
0N/A }
0N/A
0N/A private static ThreadContext getContext() {
0N/A return localContext.get();
0N/A }
0N/A
0N/A private static void setContext(ThreadContext context) {
0N/A localContext.set(context);
0N/A }
0N/A
0N/A private static ThreadLocal<ThreadContext> localContext =
0N/A new ThreadLocal<ThreadContext>();
0N/A}