1 /*
2 * Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26
27 package com.sun.jmx.snmp;
28
29 import java.util.Stack;
30 import java.util.EmptyStackException;
31
32 /**
33 * <p><b>Warning: The interface of this class is subject to change.
34 * Use at your own risk.</b></p>
35 *
36 * <p>This class associates a context with each thread that
37 * references it. The context is a set of mappings between Strings
38 * and Objects. It is managed as a stack, typically with code like
39 * this:</p>
40 *
41 * <pre>
42 * ThreadContext oldContext = ThreadContext.push(myKey, myObject);
43 * // plus possibly further calls to ThreadContext.push...
44 * try {
45 * doSomeOperation();
46 * } finally {
47 * ThreadContext.restore(oldContext);
48 * }
49 * </pre>
50 *
51 * <p>The <code>try</code>...<code>finally</code> block ensures that
52 * the <code>restore</code> is done even if
53 * <code>doSomeOperation</code> terminates abnormally (with an
54 * exception).</p>
55 *
56 * <p>A thread can consult its own context using
57 * <code>ThreadContext.get(myKey)</code>. The result is the
58 * value that was most recently pushed with the given key.</p>
59 *
60 * <p>A thread cannot read or modify the context of another thread.</p>
61 *
62 * <p><b>This API is a Sun Microsystems internal API and is subject
63 * to change without notice.</b></p>
64 */
65 public class ThreadContext implements Cloneable {
66
67 /* The context of a thread is stored as a linked list. At the
68 head of the list is the value returned by localContext.get().
69 At the tail of the list is a sentinel ThreadContext value with
70 "previous" and "key" both null. There is a different sentinel
71 object for each thread.
72
73 Because a null key indicates the sentinel, we reject attempts to
74 push context entries with a null key.
75
76 The reason for using a sentinel rather than just terminating
77 the list with a null reference is to protect against incorrect
78 or even malicious code. If you have a reference to the
79 sentinel value, you can erase the context stack. Only the
80 caller of the first "push" that put something on the stack can
81 get such a reference, so if that caller does not give this
82 reference away, no one else can erase the stack.
83
84 If the restore method took a null reference to mean an empty
85 stack, anyone could erase the stack, since anyone can make a
86 null reference.
87
88 When the stack is empty, we discard the sentinel object and
89 have localContext.get() return null. Then we recreate the
90 sentinel object on the first subsequent push.
91
92 ThreadContext objects are immutable. As a consequence, you can
93 give a ThreadContext object to setInitialContext that is no
94 longer current. But the interface says this can be rejected,
95 in case we remove immutability later. */
96
97 /* We have to comment out "final" here because of a bug in the JDK1.1
98 compiler. Uncomment it when we discard 1.1 compatibility. */
99 private /*final*/ ThreadContext previous;
100 private /*final*/ String key;
101 private /*final*/ Object value;
102
103 private ThreadContext(ThreadContext previous, String key, Object value) {
104 this.previous = previous;
105 this.key = key;
106 this.value = value;
107 }
108
109 /**
110 * <p>Get the Object that was most recently pushed with the given key.</p>
111 *
112 * @param key the key of interest.
113 *
114 * @return the last Object that was pushed (using
115 * <code>push</code>) with that key and not subsequently canceled
116 * by a <code>restore</code>; or null if there is no such object.
117 * A null return value may also indicate that the last Object
118 * pushed was the value <code>null</code>. Use the
119 * <code>contains</code> method to distinguish this case from the
120 * case where there is no Object.
121 *
122 * @exception IllegalArgumentException if <code>key</code> is null.
123 */
124 public static Object get(String key) throws IllegalArgumentException {
125 ThreadContext context = contextContaining(key);
126 if (context == null)
127 return null;
128 else
129 return context.value;
130 }
131
132 /**
133 * <p>Check whether a value with the given key exists in the stack.
134 * This means that the <code>push</code> method was called with
135 * this key and it was not cancelled by a subsequent
136 * <code>restore</code>. This method is useful when the
137 * <code>get</code> method returns null, to distinguish between
138 * the case where the key exists in the stack but is associated
139 * with a null value, and the case where the key does not exist in
140 * the stack.</p>
141 *
142 * @return true if the key exists in the stack.
143 *
144 * @exception IllegalArgumentException if <code>key</code> is null.
145 */
146 public static boolean contains(String key)
147 throws IllegalArgumentException {
148 return (contextContaining(key) != null);
149 }
150
151 /**
152 * <p>Find the ThreadContext in the stack that contains the given key,
153 * or return null if there is none.</p>
154 *
155 * @exception IllegalArgumentException if <code>key</code> is null.
156 */
157 private static ThreadContext contextContaining(String key)
158 throws IllegalArgumentException {
159 if (key == null)
160 throw new IllegalArgumentException("null key");
161 for (ThreadContext context = getContext();
162 context != null;
163 context = context.previous) {
164 if (key.equals(context.key))
165 return context;
166 /* Note that "context.key" may be null if "context" is the
167 sentinel, so don't write "if (context.key.equals(key))"! */
168 }
169 return null;
170 }
171
172 // /**
173 // * Change the value that was most recently associated with the given key
174 // * in a <code>push</code> operation not cancelled by a subsequent
175 // * <code>restore</code>. If there is no such association, nothing happens
176 // * and the return value is null.
177 // *
178 // * @param key the key of interest.
179 // * @param value the new value to associate with that key.
180 // *
181 // * @return the value that was previously associated with the key, or null
182 // * if the key does not exist in the stack.
183 // *
184 // * @exception IllegalArgumentException if <code>key</code> is null.
185 // */
186 // public static Object set(String key, Object value)
187 // throws IllegalArgumentException {
188 // ThreadContext context = contextContaining(key);
189 // if (context == null)
190 // return null;
191 // Object old = context.value;
192 // context.value = value;
193 // return old;
194 // }
195
196 /**
197 * <p>Push an object on the context stack with the given key.
198 * This operation can subsequently be undone by calling
199 * <code>restore</code> with the ThreadContext value returned
200 * here.</p>
201 *
202 * @param key the key that will be used to find the object while it is
203 * on the stack.
204 * @param value the value to be associated with that key. It may be null.
205 *
206 * @return a ThreadContext that can be given to <code>restore</code> to
207 * restore the stack to its state before the <code>push</code>.
208 *
209 * @exception IllegalArgumentException if <code>key</code> is null.
210 */
211 public static ThreadContext push(String key, Object value)
212 throws IllegalArgumentException {
213 if (key == null)
214 throw new IllegalArgumentException("null key");
215
216 ThreadContext oldContext = getContext();
217 if (oldContext == null)
218 oldContext = new ThreadContext(null, null, null); // make sentinel
219 ThreadContext newContext = new ThreadContext(oldContext, key, value);
220 setContext(newContext);
221 return oldContext;
222 }
223
224 /**
225 * <p>Return an object that can later be supplied to <code>restore</code>
226 * to restore the context stack to its current state. The object can
227 * also be given to <code>setInitialContext</code>.</p>
228 *
229 * @return a ThreadContext that represents the current context stack.
230 */
231 public static ThreadContext getThreadContext() {
232 return getContext();
233 }
234
235 /**
236 * <p>Restore the context stack to an earlier state. This typically
237 * undoes the effect of one or more <code>push</code> calls.</p>
238 *
239 * @param oldContext the state to return. This is usually the return
240 * value of an earlier <code>push</code> operation.
241 *
242 * @exception NullPointerException if <code>oldContext</code> is null.
243 * @exception IllegalArgumentException if <code>oldContext</code>
244 * does not represent a context from this thread, or if that
245 * context was undone by an earlier <code>restore</code>.
246 */
247 public static void restore(ThreadContext oldContext)
248 throws NullPointerException, IllegalArgumentException {
249 /* The following test is not strictly necessary in the code as it
250 stands today, since the reference to "oldContext.key" would
251 generate a NullPointerException anyway. But if someone
252 didn't notice that during subsequent changes, they could
253 accidentally permit restore(null) with the semantics of
254 trashing the context stack. */
255 if (oldContext == null)
256 throw new NullPointerException();
257
258 /* Check that the restored context is in the stack. */
259 for (ThreadContext context = getContext();
260 context != oldContext;
261 context = context.previous) {
262 if (context == null) {
263 throw new IllegalArgumentException("Restored context is not " +
264 "contained in current " +
265 "context");
266 }
267 }
268
269 /* Discard the sentinel if the stack is empty. This means that it
270 is an error to call "restore" a second time with the
271 ThreadContext value that means an empty stack. That's why we
272 don't say that it is all right to restore the stack to the
273 state it was already in. */
274 if (oldContext.key == null)
275 oldContext = null;
276
277 setContext(oldContext);
278 }
279
280 /**
281 * <p>Set the initial context of the calling thread to a context obtained
282 * from another thread. After this call, the calling thread will see
283 * the same results from the <code>get</code> method as the thread
284 * from which the <code>context</code> argument was obtained, at the
285 * time it was obtained.</p>
286 *
287 * <p>The <code>context</code> argument must be the result of an earlier
288 * <code>push</code> or <code>getThreadContext</code> call. It is an
289 * error (which may or may not be detected) if this context has been
290 * undone by a <code>restore</code>.</p>
291 *
292 * <p>The context stack of the calling thread must be empty before this
293 * call, i.e., there must not have been a <code>push</code> not undone
294 * by a subsequent <code>restore</code>.</p>
295 *
296 * @exception IllegalArgumentException if the context stack was
297 * not empty before the call. An implementation may also throw this
298 * exception if <code>context</code> is no longer current in the
299 * thread from which it was obtained.
300 */
301 /* We rely on the fact that ThreadContext objects are immutable.
302 This means that we don't have to check that the "context"
303 argument is valid. It necessarily represents the head of a
304 valid chain of ThreadContext objects, even if the thread from
305 which it was obtained has subsequently been set to a point
306 later in that chain using "restore". */
307 public void setInitialContext(ThreadContext context)
308 throws IllegalArgumentException {
309 /* The following test assumes that we discard sentinels when the
310 stack is empty. */
311 if (getContext() != null)
312 throw new IllegalArgumentException("previous context not empty");
313 setContext(context);
314 }
315
316 private static ThreadContext getContext() {
317 return localContext.get();
318 }
319
320 private static void setContext(ThreadContext context) {
321 localContext.set(context);
322 }
323
324 private static ThreadLocal<ThreadContext> localContext =
325 new ThreadLocal<ThreadContext>();
326 }