|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.sun.jdmk.ThreadContext
public class ThreadContext
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 |
---|
public static Object get(String key) throws IllegalArgumentException
Get the Object that was most recently pushed with the given key.
key
- the key of interest.
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.
IllegalArgumentException
- if key
is null.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.
IllegalArgumentException
- if key
is null.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.
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.
restore
to
restore the stack to its state before the push
.
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
.
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.
oldContext
- the state to return. This is usually the return
value of an earlier push
operation.
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) 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
.
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.
|
Open Source build 02 opendmk-1.0-b02 2007.10.01_19:17:46_MEST |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |