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.subject.support; 20 21 import org.apache.shiro.subject.Subject; 22 import org.apache.shiro.util.ThreadState; 23 24 import java.util.concurrent.Callable; 25 26 /** 27 * A {@code SubjectCallable} associates a {@link Subject Subject} with a target/delegate 28 * {@link Callable Callable} to ensure proper {@code Subject} thread-state management when the {@code Callable} executes. 29 * This ensures that any calls to {@code SecurityUtils.}{@link org.apache.shiro.SecurityUtils#getSubject() getSubject()} 30 * during the target {@code Callable}'s execution still work correctly even if the {@code Callable} executes on a 31 * different thread than the one that created it. This allows {@code Subject} access during asynchronous operations. 32 * <p/> 33 * When instances of this class execute (typically via a {@link java.util.concurrent.ExecutorService ExecutorService}), 34 * the following occurs: 35 * <ol> 36 * <li>The specified Subject any of its associated thread state is first bound to the thread that executes the 37 * {@code Callable}.</li> 38 * <li>The delegate/target {@code Callable} is {@link java.util.concurrent.Callable#call() executed}</li> 39 * <li>The previous thread state that might have existed before the {@code Subject} was bound is fully restored</li> 40 * </ol> 41 * <p/> 42 * This behavior ensures that the thread that executes this {@code Callable}, which is often a different thread than 43 * the one that created the instance, retains a {@code Subject} to support {@code SecurityUtils.getSubject()} 44 * invocations. It also guarantees that the running thread remains 'clean' in any thread-pooled environments. 45 * 46 * <h3>Usage</h3> 47 * 48 * This is typically considered a support class and is not often directly referenced. Most people prefer to use 49 * the {@code Subject.}{@link Subject#associateWith(Callable) associateWith} method, which will automatically return 50 * an instance of this class. 51 * <p/> 52 * An even more convenient alternative is to use a 53 * {@link org.apache.shiro.concurrent.SubjectAwareExecutorService SubjectAwareExecutorService}, which 54 * transparently uses instances of this class. 55 * 56 * @see Subject#associateWith(Callable) 57 * @see org.apache.shiro.concurrent.SubjectAwareExecutorService SubjectAwareExecutorService 58 * @since 1.0 59 */ 60 public class SubjectCallable<V> implements Callable<V> { 61 62 protected final ThreadState threadState; 63 private final Callable<V> callable; 64 65 public SubjectCallable(Subject subject, Callable<V> delegate) { 66 this(new SubjectThreadState(subject), delegate); 67 } 68 69 protected SubjectCallable(ThreadState threadState, Callable<V> delegate) { 70 if (threadState == null) { 71 throw new IllegalArgumentException("ThreadState argument cannot be null."); 72 } 73 this.threadState = threadState; 74 if (delegate == null) { 75 throw new IllegalArgumentException("Callable delegate instance cannot be null."); 76 } 77 this.callable = delegate; 78 } 79 80 public V call() throws Exception { 81 try { 82 threadState.bind(); 83 return doCall(this.callable); 84 } finally { 85 threadState.restore(); 86 } 87 } 88 89 protected V doCall(Callable<V> target) throws Exception { 90 return target.call(); 91 } 92 }