History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/com/sun/jmx/snmp/ThreadContext.java (1 of 18352 files). Show all

Unified · Split

java/pkg/com/sun/jmx/snmp/ThreadContext.java+326−0
@@ -0,0 +1,326 @@
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+}