View Javadoc

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  }