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 */
019package 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 */
043public 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}