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.subject.support;
020
021import org.apache.shiro.subject.Subject;
022import org.apache.shiro.util.ThreadState;
023
024import 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 */
060public 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}