001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.shiro.util;
020    
021    /**
022     * A {@code ThreadState} instance manages any state that might need to be bound and/or restored during a thread's
023     * execution.
024     * <h3>Usage</h3>
025     * Calling {@link #bind bind()} will place state on the currently executing thread to be accessed later during
026     * the thread's execution.
027     * <h4>WARNING</h4>
028     * After the thread is finished executing, or if an exception occurs, any previous state <b>MUST</b> be
029     * {@link #restore restored} to guarantee all threads stay clean in any thread-pooled environment.  This should always
030     * be done in a {@code try/finally} block:
031     * <pre>
032     * ThreadState state = //acquire or instantiate as necessary
033     * try {
034     *     state.bind();
035     *     doSomething(); //execute any logic downstream logic that might need to access the state
036     * } <b>finally {
037     *     state.restore();
038     * }</b>
039     * </pre>
040     *
041     * @since 1.0
042     */
043    public interface ThreadState {
044    
045        /**
046         * Binds any state that should be made accessible during a thread's execution.  This should typically always
047         * be called in a {@code try/finally} block paired with the {@link #restore} call to guarantee that the thread
048         * is cleanly restored back to its original state.  For example:
049         * <pre>
050         * ThreadState state = //acquire or instantiate as necessary
051         * <b>try {
052         *     state.bind();
053         *     doSomething(); //execute any logic downstream logic that might need to access the state
054         * } </b> finally {
055         *     state.restore();
056         * }
057         * </pre>
058         */
059        void bind();
060    
061        /**
062         * Restores a thread to its state before bind {@link #bind bind} was invoked.  This should typically always be
063         * called in a {@code finally} block to guarantee that the thread is cleanly restored back to its original state
064         * before {@link #bind bind}'s bind was called.  For example:
065         * <pre>
066         * ThreadState state = //acquire or instantiate as necessary
067         * try {
068         *     state.bind();
069         *     doSomething(); //execute any logic downstream logic that might need to access the state
070         * } <b>finally {
071         *     state.restore();
072         * }</b>
073         * </pre>
074         */
075        void restore();
076    
077        /**
078         * Completely clears/removes the {@code ThreadContext} state.  Typically this method should
079         * only be called in special cases - it is more 'correct' to {@link #restore restore} a thread to its previous
080         * state than to clear it entirely.
081         */
082        void clear();
083    
084    }