Coverage Report

Coverage Report - org.apache.shiro.util.ThreadState

Classes in this File

 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */
 package org.apache.shiro.util;
 
 /**
  * A {@code ThreadState} instance manages any state that might need to be bound and/or restored during a thread's
  * execution.
  * <h3>Usage</h3>
  * Calling {@link #bind bind()} will place state on the currently executing thread to be accessed later during
  * the thread's execution.
  * <h4>WARNING</h4>
  * After the thread is finished executing, or if an exception occurs, any previous state <b>MUST</b> be
  * {@link #restore restored} to guarantee all threads stay clean in any thread-pooled environment.  This should always
  * be done in a {@code try/finally} block:
  * <pre>
  * ThreadState state = //acquire or instantiate as necessary
  * try {
  *     state.bind();
  *     doSomething(); //execute any logic downstream logic that might need to access the state
  * } <b>finally {
  *     state.restore();
  * }</b>
  * </pre>
  *
  * @since 1.0
  */
 public interface ThreadState {
 
     /**
      * Binds any state that should be made accessible during a thread's execution.  This should typically always
      * be called in a {@code try/finally} block paired with the {@link #restore} call to guarantee that the thread
      * is cleanly restored back to its original state.  For example:
      * <pre>
      * ThreadState state = //acquire or instantiate as necessary
      * <b>try {
      *     state.bind();
      *     doSomething(); //execute any logic downstream logic that might need to access the state
      * } </b> finally {
      *     state.restore();
      * }
      * </pre>
      */
     void bind();
 
     /**
      * Restores a thread to its state before bind {@link #bind bind} was invoked.  This should typically always be
      * called in a {@code finally} block to guarantee that the thread is cleanly restored back to its original state
      * before {@link #bind bind}'s bind was called.  For example:
      * <pre>
      * ThreadState state = //acquire or instantiate as necessary
      * try {
      *     state.bind();
      *     doSomething(); //execute any logic downstream logic that might need to access the state
      * } <b>finally {
      *     state.restore();
      * }</b>
      * </pre>
      */
     void restore();
 
     /**
      * Completely clears/removes the {@code ThreadContext} state.  Typically this method should
      * only be called in special cases - it is more 'correct' to {@link #restore restore} a thread to its previous
      * state than to clear it entirely.
      */
     void clear();
 
 }

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		}