public class

ThreadContext

extends Object
implements Cloneable
java.lang.Object
   ↳ com.sun.jmx.snmp.ThreadContext

Class Overview

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.

Summary

Public Methods
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.

[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public static boolean contains (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.

Returns
  • true if the key exists in the stack.
Throws
IllegalArgumentException if key is null.

public static Object get (String key)

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.

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.

public static ThreadContext push (String key, 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.

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.

public static void restore (ThreadContext oldContext)

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.

public void setInitialContext (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.

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.