org.apache.shiro.subject.support
Class SubjectRunnable

java.lang.Object
  extended by org.apache.shiro.subject.support.SubjectRunnable
All Implemented Interfaces:
Runnable

public class SubjectRunnable
extends Object
implements Runnable

A SubjectRunnable ensures that a target/delegate Runnable will execute such that any call to SecurityUtils.getSubject() during the Runnable's execution will return the associated Subject instance. The SubjectRunnable instance can be run on any thread (the current thread or asynchronously on another thread) and the SecurityUtils.getSubject() call will still work properly. This implementation also guarantees that Shiro's thread state will be identical before and after execution to ensure threads remain clean in any thread-pooled environment.

When instances of this class run(), the following occurs:

  1. The Subject and any of its associated thread state is first bound to the thread that executes the Runnable.
  2. The delegate/target Runnable is run
  3. Any previous thread state that might have existed before the Subject was bound is fully restored

Usage

This is typically considered a support class and is not often directly referenced. Most people prefer to use the Subject.execute or Subject.associateWith methods, which transparently perform the necessary association logic.

An even more convenient alternative is to use a SubjectAwareExecutor, which transparently uses instances of this class but does not require referencing Shiro's API at all.

Since:
1.0
See Also:
Subject.associateWith(Runnable), SubjectAwareExecutor

Field Summary
protected  ThreadState threadState
           
 
Constructor Summary
  SubjectRunnable(Subject subject, Runnable delegate)
          Creates a new SubjectRunnable that, when executed, will execute the target delegate, but guarantees that it will run associated with the specified Subject.
protected SubjectRunnable(ThreadState threadState, Runnable delegate)
          Creates a new SubjectRunnable that, when executed, will perform thread state binding and guaranteed restoration before and after the Runnable's execution, respectively.
 
Method Summary
protected  void doRun(Runnable runnable)
          Simply calls the target Runnable's run() method.
 void run()
          Binds the Subject thread state, executes the target Runnable and then guarantees the previous thread state's restoration:
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

threadState

protected final ThreadState threadState
Constructor Detail

SubjectRunnable

public SubjectRunnable(Subject subject,
                       Runnable delegate)
Creates a new SubjectRunnable that, when executed, will execute the target delegate, but guarantees that it will run associated with the specified Subject.

Parameters:
subject - the Subject to associate with the delegate's execution.
delegate - the runnable to run.

SubjectRunnable

protected SubjectRunnable(ThreadState threadState,
                          Runnable delegate)
                   throws IllegalArgumentException
Creates a new SubjectRunnable that, when executed, will perform thread state binding and guaranteed restoration before and after the Runnable's execution, respectively.

Parameters:
threadState - the thread state to bind and unbind before and after the runnable's execution.
delegate - the delegate Runnable to execute when this instance is run().
Throws:
IllegalArgumentException - if either the ThreadState or Runnable arguments are null.
Method Detail

run

public void run()
Binds the Subject thread state, executes the target Runnable and then guarantees the previous thread state's restoration:
 try {
     threadState.bind();
     doRun(targetRunnable);
 } finally {
     threadState.restore()
 }
 

Specified by:
run in interface Runnable

doRun

protected void doRun(Runnable runnable)
Simply calls the target Runnable's run() method.

Parameters:
runnable - the target runnable to run.


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.