com.sun.jdmk
Class ThreadContext

java.lang.Object
  com.sun.jdmk.ThreadContext

All Implemented Interfaces:

Cloneable

public class ThreadContext
extends Object
implements Cloneable

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.

Method Summary

static boolean	contains(String key) Check whether a value with the given key exists in the stack.
static Object	get(String key) Get the Object that was most recently pushed with the given key.
static ThreadContext	getThreadContext() Return an object that can later be supplied to restore to restore the context stack to its current state.
static ThreadContext	push(String key, Object value) Push an object on the context stack with the given key.
static void	restore(ThreadContext oldContext) Restore the context stack to an earlier state.
void	setInitialContext(ThreadContext context) Set the initial context of the calling thread to a context obtained from another thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

get

public static Object get(String key)
                  throws IllegalArgumentException

Get the Object that was most recently pushed with the given key.

Parameters:

key - the key of interest.

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.

Throws:

IllegalArgumentException - if key is null.

contains

public static boolean contains(String key)
                        throws IllegalArgumentException

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 canceled 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.

Returns:

true if the key exists in the stack.

Throws:

IllegalArgumentException - if key is null.

push

public static ThreadContext push(String key,
                                 Object value)
                          throws IllegalArgumentException

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.

Parameters:

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.

Returns:

a ThreadContext that can be given to restore to restore the stack to its state before the push.

Throws:

IllegalArgumentException - if key is null.

getThreadContext

public static 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.

Returns:

a ThreadContext that represents the current context stack.

restore

public static void restore(ThreadContext oldContext)
                    throws NullPointerException,
                           IllegalArgumentException

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

Parameters:

oldContext - the state to return. This is usually the return value of an earlier push operation.

Throws:

NullPointerException - if oldContext is null.

IllegalArgumentException - if oldContext does not represent a context from this thread, or if that context was undone by an earlier restore.

setInitialContext

public void setInitialContext(ThreadContext context)
                       throws IllegalArgumentException

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.