hunt.shiro.util.ThreadState source code

1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements.  See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership.  The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License.  You may obtain a copy of the License at
9  *
10  *     http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing,
13  * software distributed under the License is distributed on an
14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15  * KIND, either express or implied.  See the License for the
16  * specific language governing permissions and limitations
17  * under the License.
18  */
19 module hunt.shiro.util.ThreadState;
20 
21 /**
22  * A {@code ThreadState} instance manages any state that might need to be bound and/or restored during a thread's
23  * execution.
24  * <h3>Usage</h3>
25  * Calling {@link #bind bind()} will place state on the currently executing thread to be accessed later during
26  * the thread's execution.
27  * <h4>WARNING</h4>
28  * After the thread is finished executing, or if an exception occurs, any previous state <b>MUST</b> be
29  * {@link #restore restored} to guarantee all threads stay clean in any thread-pooled environment.  This should always
30  * be done in a {@code try/finally} block:
31  * <pre>
32  * ThreadState state = //acquire or instantiate as necessary
33  * try {
34  *     state.bind();
35  *     doSomething(); //execute any logic downstream logic that might need to access the state
36  * } <b>finally {
37  *     state.restore();
38  * }</b>
39  * </pre>
40  *
41  */
42 interface ThreadState {
43 
44     /**
45      * Binds any state that should be made accessible during a thread's execution.  This should typically always
46      * be called in a {@code try/finally} block paired with the {@link #restore} call to guarantee that the thread
47      * is cleanly restored back to its original state.  For example:
48      * <pre>
49      * ThreadState state = //acquire or instantiate as necessary
50      * <b>try {
51      *     state.bind();
52      *     doSomething(); //execute any logic downstream logic that might need to access the state
53      * } </b> finally {
54      *     state.restore();
55      * }
56      * </pre>
57      */
58     void bind();
59 
60     /**
61      * Restores a thread to its state before bind {@link #bind bind} was invoked.  This should typically always be
62      * called in a {@code finally} block to guarantee that the thread is cleanly restored back to its original state
63      * before {@link #bind bind}'s bind was called.  For example:
64      * <pre>
65      * ThreadState state = //acquire or instantiate as necessary
66      * try {
67      *     state.bind();
68      *     doSomething(); //execute any logic downstream logic that might need to access the state
69      * } <b>finally {
70      *     state.restore();
71      * }</b>
72      * </pre>
73      */
74     void restore();
75 
76     /**
77      * Completely clears/removes the {@code ThreadContext} state.  Typically this method should
78      * only be called in special cases - it is more 'correct' to {@link #restore restore} a thread to its previous
79      * state than to clear it entirely.
80      */
81     void clear();
82 
83 }