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 package org.apache.shiro.util;
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 * @since 1.0
42 */
43 public interface ThreadState {
44
45 /**
46 * Binds any state that should be made accessible during a thread's execution. This should typically always
47 * be called in a {@code try/finally} block paired with the {@link #restore} call to guarantee that the thread
48 * is cleanly restored back to its original state. For example:
49 * <pre>
50 * ThreadState state = //acquire or instantiate as necessary
51 * <b>try {
52 * state.bind();
53 * doSomething(); //execute any logic downstream logic that might need to access the state
54 * } </b> finally {
55 * state.restore();
56 * }
57 * </pre>
58 */
59 void bind();
60
61 /**
62 * Restores a thread to its state before bind {@link #bind bind} was invoked. This should typically always be
63 * called in a {@code finally} block to guarantee that the thread is cleanly restored back to its original state
64 * before {@link #bind bind}'s bind was called. For example:
65 * <pre>
66 * ThreadState state = //acquire or instantiate as necessary
67 * try {
68 * state.bind();
69 * doSomething(); //execute any logic downstream logic that might need to access the state
70 * } <b>finally {
71 * state.restore();
72 * }</b>
73 * </pre>
74 */
75 void restore();
76
77 /**
78 * Completely clears/removes the {@code ThreadContext} state. Typically this method should
79 * only be called in special cases - it is more 'correct' to {@link #restore restore} a thread to its previous
80 * state than to clear it entirely.
81 */
82 void clear();
83
84 }