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 }