File	Doc	Category	Size	Date	Package
ThreadContext.java	API Doc	Java SE 5 API	12028	Fri Aug 26 14:55:04 BST 2005	com.sun.jmx.snmp

ThreadContext

• java.lang.Object

ThreadContext oldContext = ThreadContext.push(myKey, myObject);
// plus possibly further calls to ThreadContext.push...
try {
doSomeOperation();
} finally {
ThreadContext.restore(oldContext);
}

Fields Summary
private ThreadContext	previous
private String	key
private Object	value
private static ThreadLocal	localContext

Constructors Summary
private ThreadContext(ThreadContext previous, String key, Object value) this.previous = previous; this.key = key; this.value = value;

Methods Summary
public static boolean	contains(java.lang.String key) 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. return true if the key exists in the stack. exception IllegalArgumentException if key is null. return (contextContaining(key) != null);
private static com.sun.jmx.snmp.ThreadContext	contextContaining(java.lang.String key) Find the ThreadContext in the stack that contains the given key, or return null if there is none. exception IllegalArgumentException if key is null. 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;
public static java.lang.Object	get(java.lang.String key) 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 cancelled 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. ThreadContext context = contextContaining(key); if (context == null) return null; else return context.value;
private static com.sun.jmx.snmp.ThreadContext	getContext() return (ThreadContext) localContext.get();
public static com.sun.jmx.snmp.ThreadContext	getThreadContext() 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. return a ThreadContext that represents the current context stack. return getContext();
public static com.sun.jmx.snmp.ThreadContext	push(java.lang.String key, java.lang.Object value) 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. 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 restore to restore the stack to its state before the push. exception IllegalArgumentException if key is null. 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;
public static void	restore(com.sun.jmx.snmp.ThreadContext oldContext) Restore the context stack to an earlier state. This typically undoes the effect of one or more push calls. param oldContext the state to return. This is usually the return value of an earlier 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. /* 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);
private static void	setContext(com.sun.jmx.snmp.ThreadContext context) localContext.set(context);
public void	setInitialContext(com.sun.jmx.snmp.ThreadContext context) 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. exception 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. /* 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);