https://openjdk.java.net/ 
/*
 * Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */


package com.sun.jmx.snmp;

import java.util.Stack;
import java.util.EmptyStackException;


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.


/**
 * <p><b>Warning: The interface of this class is subject to change.
 * Use at your own risk.</b></p>
 *
 * <p>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:</p>
 *
 * <pre>
 * ThreadContext oldContext = ThreadContext.push(myKey, myObject);
 * // plus possibly further calls to ThreadContext.push...
 * try {
 *      doSomeOperation();
 * } finally {
 *      ThreadContext.restore(oldContext);
 * }
 * </pre>
 *
 * <p>The <code>try</code>...<code>finally</code> block ensures that
 * the <code>restore</code> is done even if
 * <code>doSomeOperation</code> terminates abnormally (with an
 * exception).</p>
 *
 * <p>A thread can consult its own context using
 * <code>ThreadContext.get(myKey)</code>.  The result is the
 * value that was most recently pushed with the given key.</p>
 *
 * <p>A thread cannot read or modify the context of another thread.</p>
 *
 * <p><b>This API is a Sun Microsystems internal API  and is subject
 * to change without notice.</b></p>
 */
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.


Params:
  • key – the key of interest.
Throws:
Returns: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.
/**
     * <p>Get the Object that was most recently pushed with the given key.</p>
     *
     * @param key the key of interest.
     *
     * @return the last Object that was pushed (using
     * <code>push</code>) with that key and not subsequently canceled
     * by a <code>restore</code>; or null if there is no such object.
     * A null return value may also indicate that the last Object
     * pushed was the value <code>null</code>.  Use the
     * <code>contains</code> method to distinguish this case from the
     * case where there is no Object.
     *
     * @exception IllegalArgumentException if <code>key</code> 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.


Throws:
Returns:true if the key exists in the stack.
/**
     * <p>Check whether a value with the given key exists in the stack.
     * This means that the <code>push</code> method was called with
     * this key and it was not cancelled by a subsequent
     * <code>restore</code>.  This method is useful when the
     * <code>get</code> 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.</p>
     *
     * @return true if the key exists in the stack.
     *
     * @exception IllegalArgumentException if <code>key</code> 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.


Throws:
  • IllegalArgumentException – if key is null.
/**
     * <p>Find the ThreadContext in the stack that contains the given key,
     * or return null if there is none.</p>
     *
     * @exception IllegalArgumentException if <code>key</code> 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 <code>push</code> operation not cancelled by a subsequent
//   * <code>restore</code>.  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 <code>key</code> 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.


Params:
  • key – the key that will be used to find the object while it is
on the stack.
  • value – the value to be associated with that key.  It may be null.
Throws:
Returns:a ThreadContext that can be given to restore to
restore the stack to its state before the push.
/**
     * <p>Push an object on the context stack with the given key.
     * This operation can subsequently be undone by calling
     * <code>restore</code> with the ThreadContext value returned
     * here.</p>
     *
     * @param key the key that will be used to find the object while it is
     * on the stack.
     * @param value the value to be associated with that key.  It may be null.
     *
     * @return a ThreadContext that can be given to <code>restore</code> to
     * restore the stack to its state before the <code>push</code>.
     *
     * @exception IllegalArgumentException if <code>key</code> 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.


Returns:a ThreadContext that represents the current context stack.
/**
     * <p>Return an object that can later be supplied to <code>restore</code>
     * to restore the context stack to its current state.  The object can
     * also be given to <code>setInitialContext</code>.</p>
     *
     * @return a ThreadContext that represents the current context stack.
     */
    public static ThreadContext getThreadContext() {
        return getContext();
    }

    
Restore the context stack to an earlier state.  This typically
undoes the effect of one or more push calls.


Params:
  • oldContext – the state to return.  This is usually the return
value of an earlier push operation.
Throws:
/**
     * <p>Restore the context stack to an earlier state.  This typically
     * undoes the effect of one or more <code>push</code> calls.</p>
     *
     * @param oldContext the state to return.  This is usually the return
     * value of an earlier <code>push</code> operation.
     *
     * @exception NullPointerException if <code>oldContext</code> is null.
     * @exception IllegalArgumentException if <code>oldContext</code>
     * does not represent a context from this thread, or if that
     * context was undone by an earlier <code>restore</code>.
     */
    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.


Throws:
  • IllegalArgumentException – if the context stack was
not empty before the call.  An implementation may also throw this
exception if context is no longer current in the
thread from which it was obtained.
/**
     * <p>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 <code>get</code> method as the thread
     * from which the <code>context</code> argument was obtained, at the
     * time it was obtained.</p>
     *
     * <p>The <code>context</code> argument must be the result of an earlier
     * <code>push</code> or <code>getThreadContext</code> call.  It is an
     * error (which may or may not be detected) if this context has been
     * undone by a <code>restore</code>.</p>
     *
     * <p>The context stack of the calling thread must be empty before this
     * call, i.e., there must not have been a <code>push</code> not undone
     * by a subsequent <code>restore</code>.</p>
     *
     * @exception IllegalArgumentException if the context stack was
     * not empty before the call.  An implementation may also throw this
     * exception if <code>context</code> 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<ThreadContext> localContext =
            new ThreadLocal<ThreadContext>();
}