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.subject.support;
020    
021    import org.apache.shiro.subject.Subject;
022    import org.apache.shiro.util.ThreadState;
023    
024    import java.util.concurrent.Callable;
025    
026    /**
027     * A {@code SubjectCallable} associates a {@link Subject Subject} with a target/delegate
028     * {@link Callable Callable} to ensure proper {@code Subject} thread-state management when the {@code Callable} executes.
029     * This ensures that any calls to {@code SecurityUtils.}{@link org.apache.shiro.SecurityUtils#getSubject() getSubject()}
030     * during the target {@code Callable}'s execution still work correctly even if the {@code Callable} executes on a
031     * different thread than the one that created it.  This allows {@code Subject} access during asynchronous operations.
032     * <p/>
033     * When instances of this class execute (typically via a {@link java.util.concurrent.ExecutorService ExecutorService}),
034     * the following occurs:
035     * <ol>
036     * <li>The specified Subject any of its associated thread state is first bound to the thread that executes the
037     * {@code Callable}.</li>
038     * <li>The delegate/target {@code Callable} is {@link java.util.concurrent.Callable#call() executed}</li>
039     * <li>The previous thread state that might have existed before the {@code Subject} was bound is fully restored</li>
040     * </ol>
041     * <p/>
042     * This behavior ensures that the thread that executes this {@code Callable}, which is often a different thread than
043     * the one that created the instance, retains a {@code Subject} to support {@code SecurityUtils.getSubject()}
044     * invocations. It also guarantees that the running thread remains 'clean' in any thread-pooled environments.
045     *
046     * <h3>Usage</h3>
047     *
048     * This is typically considered a support class and is not often directly referenced.  Most people prefer to use
049     * the {@code Subject.}{@link Subject#associateWith(Callable) associateWith} method, which will automatically return
050     * an instance of this class.
051     * <p/>
052     * An even more convenient alternative is to use a
053     * {@link org.apache.shiro.concurrent.SubjectAwareExecutorService SubjectAwareExecutorService}, which
054     * transparently uses instances of this class.
055     *
056     * @see Subject#associateWith(Callable)
057     * @see org.apache.shiro.concurrent.SubjectAwareExecutorService SubjectAwareExecutorService
058     * @since 1.0
059     */
060    public class SubjectCallable<V> implements Callable<V> {
061    
062        protected final ThreadState threadState;
063        private final Callable<V> callable;
064    
065        public SubjectCallable(Subject subject, Callable<V> delegate) {
066            this(new SubjectThreadState(subject), delegate);
067        }
068    
069        protected SubjectCallable(ThreadState threadState, Callable<V> delegate) {
070            if (threadState == null) {
071                throw new IllegalArgumentException("ThreadState argument cannot be null.");
072            }
073            this.threadState = threadState;
074            if (delegate == null) {
075                throw new IllegalArgumentException("Callable delegate instance cannot be null.");
076            }
077            this.callable = delegate;
078        }
079    
080        public V call() throws Exception {
081            try {
082                threadState.bind();
083                return doCall(this.callable);
084            } finally {
085                threadState.restore();
086            }
087        }
088    
089        protected V doCall(Callable<V> target) throws Exception {
090            return target.call();
091        }
092    }